Configuring Displays Using a Transaction

Quartz Display Services makes it possible to configure a set of displays in a single transaction. During the execution of configuration changes, Quartz performs a standard fade effect on all online displays. The displays fade to a monochromatic color, the configuration takes place, and the displays return to normal. For more information about fade effects, see Using Fade Effects.

You begin a new transaction by calling CGBeginDisplayConfiguration. The next step is to declare what changes you want to make. For example, you can use these functions:

• CGConfigureDisplayWithDisplayMode sets the display mode of a display. (In OS X v10.5 use CGConfigureDisplayMode instead.)

• CGConfigureDisplayMirrorOfDisplay adds a display to a mirroring set.

• CGConfigureDisplayOrigin sets a display’s origin in global display space.

• CGConfigureDisplayFadeEffect customizes the fade effect. (Calling this function modifies the fade behavior for a single display configuration and has no permanent effect.)

After you’re finished preparing the transaction, you call CGCompleteDisplayConfiguration to execute it. In this call you also specify the scope of the configuration change. Typically, you specify kCGConfigureForAppOnly to apply the changes for the lifetime of your application.

Listing 1 shows how to use a configuration transaction with a custom fade effect to change the display mode of a single display for OS X v10.6 and later. For OS X v10.5 or earlier, see Listing 2 instead. A detailed explanation for each numbered line of code appears following the listings.

Listing 1  A simple configuration transaction (OS X v10.6 or later)

void MyDisplaySwitchToMode (CGDirectDisplayID display, CGDisplayModeRef mode)

{

    CGDisplayConfigRef config; // 1

    CGBeginDisplayConfiguration (&config); // 2

    CGConfigureDisplayWithDisplayMode (config, display, mode, NULL); // 3

    CGConfigureDisplayFadeEffect ( // 4

        config,

        0.6,    // fade out interval in seconds

        1.0,    // fade in interval

        0.5,    // red

        0.5,    // green

        0.5     // blue

    );

    CGCompleteDisplayConfiguration (config, kCGConfigureForAppOnly); // 5

}

Listing 2  A simple configuration transaction (OS X v 10.5)

void MyDisplaySwitchToMode (CGDirectDisplayID display, CFDictionaryRef mode)

{

    CGDisplayConfigRef config; // 1

    CGBeginDisplayConfiguration (&config); // 2

    CGConfigureDisplayMode (config, display, mode); // 3

    CGConfigureDisplayFadeEffect ( // 4

        config,

        0.6,    // fade out interval in seconds

        1.0,    // fade in interval

        0.5,    // red

        0.5,    // green

        0.5     // blue

    );

    CGCompleteDisplayConfiguration (config, kCGConfigureForAppOnly); // 5

}

Here’s what the code does:

1. Declares a display configuration object, a variable that provides a context for a set of display configuration changes.

2. Begins a new configuration transaction and passes back a display configuration object.

3. Declares the display mode change for this configuration.

4. Customizes the default fade effect for this configuration. The new fade color is gray.

5. Applies the new configuration with application scope. On return, the configuration object is no longer valid.