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

djay Pro 1.1 - Transform your Mac into a...
djay Pro provides a complete toolkit for performing DJs. Its unique modern interface is built around a sophisticated integration with iTunes and Spotify, giving you instant access to millions of... Read more
Vivaldi 1.0.118.19 - Lightweight browser...
Vivaldi browser. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind that users are... Read more
Stacks 2.6.11 - New way to create pages...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features: Fluid Layout: Stacks lets you build pages... Read more
xScope 4.1.3 - Onscreen graphic measurem...
xScope is powerful set of tools that are ideal for measuring, inspecting, and testing on-screen graphics and layouts. Its tools float above your desktop windows and can be accessed via a toolbar,... Read more
Cyberduck 4.7 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Labels & Addresses 1.7 - Powerful la...
Labels & Addresses is a home and office tool for printing all sorts of labels, envelopes, inventory labels, and price tags. Merge-printing capability makes the program a great tool for holiday... Read more
teleport 1.2.1 - Use one mouse/keyboard...
teleport is a simple utility to let you use one single mouse and keyboard to control several of your Macs. Simply reach the edge of your screen, and your mouse teleports to your other Mac! The... Read more
Apple iMovie 10.0.8 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
Box Sync 4.0.6233 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Fantastical 2.0.3 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more

SoundHound + LiveLyrics is Making its De...
SoundHound Inc. has announced that SoundHound + LiveLyrics, will be one of the first third-party apps to hit the Apple Watch. With  SoundHound you'll be able to tap on your watch and have the app recognize the music you are listening to, then have... | Read more »
Adobe Joins the Apple Watch Lineup With...
A whole tidal wave of apps are headed for the Apple Watch, and Adobe has joined in with 3 new ways to enhance your creativity and collaborate with others. The watch apps pair with iPad/iPhone apps to give you total control over your Adobe projects... | Read more »
Z Steel Soldiers, Sequel to Kavcom'...
Kavcom has released Z Steel Soldiers, which continues the story of the comedic RTS originally created by the Bitmap Brothers. [Read more] | Read more »
Seene Lets You Create 3D Images With You...
Seene, by Obvious Engineering, is a 3D capture app that's meant to allow you to create visually stunning 3D images with a tap of your finger, and then share them as a 3D photo, video or gif. [Read more] | Read more »
Lost Within - Tips, Tricks, and Strategi...
Have you just downloaded Lost Within and are you in need of a guiding hand? While it’s not the toughest of games out there you might still want some helpful tips to get you started. [Read more] | Read more »
Entertain Your Pet With Your Watch With...
The Petcube Camera is a device that lets you use live video to check in on your pet, talk to them, and play with them using a laser pointer - all while you're away. And the Petcube app is coming to the Apple Watch, so you'll be able to hang out with... | Read more »
Now You Can Manage Your Line2 Calls With...
You'll be able to get your Line2 cloud phone service on the Apple Watch very soon. The watch app can send and receive messages using hands-free voice dictation, or by selecting from a list of provided responses. [Read more] | Read more »
R.B.I. Baseball 15 (Games)
R.B.I. Baseball 15 1.01 Device: iOS Universal Category: Games Price: $4.99, Version: 1.01 (iTunes) Description: The legendary Major League Baseball franchise returns to the diamond. Make History. ** ALL iPOD Touch, the iPad 2 and the... | Read more »
Here's How You Can Tell if an App W...
The Apple Watch is pretty much here, and that means a whole lot of compatible apps and games are going to be updated or released onto the App Store. That's okay though, beacause Apple has quietly updated their app description pages to make things... | Read more »
Forgotten Memories : Alternate Realities...
Forgotten Memories : Alternate Realities 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: + REDUCED PRICE ONLY THE LAUNCHING WEEK + "The most exciting horror game of 2015." - AppSpy... | Read more »

Price Scanner via MacPrices.net

Intel Compute Stick: A New Mini-Computing For...
The Intel Compute Stick, a new pocket-sized computer based on a quad-core Intel Atom processor running Windows 8.1 with Bing, is available now through Intel Authorized Dealers across much of the... Read more
Heal to Launch First One-Touch House Call Doc...
Santa Monica, California based Heal, a pioneer in on-demand personal health care services — will offer the first one-touch, on-demand house call doctor app for the Apple Watch. Heal’s Watch app,... Read more
Mac Notebooks: Avoiding MagSafe Power Adapter...
Apple Support says proper usage, care, and maintenance of Your Mac notebook’s MagSafe power adapter can substantially increase the the adapter’s service life. Of course, MagSafe itself is an Apple... Read more
12″ Retina MacBook In Shootout With Air And P...
BareFeats’ rob-ART morgan has posted another comparison of the 12″ MacBook with other Mac laptops, noting that the general goodness of all Mac laptops can make which one to purchase a tough decision... Read more
FileMaker Go for iPad and iPhone: Over 1.5 Mi...
FileMaker has announced that its FileMaker Go for iPad and iPhone app has surpassed 1.5 million downloads from the iTunes App Store. The milestone confirms the continued popularity of the FileMaker... Read more
Sale! 13-inch 2.7GHz Retina MacBook Pro for $...
 Best Buy has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale for $1099 – $200 off MSRP. Choose free shipping or free local store pickup (if available). Price for online orders only, in-... Read more
Minimalist MacBook Confirms Death of Steve Jo...
ReadWrite’s Adriana Lee has posted a eulogy for the “Digital Hub” concept Steve Jobs first proposed back in 2001, declaring the new 12-inch MacBook with its single, over-subscribed USB-C port to be... Read more
13-inch 2.7GHz Retina MacBook Pro for $1234 w...
Adorama has the 13″ 2.7GHz/128GB Retina MacBook Pro in stock for $1234.99 ($65 off MSRP) including free shipping plus a free LG external DVD/CD optical drive. Adorama charges sales tax in NY & NJ... Read more
13-inch 2.5GHz MacBook Pro available for $999...
 Adorama has the 13-inch 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more

Jobs Board

*Apple* Support Technician IV - Jack Henry a...
Job Description Jack Henry & Associates is seeking an Apple Support Technician. This position while acting independently, ensures the proper day-to-day control of Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Service-Learning Counselor, *APPLE* Corps -...
…CONTRACT TITLE Higher Education Assistant FLSA Exempt CAMPUS SPECIFIC INFORMATION APPLE Corps (Academic Preparation Program for Law Enforcement), a partnership between Read more
*Apple* iOS Specialist - Kforce (United Stat...
Our client is seeking an Apple iOS Specialist to join their team in Quincy, Massachusetts (MA). Duties: * Responsible for configuration and distribution of desktop, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.