< Previous PageNext Page > Hide TOC

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:

• CGConfigureDisplayMode sets the display mode of a display.

• 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'll 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. A detailed explanation for each numbered line of code appears following the listing.

Listing 1  A simple configuration transaction

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.

< Previous PageNext Page > Hide TOC