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

Posterino 3.3.6 - Create posters, collag...
Posterino offers enhanced customization and flexibility including a variety of new, stylish templates featuring grids of identical or odd-sized image boxes. You can customize the size and shape of... Read more
Together 3.8.3 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
iClock Pro 3.4.9 - Customize your menuba...
iClock Pro is a menu bar replacement clock for Apple's default clock. iClock Pro is an update, total rewrite and improvement to the popular iClock. Have the day, date and time in different fonts and... Read more
Things 2.8.12 - Elegant personal task ma...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
Typinator 7.2 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Spotify 1.0.53.758. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
beaTunes 4.6.14 - Organize your music co...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
Vienna 3.1.10 :d05d7a5d: - RSS and Atom...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
Day One 2.1.8 - Maintain a daily journal...
Day One is the easiest and best-looking way to use a journal / diary / text-logging application for the Mac. Day One is well designed and extremely focused to encourage you to write more through... Read more
iDefrag 5.1.8 - Disk defragmentation and...
iDefrag helps defragment and optimize your disk for improved performance. Features include: Supports HFS and HFS+ (Mac OS Extended). Supports case sensitive and journaled filesystems. Supports... Read more

Latest Forum Discussions

See All

Fantasy MMORPG MU Origin adds new modes,...
MU Origin, Webzen’s highly popular fantasy MMORPG is getting ready to shake things up for the second time this year, as a new update makes its way to the Google Play and App Store from today. Introducing new systems, modes, and events, the land of... | Read more »
Blizzard is looking to hire a mobile dev...
A new thread on the popular video game rumor forum, NeoGAF, uncovered an interesting job listing over at Blizzard Entertainment. It appears the studio behindStarCraft, World of WarCraft, Hearthstone,andOverwatch is looking to bring on a new hire... | Read more »
Legend of Zelda meets Cooking Mama in ne...
Dungeon Chef is what happens when you mix the RPG elements (and style) of a Legend of Zelda game, with cooking elements. Although, now that The Legend of Zelda: Breath of the Wild also has cookingelements, so maybe the gameplay is not so novel.... | Read more »
ChordFlow (Music)
ChordFlow 1.0.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0.0 (iTunes) Description: ChordFlow is a chord sequencer with a unique 4-track polyphonic arpeggiator, extensive chord library, MIDI out and Ableton Link... | Read more »
The Walking Dead: A New Frontier is out...
The newest season of Telltale Games'The Walking Dead is well underway. After the release of the third episode, "Above the Law" about a month ago, episode four, "Thicker Than Water" is hot and ready for more zombies and gut-wrenching emotional... | Read more »
Best games we played this week
Another week, another new wave of mobile games do dive into. We've dug through the list of apps that came out this week to tell you which apps are worth your sweet time. And while there weren't too many games this week, there were some big ones.... | Read more »
Vignettes (Games)
Vignettes 1.0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1 (iTunes) Description: Vignettes is a casual but unique exploration game without text or characters, where objects shapeshift as you spin them around... | Read more »
Get Me Outta Here is an 80s retro shoote...
Are you ready to fight some aliens? Because Crescent Moon Games has released the retro shooter Get Me Outta Here on iOS devices today. [Read more] | Read more »
Get a bunch of Apple productivity apps f...
If you're an Apple Mac owner, you're probably aware of the host of Apple productivity apps the company includes in all new Mac purchases. Apps like iMovie, Keynote, and of course, GarageBand. While you used to be able to also buy these apps... | Read more »
Terra Mystica (Games)
Terra Mystica 1.03 Device: iOS Universal Category: Games Price: $9.99, Version: 1.03 (iTunes) Description: Short Summary:≈≈≈≈≈≈≈≈≈≈≈≈≈ | Read more »

Price Scanner via MacPrices.net

DEVONthink To Go 2.1.3 For iOS Adds New Declu...
DEVONtechnologies has updated DEVONthink To Go, its iOS companion to DEVONthink for Mac. Enhancements and bug fixes in Version 2.1.3 include DEVONtechnologies’ new decluttering service for clipping... Read more
Use Apple’s Education discount to save up to...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
Apple refurbished Apple Watches available sta...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
15-inch Touch Bar MacBook Pros, Apple refurbi...
Apple is offering Certified Refurbished 2016 15″ Touch Bar MacBook Pros for $360 to $420 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2.6GHz... Read more
13-inch MacBook Airs on sale for up to $150 o...
Overstock.com has 13″ MacBook Airs on sale for up to $150 off MSRP including free shipping: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $869.99 $130 off MSRP - 13″ 1.6GHz/256GB MacBook Air (sku... Read more
15-inch Touch Bar MacBook Pros on sale for $1...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
15-inch 2.7GHz Touch Bar MacBook Pros on sale...
Amazon has 2016 15″ 2.7GHz Apple Touch Bar MacBook Pros in stock today and on sale for $150-$200 off MSRP. Shipping is free: - 15″ 2.7GHz Touch Bar MacBook Pro Space Gray (sku MLH42LL/A): $2599 $200... Read more
Apple now offering Certified Refurbished 13-i...
Apple is now offering Certified Refurbished 2016 13″ Touch Bar MacBook Pros for $270-$300 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.9GHz... Read more
MyGiHealth Digestive Symptom Tracker Version...
My Total Health, Inc. has announced the release of MyGiHealth 2.1, an important update to their digestive symptom tracker developed exclusively for iPhone, iPad and iPod touch devices. MyGiHealth is... Read more
Galaxy S8 Materials Costs Highest by Far Comp...
The new Samsung Galaxy S8 equipped with 64 gigabytes (GB) of NAND flash memory carries a bill of materials (BOM) cost that comes out to US$301.60, much higher than for previous versions of the... Read more

Jobs Board

*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Music Marketing Lead, iTunes & *Apple*...
# Music Marketing Lead, iTunes & Apple Music Job Number: 56868140 Culver City, California, United States Posted: Apr. 17, 2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Media Products - Commerce Engineerin...
Apple Media Products - Commerce Engineering Manager Job Number: 57037480 Santa Clara Valley, California, United States Posted: Apr. 18, 2017 Weekly Hours: 40.00 Job Read more
*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.