TweetFollow Us on Twitter

March 96 - GRAPHICAL TRUFFLES: The Display Manager

GRAPHICAL TRUFFLES: The Display Manager

Mike Marinkovich

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.

MORE FUNCTIONS, LESS CODE

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.

  • If kNoSwitchConfirmBit isn't set, the requested mode is an optional mode and is only shown in the mode list of the Monitors control panel when the Option key is pressed (an optional mode requires confirmation from the user before it's allowed).

  • kDepthNotAvailableBit indicates whether the requested pixel depth is available with the requested display mode.
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.

  • If you set failToMain to true and the routine can't find what it's looking for (either the graphics device or the display ID), the routine returns information about the main graphics device rather than returning an error.

  • If you set failToMain to false and the routine can't find what it's looking for, it will return kDMDisplayNotFoundErr. (For example, when a PowerBook goes to sleep, the display might be removed.)

KEEPING UP WITH THE CHANGES

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:

  • keyDisplayOldConfig, which is a record of the display's previous state

  • keyDisplayNewConfig, which is a record of the display's current state
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;
}

WHAT TO DO NOW

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.*

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

pwSafe 4.1 - Secure password management...
pwSafe provides simple and secure password management across devices and computers. pwSafe uses iCloud to keep your password databases backed-up and synced between Macs and iOS devices. It is... Read more
Kodi 15.0.rc1 - Powerful media center to...
Kodi (was XBMC) is an award-winning free and open-source (GPL) software media player and entertainment hub that can be installed on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user... Read more
Coda 2.5.11 - One-window Web development...
Coda is a powerful Web editor that puts everything in one place. An editor. Terminal. CSS. Files. With Coda 2, we went beyond expectations. With loads of new, much-requested features, a few surprises... Read more
Bookends 12.5.7 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Access the power of Bookends directly from Mellel, Nisus Writer Pro, or MS Word (... Read more
Maya 2016 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
RapidWeaver 6.2.3 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
MacFamilyTree 7.5.2 - Create and explore...
MacFamilyTree gives genealogy a facelift: it's modern, interactive, incredibly fast, and easy to use. We're convinced that generations of chroniclers would have loved to trade in their genealogy... Read more
Paragraphs 1.0.1 - Writing tool just for...
Paragraphs is an app just for writers. It was built for one thing and one thing only: writing. It gives you everything you need to create brilliant prose and does away with the rest. Everything in... Read more
BlueStacks App Player 0.9.21 - Run Andro...
BlueStacks App Player lets you run your Android apps fast and fullscreen on your Mac. Version 0.9.21: Note: Now requires OS X 10.8 or later running on a 64-bit Intel processor. Initial stable... Read more
Tweetbot 2.0.2 - Popular Twitter client....
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more

Rage of Bahamut is Giving Almost All of...
The App Store isn't what it used to be back in 2012, so it's not unexpected to see some games changing their structures with the times. Now we can add Rage of Bahamut to that list with the recent announcement that the game is severely cutting back... | Read more »
Adventures of Pip (Games)
Adventures of Pip 1.0 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ** ONE WEEK ONLY — 66% OFF! *** “Adventures of Pip is a delightful little platformer full of charm, challenge and impeccable... | Read more »
Divide By Sheep - Tips, Tricks, and Stre...
Who would have thought splitting up sheep could be so involved? Anyone who’s played Divide by Sheep, that’s who! While we’re not about to give you complete solutions to everything (because that’s just cheating), we will happily give you some... | Read more »
NaturalMotion and Zynga Have Started Tea...
An official sequel to 2012's CSR Racing is officially on the way, with Zynga and NaturalMotion releasing a short teaser trailer to get everyone excited. Well, as excited as one can get from a trailer with no gameplay footage, anyway. [Read more] | Read more »
Grab a Friend and Pick up Overkill 3, Be...
Overkill 3 is a pretty enjoyable third-person shooter that was sort of begging for some online multiplayer. Fortunately the begging can stop, because its newest update has added an online co-op mode. [Read more] | Read more »
Scanner Pro's Newest Update Adds Au...
Scanner Pro is one of the most popular document scanning apps on iOS, thanks in no small part to its near-constant updates, I'm sure. Now we're up to update number six, and it adds some pretty handy new features. [Read more] | Read more »
Heroki (Games)
Heroki 1.0 Device: iOS Universal Category: Games Price: $7.99, Version: 1.0 (iTunes) Description: CLEAR THE SKIES FOR A NEW HERO!The peaceful sky village of Levantia is in danger! The dastardly Dr. N. Forchin and his accomplice,... | Read more »
Wars of the Roses (Games)
Wars of the Roses 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
TapMon Battle (Games)
TapMon Battle 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: It's time to battle!Tap! Tap! Tap! Try tap a egg to hatch a Tapmon!Do a battle with another tapmons using your hatched tapmons! *... | Read more »
Alchemic Dungeons (Games)
Alchemic Dungeons 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: ### Release Event! ### 2.99$->0.99$ for limited time! ### Roguelike Role Playing Game! ### Alchemic Dungeons is roguelike... | Read more »

Price Scanner via MacPrices.net

Canon PIXMA MG3620 Wireless Inkjet All-in-One...
Canon U.S.A., Inc. has announced the PIXMA MG3620 Wireless (1) Inkjet All-in-One (AIO) printer for high-quality photo and document printing. Built with convenience in mind for the everyday home user... Read more
July 4th Holiday Weekend 13-inch MacBook Pro...
Save up to $150 on the purchase of a new 2015 13″ Retina MacBook Pro at the following resellers this weekend. Shipping is free with each model: 2.7GHz/128GB MSRP $1299 2.7GHz/... Read more
27-inch 3.5GHz 5K iMac on sale for $2149, sav...
Best Buy has the 27″ 3.5GHz 5K iMac on sale for $2149.99. Choose free shipping or free local store pickup (if available). Sale price for online orders only, in-store prices may vary. Their price is $... Read more
Apple now offering refurbished 2015 11-inch...
The Apple Store is now offering Apple Certified Refurbished 2015 11″ MacBook Airs as well as 13″ MacBook Airs (the latest models), available for up to $180 off the cost of new models. An Apple one-... Read more
15-inch 2.5GHz Retina MacBook Pro on sale for...
Amazon.com has the 15″ 2.5GHz Retina MacBook Pro on sale for $2274 including free shipping. Their price is $225 off MSRP, and it’s the lowest price available for this model. Read more
Finally Safe To Upgrade To Yosemite’?
The reason I’ve held back from upgrading my MacBook Air from OS X 10.9 Mavericks to 10.10 Yosemite for nearly a year isn’t just procrastination. Among other bugs reported, there have been persistent... Read more
Logo Pop Free Vector Logo Design App For OS X...
128bit Technologies has released of Logo Pop Free 1.2 for Mac OS X, a vector based, full-fledged, logo design app available exclusively on the Mac App Store for the agreeable price of absolutely free... Read more
21-inch 1.4GHz iMac on sale for $999, save $1...
B&H Photo has new 21″ 1.4GHz iMac on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Best Buy has the 21″ 1.4GHz iMac on sale for $999.99 on their... Read more
16GB iPad mini 3 on sale for $339, save $60
B&H Photo has the 16GB iPad mini 3 WiFi on sale for $339 including free shipping plus NY tax only. Their price is $60 off MSRP. Read more
Save up to $40 on iPad Air 2, NY tax only, fr...
B&H Photo has iPad Air 2s on sale for up to $40 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $489 $10 off - 64GB iPad Air 2 WiFi: $559 $40 off - 128GB iPad Air... Read more

Jobs Board

*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
Program Manger, WW *Apple* Direct Fulfillme...
**Job Summary** We are seeking a business analyst to work within our Worldwide Apple Direct Fulfillment Operations team. This role will work closely with related program Read more
Project Manager, *Apple* Retail New Store O...
**Job Summary** An Apple Retail New Store Openings & Remodels Project Manager is responsible for successfully managing the openings, remodels, and small works of Read more
Technical Project Manager - *Apple* Pay - A...
**Job Summary** Apple Pay is seeking an experienced technical PM to…manage the on boarding of new merchants for the Apple Pay platform in the US Within this role you Read more
*Apple* Pay- Automation Test Engineer - Appl...
**Job Summary** At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring passion and dedication to your job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.