A major change is taking place on the screen, which your application might not even
know about! With the help of the Display Manager, the user can use the Monitors
control panel to rearrange displays, make resolution switches, add or remove a
display, and move the menu bar from one display to another -- all without rebooting.
However, the ease of changing a display for the user poses new challenges for the
developer if an application relies on a graphics device's bounding rectangle to position,
zoom, and grow its windows.
To meet this challenge, the Display Manager provides several new functions that make
it easier to gather information about the display environment and implement changes.
I'll describe some of the more commonly used functions in this column. I'll also discuss
how to use a notification event to find out when a display has changed (an example is
included on this issue's CD).
Two versions of the Display Manager are currently implemented in the system
software. The information in this column applies to both versions. Display Manager
version 1.0 is available on all PowerPC(TM) processor-based Macintosh computers
and Color QuickDraw-capable Macintosh computers running System 7.5. Display
Manager 2.0 is available on PCI-based computers running System 7.5.2. To determine
whether the Display Manager is available, call Gestalt with the selector
gestaltDisplayMgrAttr and check the gestaltDisplayMgrPresent bit of the response. To
determine which version you have, call Gestalt with the selector
gestaltDisplayMgrVers.
The Display Manager includes several new functions that greatly simplify tasks that
used to take a lot of code. For example, many applications need to query screen devices
for bounding rectangles, pixel depths, and a variety of other things. Prior to the
Display Manager, an application could use the GetDeviceList function to retrieve the
first graphics device record in the device list and call GetNextDevice for subsequent
devices in the list. The application would then need to use the Device Manager to
determine whether the device was a screen device and whether it was active. With the
Display Manager, you can do all this with two functions: DMGetFirstScreenDevice and
DMGetNextScreenDevice.
GDHandle aDevice;
aDevice =
DMGetFirstScreenDevice(dmOnlyActiveDisplays);
while (aDevice != nil) {
// Do something with the device.
...
// Get the next device in the list.
aDevice = DMGetNextScreenDevice(aDevice,
dmOnlyActiveDisplays);
}
The Display Manager also introduces two functions that make it easier to retrieve
information about the attached displays and to change their characteristics:
DMCheckDisplayMode and DMSetDisplayMode.
DMCheckDisplayMode determines whether a specific display mode and pixel depth are
supported by the supplied graphics device. (A display mode is a combination of several
interrelated display characteristics, such as resolution and scan timing.) This
function has two output parameters: modeOk and switchFlags. If the Boolean modeOk
parameter is true, the screen device supports the requested display mode. The
switchFlags parameter contains two flag bits that should be checked with the constants
kNoSwitchConfirmBit and kDepthNotAvailableBit.
Once your application knows that the requested display mode and pixel depth are
available, you can use the DMSetDisplayMode function to reconfigure the video display.
If you pass 0 for the mode parameter, the Display Manager uses the device's current
display mode.
If you like to change the display mode and pixel depth often, you can save the
configuration and retrieve it at startup with the DMSaveScreenPrefs function. This
function requires three parameters, which all take the value of NULL since they're
private to the Display Manager. (Go figure.)
Identifying displays. Many of the Display Manager functions require a display ID
(type DisplayIDType) as a parameter. A display ID is a long integer that uniquely
identifies a screen display. Affiliating a display ID with a graphics device can be useful
in cases where the graphics device might change or isn't available. You can obtain a
display ID with the function DMGetDisplayIDByGDevice, which requires a graphics
device as a parameter. Or you can retrieve the graphics device corresponding to a
given display ID by calling DMGetGDeviceByDisplayID. Both functions require the
Boolean parameter failToMain.
Now that the user is able to change a screen display without restarting, your
application may want to reposition and resize its windows, update internal
display-related data structures, or update nonstandard window definitions on the fly.
If desired, the Display Manager can automatically adjust the positions of the windows
that were onscreen before the change to keep them onscreen after the change, but it
may not put them in the best possible positions. However, if you want to reposition and
resize your windows yourself, you need to set the isDisplayManagerAware flag in your
application's SIZE resource and install a callback procedure or an Apple event handler
in your application so that you'll know when a display has changed.
Your application registers a callback procedure with the Display Manager function
DMRegisterNotifyProc. The display notification procedure takes a Display Notice Apple
event parameter describing the changes that were made to the display. The notification
callback is especially useful for control panels and other instances where high-level
event handling in an event loop isn't possible. Another benefit of the notification
callback is that your application is informed on a more timely basis than through a
high-level event, thus giving the appearance of seamless integration with the Display
Manager.
If you're using Display Manager 1.0, you're not notified about depth
changes, and A5 isn't restored when you receive the notification callback.*
You can also receive and process Display Notice events through an Apple event handler.
Display Notice event handlers are installed like any other Apple event handlers, with
the AEInstallEventHandler function:
err = AEInstallEventHandler(kCoreEventClass, kAESystemConfigNotice, NewAEEventHandlerProc(DoAEDisplayConfigChange), 0, false);
To enable high-level events in your application, you need to set the
isHighLevelEventAware flag in the SIZE resource. (You'll also need to support the
required Apple events described in Inside Macintosh: Interapplication
Communication.)
Whether your application uses a notification callback or a high-level event handler, a
Display Notice Apple event is passed to your routine. You can obtain a list of descriptor
records (an AEDescList) from the Display Notice event with the AEGetParamDesc
function. Each descriptor record holds two additional keyword-specific descriptor
records:
You can obtain these records one at a time with the function AEGetNthDesc.
To move and resize your application's windows, you need to know which graphics
device was affected, the old and new bounding rectangles of the device, and possibly the
pixel depth. All the information about the affected graphics device can be obtained from
the descriptor list with keyword-specific descriptor constants, which are defined in
the Displays.h universal header file. You call AEGetKeyPtr with the various descriptor
constants to extract the information you need. In particular, the constant
keyDeviceRect extracts the bounding rectangle, and keyDisplayID extracts the display
ID. As previously mentioned, you can convert a display ID to a graphics device with the
function DMGetGDeviceByDisplayID.
Listing 1 shows an example of what to do after receiving a Display Notice event from a
notification callback or a high-level event handler.
Listing 1. Handling the Display Notice event
OSErr HandleNotification(AppleEvent *event)
{
OSErr err;
GrafPtr oldPort;
AEDescList displayList, aDisplay;
AERecord oldConfig, newConfig;
AEKeyword tempWord;
DisplayIDType displayID;
unsigned long returnType;
long count;
Rect oldRect, newRect;
GetPort(&oldPort);
// Get a list of the displays from the Display Notice Apple event.
err = AEGetParamDesc(event, kAEDisplayNotice, typeWildCard,
&DisplayList);
// How many items in the list?
err = AECountItems(&displayList, &count);
while (count > 0) {
// Loop through the list.
err = AEGetNthDesc(&displayList, count, typeWildCard,
&tempWord, &aDisplay);
// Get the old rect.
err = AEGetNthDesc(&aDisplay, 1, typeWildCard, &tempWord,
&oldConfig);
err = AEGetKeyPtr(&oldConfig, keyDeviceRect, typeWildCard,
&returnType, &oldRect, 8, nil);
// Get the display ID so that we can get the GDevice later.
err = AEGetKeyPtr(&oldConfig, keyDisplayID, typeWildCard,
&returnType, &displayID, 8, nil);
// Get the new rect.
err = AEGetNthDesc(&aDisplay, 2, typeWildCard, &tempWord,
&newConfig);
err = AEGetKeyPtr(&newConfig, keyDeviceRect, typeWildCard,
&returnType, &newRect, 8, nil);
// If the new and old rects are not the same, we can assume
// that the GDevice has changed, and the windows need to be
// rearranged.
if (err == noErr && !EqualRect(&newRect, &oldRect))
HandleDeviceChange(displayID, &newRect);
count--;
err = AEDisposeDesc(&aDisplay);
err = AEDisposeDesc(&oldConfig);
err = AEDisposeDesc(&newConfig);
}
err = AEDisposeDesc(&displayList);
SetPort(oldPort);
return err;
}
The sample code on this issue's CD should provide a starting point for how to handle
display notification events in your application. Additional documentation and sample
code for the Display Manager are provided in the Display Manager Development Kit,
which is also on the CD.
The Mac OS Software Developer's Kit incudes the Display Manager
Development Kit along with a lot of other development software. The Mac
OSSDK is now part of the Developer CD Series (included in the Apple
Developer Mailing, which is available through the Apple Developer Catalog).*
To learn more about what the Display Manager can do for you, you should also take a
look at the Displays.h universal header file.
Now there's no excuse for your application to be in the dark about changes taking place
on the screen. So why not keep your users happy and take advantage of the help that the
Display Manager can give you?
MIKE MARINKOVICH (marink@apple.com) is a member of the Printing, Imaging,
and Graphics (PIGS) group in Developer Technical Support at Apple. He's been whiling
away his days (and many of his evenings) coming to grips with the Display Manager
and other QuickDraw-related esoterica. When not indulging in his hobby, which also
happens to be playing around with the Toolbox and programming his Macintosh, Mike
spends his time exploring the San Francisco Bay Area in his trusty Subaru. Mike's
from Seattle and misses the rain.*
Thanks to Eric Anderson, David Hayward, and Ian Hendry for reviewing this column.*