Legacy Document

Important: The Display Manager is deprecated in Mac OS X version 10.4 and later. The replacement is Quartz Display Services, a modern Mac OS X API that provides similar functionality. For more information, see Quartz Display Services Reference.

Display Manager Reference (Not Recommended)

Framework	Carbon/Carbon.h
Declared in	Displays.h

Overview

In Mac OS 9 and earlier, the Display Manager allowed users to dynamically change the arrangement and display modes of the monitors attached to their computers. The Display Manager was included in Carbon to facilitate the porting of legacy applications to Mac OS X. You should not use Display Manager functions in new application development. Instead, you should use Quartz Display Services.

Functions by Task

Adding and Removing Video Devices From the Device List

Changing Display Modes and Display Configurations

Determining Display Modes and Display Configurations

Getting Video Devices

Registering and Unregistering Your Program

Working With Universal Procedure Pointers for Display Manager Callbacks

Miscellaneous

Callbacks

DMComponentListIteratorProcPtr

typedef void (*DMComponentListIteratorProcPtr)
(
   void * userData,
   DMListIndexType itemIndex,
   DMComponentListEntryPtr componentInfo
);

If you name your function MyDMComponentListIteratorProc, you would declare it like this:

void MyDMComponentListIteratorProc (
   void * userData,
   DMListIndexType itemIndex,
   DMComponentListEntryPtr componentInfo
);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayListIteratorProcPtr

typedef void (*DMDisplayListIteratorProcPtr)
(
   void * userData,
   DMListIndexType itemIndex,
   DisplayListEntryPtr displaymodeInfo
);

If you name your function MyDMDisplayListIteratorProc, you would declare it like this:

void MyDMDisplayListIteratorProc (
   void * userData,
   DMListIndexType itemIndex,
   DisplayListEntryPtr displaymodeInfo
);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayModeListIteratorProcPtr

Defines a pointer to a list iterator callback function.

typedef void (*DMDisplayModeListIteratorProcPtr)
(
   void * userData,
   DMListIndexType itemIndex,
   DMDisplayModeListEntryPtr displaymodeInfo
);

If you name your function MyDMDisplayModeListIteratorProc, you would declare it like this:

void MyDMDisplayModeListIteratorProc (
   void * userData,
   DMListIndexType itemIndex,
   DMDisplayModeListEntryPtr displaymodeInfo
);

Parameters

userData: A pointer to data about mode changes provided by the user.
itemIndex: Specifies the list entry. See DMListIndexType for more information. This is the index passed into DMGetIndexedDisplayModeFromList.
displaymodeInfo: A pointer to a structure of type DMDisplayModeListEntryRec that provides display mode information.

Discussion

The function DMGetIndexedDisplayModeFromList uses this callback function to retrieve and return information about a display mode to the caller of DMGetIndexedDisplayModeFromList.

When you implement this function, the pointer you pass to the DMGetIndexedDisplayModeFromList function should be a universal procedure pointer with the following type definition:

typedef (DMDisplayModeListIteratorProcPtr)             DMDisplayModeListIteratorUPP;

To create a universal procedure pointer for your application-defined function, you should use the NewDMDisplayModeListIteratorUPP function as follows:

DMDisplayModeListIteratorUPP MyDMDisplayModeListIteratorUPP;

MyDMDisplayModeListIteratorUPP = NewDMDisplayModeListIteratorUPP  (&MyDMDisplayModeListIteratorCallback)

You can then pass MyDMDisplayModeListIteratorUPP in the listIterator parameter of the DMGetIndexedDisplayModeFromList function. When you no longer need the list iterator, you should dispose of the UPP using the DisposeDMDisplayModeListIteratorUPP function:

DisposeDMDisplayModeListIteratorUPP (

    MyDMDisplayModeListIteratorUPP);

Using this call ensures that the call is made through a universal procedure pointer.

Special Considerations

Because this function may move or purge memory blocks or access handles, you cannot call it at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMExtendedNotificationProcPtr

Defines a pointer to an extended notification callback function.

typedef void (*DMExtendedNotificationProcPtr)
(
   void * userData,
   short theMessage,
   void * notifyData
);

If you name your function MyDMExtendedNotificationProc, you would declare it like this:

void MyDMExtendedNotificationProc (
   void * userData,
   short theMessage,
   void * notifyData
);

Parameters

userData: A pointer you passed into DMRegisterExtendedNotifyProc.
theMessage: A message selector. See “Notification Messages” for information on specific message selectors.
notifyData: A pointer to message-specific information data provided by the the Display Manager, described in “Notification Messages.”

Discussion

Display Manager notification functions use this callback function when your application needs to know when certain events have occurred. The system software may implement these events or follow a user action. When these events occur, the Display Manager will send notification messages to registrants.

When you call the function DMRegisterExtendedNotifyProc you designate an application-defined function to handle the extended notification procedure.

When you implement this function, the pointer you pass to the DMRegisterExtendedNotifyProc function should be a universal procedure pointer with the following type definition:

typedef (DMExtendedNotificationProcPtr)             DMExtendedNotificationUPP;

To create a universal procedure pointer for your application-defined function, you should use the NewDMExtendedNotificationProc macro as follows:

DMExtendedNotificationUPP  MyExtendedNotificationUPP;

MyExtendedNotificationUPP = NewDMExtendedNotificationProc  (MyExtendedNotificationCallback);

You can then pass MyExtendedNotificationUPP in the notifyProc parameter of the DMRegisterExtendedNotifyProc function. When you no longer need notifications, you should remove it using the DMRemoveExtendedNotifyProc function. You sould also dispose of the UPP using the DisposeDMExtendedNotificationUPP function:

DisposeDMExtendedNotificationUPP(MyExtendedNotificationUPP);

Using this call ensures that the call is made through a universal procedure pointer.

Special Considerations

Because this function may move or purge memory blocks or access handles, you cannot call it at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMNotificationProcPtr

typedef void (*DMNotificationProcPtr)
(
   AppleEvent * theEvent
);

If you name your function MyDMNotificationProc, you would declare it like this:

void MyDMNotificationProc (
   AppleEvent * theEvent
);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMProfileListIteratorProcPtr

typedef void (*DMProfileListIteratorProcPtr)
(
   void * userData,
   DMListIndexType itemIndex,
   DMProfileListEntryPtr profileInfo
);

If you name your function MyDMProfileListIteratorProc, you would declare it like this:

void MyDMProfileListIteratorProc (
   void * userData,
   DMListIndexType itemIndex,
   DMProfileListEntryPtr profileInfo
);

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

Data Types

AVLocationRec

struct AVLocationRec {
   unsigned long locationConstant;
};
typedef struct AVLocationRec AVLocationRec;
typedef AVLocationRec * AVLocationPtr;

Fields

locationConstant: Reserved for future expansion. Set this field to zero.

Discussion

The function DMGetGraphicInfoByAVID uses the AVLocationRec structure to get information about graphic displays.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

AVPowerStatePtr

typedef VDPowerStateRec * AVPowerStatePtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

AVPowerStateRec

typedef VDPowerStateRec AVPowerStateRec;

Discussion

The functions DMGetAVPowerState and DMSetAVPowerState contain a parameter of type AVPowerStatePtr, which is a pointer to the AVPowerStateRec data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DependentNotifyRec

struct DependentNotifyRec {
   ResType notifyType;
   ResType notifyClass;
   DisplayIDType notifyPortID;
   ComponentInstance notifyComponent;
   unsigned long notifyVersion;
   unsigned long notifyFlags;
   unsigned long notifyReserved;
   unsigned long notifyFuture;
};
typedef struct DependentNotifyRec DependentNotifyRec;
typedef DependentNotifyRec * DependentNotifyPtr;

Fields

notifyType: A value that specifies the type of engine, if any, that made the change. The Display Manager may set this field to zero.
notifyClass: A value specifying the class of change that occurred: for instance, color or screen size. This field uses a value supplied by the constant described under “Dependent Notification Constants” to specify the class of change that has occurred in a dependent display.
notifyPortID: Specifies which device was touched (kInvalidDisplayID specifies all or none).
notifyComponent: A value that indentifies the engine that made the change. The Display Manager may set this field to zero.
notifyVersion: Reserved for future expansion. The Display Manager sets this field to zero.
notifyFlags: Reserved for future expansion. The Display Manager sets this field to zero.
notifyReserved: Reserved for future expansion. The Display Manager sets this field to zero.
notifyFuture: Reserved for future expansion. The Display Manager sets this field to zero.

Discussion

The function DMSendDependentNotification uses the notifyType and notifyClass fields of the DependentNotifyRec structure.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DisplayListEntryRec

struct DisplayListEntryRec {
   GDHandle displayListEntryGDevice;
   DisplayIDType displayListEntryDisplayID;
   UInt32 displayListEntryIncludeFlags;
   UInt32 displayListEntryReserved1;
   UInt32 displayListEntryReserved2;
   UInt32 displayListEntryReserved3;
   UInt32 displayListEntryReserved4;
   UInt32 displayListEntryReserved5;
};
typedef struct DisplayListEntryRec DisplayListEntryRec;
typedef DisplayListEntryRec * DisplayListEntryPtr;

Fields

displayListEntryGDevice: A value of type GDHandle.
displayListEntryDisplayID: A value of type DisplayIDType that specifies the display ID.
displayListEntryIncludeFlags: A value of type UInt32 that specifies the reason this entry was included.
displayListEntryReserved1: Reserved for future expansion. Set this field to zero.
displayListEntryReserved2: Reserved for future expansion. Set this field to zero.
displayListEntryReserved3: Reserved for future expansion. Set this field to zero.
displayListEntryReserved4: Reserved for future expansion. Set this field to zero.
displayListEntryReserved5: Reserved for future expansion. Set this field to zero.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMComponentListEntryRec

struct DMComponentListEntryRec {
   DisplayIDType itemID;
   Component itemComponent;
   ComponentDescription itemDescription;
   ResType itemClass;
   DMFidelityType itemFidelity;
   ResType itemSubClass;
   Point itemSort;
   unsigned long itemFlags;
   ResType itemReserved;
   unsigned long itemFuture1;
   unsigned long itemFuture2;
   unsigned long itemFuture3;
   unsigned long itemFuture4;
};
typedef struct DMComponentListEntryRec DMComponentListEntryRec;
typedef DMComponentListEntryRec * DMComponentListEntryPtr;

Fields

itemID
itemComponent
itemDescription
itemClass
itemFidelity
itemSubClass
itemSort: Reserved for future expansion. Set this field to zero.
itemFlags: Reserved for future expansion. Set this field to zero.
itemReserved
itemFuture1: Reserved for future expansion. Set this field to zero.
itemFuture2: Reserved for future expansion. Set this field to zero.
itemFuture3: Reserved for future expansion. Set this field to zero.
itemFuture4: Reserved for future expansion. Set this field to zero.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMComponentListIteratorUPP

typedef DMComponentListIteratorProcPtr DMComponentListIteratorUPP;

Discussion

For more information, see the description of the DMComponentListIteratorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDepthInfoBlockRec

struct DMDepthInfoBlockRec {
   unsigned long depthBlockCount;
   DMDepthInfoPtr depthVPBlock;
   unsigned long depthBlockFlags;
   unsigned long depthBlockReserved1;
   unsigned long depthBlockReserved2;
};
typedef struct DMDepthInfoBlockRec DMDepthInfoBlockRec;
typedef DMDepthInfoBlockRec * DMDepthInfoBlockPtr;

Fields

depthBlockCount: Specifies the number of mode depths available.
depthVPBlock: Array of DMDepthInfoRec.
depthBlockFlags: Reserved for future expansion.
depthBlockReserved1: Reserved for future expansion.
depthBlockReserved2: Reserved for future expansion.

Discussion

When you call the function DMGetIndexedDisplayModeFromList , the Display Manager passes a pointer to a DMDisplayModeListEntryRec structure to your application. Its field displayModeDepthBlockInfo is a pointer to a DMDepthInfoBlockRec structure.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDepthInfoRec

struct DMDepthInfoRec {
   VDSwitchInfoPtr depthSwitchInfo;
   VPBlockPtr depthVPBlock;
   UInt32 depthFlags;
   UInt32 depthReserved1;
   UInt32 depthReserved2;
};
typedef struct DMDepthInfoRec DMDepthInfoRec;
typedef DMDepthInfoRec * DMDepthInfoPtr;

Fields

depthSwitchInfo: A pointer to the structure VDSwitchInfoRec, which contains values that specify information on video switch modes and data.
depthVPBlock: A pointer to the structure VPBlock, which supplies information about size, depth and format.
depthFlags: Values from the video structure VDVideoParametersInfoRec, which specify color, size, and depth.
depthReserved1: Reserved for future expansion.
depthReserved2: Reserved for future expansion.

Discussion

This structure provides information that the structure DMDepthInfoBlockRec supplies to the function DMGetIndexedDisplayModeFromList.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayListIteratorUPP

typedef DMDisplayListIteratorProcPtr DMDisplayListIteratorUPP;

Discussion

For more information, see the description of the DMDisplayListIteratorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayModeListEntryRec

struct DMDisplayModeListEntryRec {
   UInt32 displayModeFlags;
   VDSwitchInfoPtr displayModeSwitchInfo;
   VDResolutionInfoPtr displayModeResolutionInfo;
   VDTimingInfoPtr displayModeTimingInfo;
   DMDepthInfoBlockPtr displayModeDepthBlockInfo;
   UInt32 displayModeVersion;
   StringPtr displayModeName;
   DMDisplayTimingInfoPtr displayModeDisplayInfo;
};
typedef struct DMDisplayModeListEntryRec DMDisplayModeListEntryRec;
typedef DMDisplayModeListEntryRec * DMDisplayModeListEntryPtr;

Fields

displayModeFlags: A pointer to a video structure, VDSwitchInfoRec, which provides information you need to tell the driver how to switch into different configurations, bit depths, or resolutions. See the function DMSetDisplayMode for more information.
displayModeSwitchInfo: A pointer to a VDSwitchInfoRec video structure, which provides information you need to tell the driver how to switch into different configurations, bit depths, or resolutions. See the function DMSetDisplayMode for more information.
displayModeResolutionInfo: A pointer to a pointer to a VDResolutionInfoRec video structure, which provides information about horizontal pixels, maximum depth modes, and the vertical line of the specified display mode.
displayModeTimingInfo: A pointer to a pointer to a VDTimingInfoRec video structure, which provides information about timing, format of the specified display mode.
displayModeDepthBlockInfo: A pointer to a DMDepthInfoBlockRec structure, which provides information about available pixel formats and the VPBlock, including size and depth.
displayModeVersion: The version of this structure. Currently it is version kDisplayTimingInfoVersionOne. See “Display Version Values” for more information.
displayModeName: A string pointer giving the display mode name.
displayModeDisplayInfo: A pointer to the DMDisplayTimingInfoRec data type. This data type supplies information about the quality and default values of the timing.

Discussion

The DMDisplayModeListEntryRec structure contains information about a display mode in a display mode list built by the function DMNewDisplayModeList.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayModeListIteratorUPP

typedef DMDisplayModeListIteratorProcPtr DMDisplayModeListIteratorUPP;

Discussion

For more information, see the description of the DMDisplayModeListIteratorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMDisplayTimingInfoRec

struct DMDisplayTimingInfoRec {
   UInt32 timingInfoVersion;
   UInt32 timingInfoAttributes;
   SInt32 timingInfoRelativeQuality;
   SInt32 timingInfoRelativeDefault;
   UInt32 timingInfoReserved[16];
};
typedef struct DMDisplayTimingInfoRec DMDisplayTimingInfoRec;
typedef DMDisplayTimingInfoRec * DMDisplayTimingInfoPtr;

Fields

timingInfoVersion: An unsigned 32 bit integer that shows the timing version. See “Display Version Values” for timing version values.
timingInfoAttributes: An unsigned 32 bit integer that the Display Manager sets to show timing attributes.
timingInfoRelativeQuality: A signed 32 bit integer whose flags the Display Manager sets to provide information on the quality of the timing.
timingInfoRelativeDefault: A signed 32 bit integer the Display Manager sets that specifies the relative default value of the timing.
timingInfoReserved: Reserved for future expansion.

Discussion

This structure supplies information about timing attributes, defaults and values to the structure DMDisplayModeListEntryRec.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMExtendedNotificationUPP

typedef DMExtendedNotificationProcPtr DMExtendedNotificationUPP;

Discussion

For more information, see the description of the DMExtendedNotificationProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMFidelityType

typedef UInt32 DMFidelityType;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMListIndexType

typedef unsigned long DMListIndexType;

Discussion

The function DMGetIndexedDisplayModeFromList uses this data type to supply a list of display modes from which you can obtain information about a specified display mode.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMListType

typedef void * DMListType;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMMakeAndModelRec

struct DMMakeAndModelRec {
   ResType manufacturer;
   UInt32 model;
   UInt32 serialNumber;
   UInt32 manufactureDate;
   UInt32 makeReserved[4];
};
typedef struct DMMakeAndModelRec DMMakeAndModelRec;
typedef DMMakeAndModelRec * DMMakeAndModelPtr;

Fields

manufacturer: Represents the manufacturer of the specified display.
model: Represents the model name of the specified display.
serialNumber: Represents the serial number of the specified display.
manufactureDate: Represents the date of manufacture of the specified display.
makeReserved: Reserved for future expansion.

Discussion

This structure stores information about a specified monitor or display. If you need to keep track of configurations and user preferences, you can store that information in this structure.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMModalFilterUPP

typedef void * DMModalFilterUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMNotificationUPP

typedef DMNotificationProcPtr DMNotificationUPP;

Discussion

For more information, see the description of the DMNotificationProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMProcessInfoPtr

typedef void * DMProcessInfoPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMProfileListEntryRec

struct DMProfileListEntryRec {
   CMProfileRef profileRef;
   Ptr profileReserved1;
   Ptr profileReserved2;
   Ptr profileReserved3;
};
typedef struct DMProfileListEntryRec DMProfileListEntryRec;
typedef DMProfileListEntryRec * DMProfileListEntryPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

DMProfileListIteratorUPP

typedef DMProfileListIteratorProcPtr DMProfileListIteratorUPP;

Discussion

For more information, see the description of the DMProfileListIteratorProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Displays.h

Constants

Active Device Only Values

enum {
   dmOnlyActiveDisplays = true,
   dmAllDisplays = false
};

Constants

dmOnlyActiveDisplays

Returns a handle to the GDevice structure for an active device only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

dmAllDisplays

Returns a handle to the GDevice structure for a device, active or not.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

The functions DMGetFirstScreenDevice and DMGetNextScreenDevice contain the parameter activeOnly which you can specify with an Active Device Constant.

Apple Event Notification Keywords

enum {
   kAESystemConfigNotice = 'cnfg',
   kAEDisplayNotice = 'dspl',
   kAEDisplaySummary = 'dsum',
   keyDMConfigVersion = 'dmcv',
   keyDMConfigFlags = 'dmcf',
   keyDMConfigReserved = 'dmcr',
   keyDisplayID = 'dmid',
   keyDisplayComponent = 'dmdc',
   keyDisplayDevice = 'dmdd',
   keyDisplayFlags = 'dmdf',
   keyDisplayMode = 'dmdm',
   keyDisplayModeReserved = 'dmmr',
   keyDisplayReserved = 'dmdr',
   keyDisplayMirroredId = 'dmmi',
   keyDeviceFlags = 'dddf',
   keyDeviceDepthMode = 'dddm',
   keyDeviceRect = 'dddr',
   keyPixMapRect = 'dpdr',
   keyPixMapHResolution = 'dphr',
   keyPixMapVResolution = 'dpvr',
   keyPixMapPixelType = 'dppt',
   keyPixMapPixelSize = 'dpps',
   keyPixMapCmpCount = 'dpcc',
   keyPixMapCmpSize = 'dpcs',
   keyPixMapAlignment = 'dppa',
   keyPixMapResReserved = 'dprr',
   keyPixMapReserved = 'dppr',
   keyPixMapColorTableSeed = 'dpct',
   keySummaryMenubar = 'dsmb',
   keySummaryChanges = 'dsch',
   keyDisplayOldConfig = 'dold',
   keyDisplayNewConfig = 'dnew'
};

Constants

kAESystemConfigNotice

Keyword for the Event ID for a Display Notice event.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kAEDisplayNotice

Keyword for a required parameter to a Display Notice event.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kAEDisplaySummary

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDMConfigVersion

Keyword for the descriptor structure describing the version number for this Display Notice event.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDMConfigFlags

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDMConfigReserved

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayID

Keyword for the descriptor structure describing the display ID for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayComponent

Unless you are disconnecting display components, this is for internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayDevice

Keyword for the descriptor structure containing a handle to the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayFlags

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayMode

Keyword for the descriptor structure containing the sResource number from the video device for this display mode.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayModeReserved

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayReserved

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayMirroredId

Keyword for the display this device is mirrored to.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDeviceFlags

Keyword for the descriptor structure describing the attributes for the video device as maintained in the gdFlags field of the GDevice structure for the device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDeviceDepthMode

Keyword for the descriptor structure describing the depth mode for the video device; that is, the value of the gdMode field in the GDevice structure for the device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDeviceRect

Keyword for the descriptor structure describing the boundary rectangle of the video device; that is, the value of the gdRect field in the GDevice structure for the device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapRect

Keyword for the descriptor structure describing the boundary rectangle into which QuickDraw can draw; that is, the bounds field in the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapHResolution

Keyword for the descriptor structure describing the horizontal resolution of the pixel image in the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapVResolution

Keyword for the descriptor structure describing the vertical resolution of the pixel image in the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapPixelType

Keyword for the descriptor structure describing the storage format for the pixel image on the device; that is, the value of the pixelType field in the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapPixelSize

Keyword for the descriptor structure describing the pixel depth for the device; that is, the value of the pixelSize field in the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapCmpCount

Keyword for the descriptor structure containing the number of components used to represent a color for a pixel; that is, the value of the cmpCount field in the PixMap structure for the GDevice structure for the device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapCmpSize

Keyword for the descriptor structure describing the size in bits of each component for a pixel; that is, the value of the cmpSize field in the PixMap structure for the GDevice structure for the device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapAlignment

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapResReserved

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapReserved

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyPixMapColorTableSeed

Keyword for the descriptor structure containing the value of the ctSeed field of the ColorTable structure for the PixMap structure for the GDevice structure for the video device.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keySummaryMenubar

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keySummaryChanges

Reserved for future expansion. Internal use only.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayOldConfig

Keyword for the descriptor structure describing the video device’s previous state.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

keyDisplayNewConfig

Keyword for the descriptor structure describing the video device’s new state.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

The Display Manager sends an Apple event—the Display Notice event—to notify applications that it has changed the display environment. The keywords that specify the Display Notice event and its descriptor structures are described here.

Confirm Flags

enum {
   kForceConfirmBit = 0,
   kForceConfirmMask = (1 << kForceConfirmBit)
};

Constants

kForceConfirmBit

Indicates to force a confirm dialog.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kForceConfirmMask

Use to set or test for a forced confirm dialog.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Dependent Notification Constants

enum {
   kDependentNotifyClassShowCursor = 'shcr',
   kDependentNotifyClassDriverOverride = 'ndrv',
   kDependentNotifyClassDisplayMgrOverride = 'dmgr',
   kDependentNotifyClassProfileChanged = 'prof'
};

Constants

kDependentNotifyClassShowCursor

The Display Manager sends an extended notification when a hidden cursor shows during a display unmirror.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDependentNotifyClassDriverOverride

The Display Manager sends notification that a video driver has been overridden with a newer revision.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDependentNotifyClassDisplayMgrOverride

The Display Manager sends notification that it has been upgraded with a newer revision.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDependentNotifyClassProfileChanged

The Display Manager sends notification when the profile associated with a display changes.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

The function DMSendDependentNotification contains the parameter notifyClass which you can specify with a Dependent Notification Constant.

Display/Device ID Constants

The Display Manager uses these values to help with the configuration of the display.

enum {
   kDummyDeviceID = 0x00FF,
   kInvalidDisplayID = 0x0000,
   kFirstDisplayID = 0x0100
};

Constants

kDummyDeviceID

This is the ID of the dummy display, used when the last “real” display is removed.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kInvalidDisplayID

This is the ID of the invalid display, which has been removed from the active display list.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kFirstDisplayID

When your application sets this bit it asks the Display Manager to return the ID of the first display device on the active display list.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Display Gestalt Constants

enum {
   kDisplayGestaltDisplayCommunicationAttr = 'comm',
   kDisplayGestaltForbidI2CMask = (1 << 0),
   kDisplayGestaltUseI2CPowerMask = (1 << 1),
   kDisplayGestaltCalibratorAttr = 'cali',
   kDisplayGestaltBrightnessAffectsGammaMask = (1 << 0),
   kDisplayGestaltViewAngleAffectsGammaMask = (1 << 1)
};

Display Mode Flags

The structure DMDisplayModeListEntryRec uses these values for its displayModeFlags field.

enum {
   kDisplayModeListNotPreferredBit = 0,
   kDisplayModeListNotPreferredMask = (1 << kDisplayModeListNotPreferredBit)
};

Constants

kDisplayModeListNotPreferredBit

Indicates there is a better timing available and that this timing should be shown only if the user wants to see all options.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDisplayModeListNotPreferredMask

(1 kDisplayModeListNotPreferredBit)

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Display Version Values

enum {
   kDisplayTimingInfoVersionZero = 1,
   kDisplayTimingInfoReservedCountVersionZero = 16,
   kDisplayModeEntryVersionZero = 0,
   kDisplayModeEntryVersionOne = 1
};

Constants

kDisplayTimingInfoVersionZero

This relative information is always NULL in this version.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDisplayTimingInfoReservedCountVersionZero

This relative information is always NULL in this version.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDisplayModeEntryVersionZero

This relative information is always NULL in this version.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDisplayModeEntryVersionOne

This relative information is always NULL in this version.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

These values supply information to the structure DMDisplayModeListEntryRec.

Fidelity Check Constants

enum {
   kNoFidelity = 0,
   kMinimumFidelity = 1,
   kDefaultFidelity = 500,
   kDefaultManufacturerFidelity = 1000
};

Get Name By AVID Mask

enum {
   kDMSupressNumbersMask = (1 << 0),
   kDMForceNumbersMask = (1 << 1),
   kDMSupressNameMask = (1 << 2)
};

Constants

kDMSupressNumbersMask

If the bit specified by this mask is set, the numbers are suppressed and only names are returned.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMForceNumbersMask

If the bit specified by this mask is set, the numbers are forced to always be shown–even on single display configs.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMSupressNameMask

If the bit specified by this mask is set, the names are suppressed and only numbers are returned.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Include Masks

enum {
   kIncludeOnlineActiveDisplaysMask = (1 << 0),
   kIncludeOnlineDisabledDisplaysMask = (1 << 1),
   kIncludeOfflineDisplaysMask = (1 << 2),
   kIncludeOfflineDummyDisplaysMask = (1 << 3),
   kIncludeHardwareMirroredDisplaysMask = (1 << 4)
};

Item Flags

enum {
   kComponentListNotPreferredBit = 0,
   kComponentListNotPreferredMask = (1 << kComponentListNotPreferredBit)
};

Mode List Masks

enum {
   kDMModeListIncludeAllModesMask = (1 << 0),
   kDMModeListIncludeOfflineModesMask = (1 << 1),
   kDMModeListExcludeDriverModesMask = (1 << 2),
   kDMModeListExcludeDisplayModesMask = (1 << 3),
   kDMModeListExcludeCustomModesMask = (1 << 4),
   kDMModeListPreferStretchedModesMask = (1 << 5),
   kDMModeListPreferSafeModesMask = (1 << 6)
};

Constants

kDMModeListIncludeAllModesMask

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListIncludeOfflineModesMask

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListExcludeDriverModesMask

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListExcludeDisplayModesMask

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListExcludeCustomModesMask

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListPreferStretchedModesMask

Prefer modes that are stretched over modes that are letterboxed when setting kDisplayModeListNotPreferredBit

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMModeListPreferSafeModesMask

Prefer modes that are safe over modes that are not when setting kDisplayModeListNotPreferredBit

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Name Flags

enum {
   kSuppressNumberBit = 0,
   kSuppressNumberMask = 1,
   kForceNumberBit = 1,
   kForceNumberMask = 2,
   kSuppressNameBit = 2,
   kSuppressNameMask = 4
};

New Engine List Constants

enum {
   kAnyPanelType = 0,
   kAnyEngineType = 0,
   kAnyDeviceType = 0,
   kAnyPortType = 0
};

Notification Messages

enum {
   kDMNotifyRequestConnectionProbe = 0,
   kDMNotifyInstalled = 1,
   kDMNotifyEvent = 2,
   kDMNotifyRemoved = 3,
   kDMNotifyPrep = 4,
   kDMNotifyExtendEvent = 5,
   kDMNotifyDependents = 6,
   kDMNotifySuspendConfigure = 7,
   kDMNotifyResumeConfigure = 8,
   kDMNotifyRequestDisplayProbe = 9,
   kDMNotifyDisplayWillSleep = 10,
   kDMNotifyDisplayDidWake = 11,
   kExtendedNotificationProc = (1L << 16)
};

Constants

kDMNotifyRequestConnectionProbe

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyInstalled

The Display Manager provides this message during a callback function to if your application has installed an extended notification procedure pointer for the first time. The Display Manager provides this message in the notifyData parameter of DMSendDependentNotification.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyEvent

The Display Manager provides this message when an Apple event update occurs, after a display configuration change is made. This is the only time non-extended notifications are called.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyRemoved

The Display Manager provides this message when the function DMSendDependentNotification is called on your function.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyPrep

Before passing kDMSNotifyRemoved, the Display Manager provides this message to indicate that it is about to begin to configure. Calling DMSendDependentNotification tells the Display Manager to send this message.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyExtendEvent

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyDependents

The Display Manager provides this message to DMSendDependentNotification.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifySuspendConfigure

The Display Manager passes this selector to notify your UPP that configuration is temporarily suspended. For instance, if a video game makes a temporary change to the display configuration, the game is expected to resume configuration and restore video before allowing other applications to access the screen.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyResumeConfigure

The Display Manager passes this selector to notify your application when previously suspended configuration is resumed. Your application can then replace windows and icons, and change depth mode if necessary.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyRequestDisplayProbe

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDMNotifyDisplayWillSleep

This selector is only available in Mac OS X.

Available in Mac OS X v10.2 and later.

Declared in Displays.h.

kDMNotifyDisplayDidWake

This selector is only available in Mac OS X.

Available in Mac OS X v10.2 and later.

Declared in Displays.h.

kExtendedNotificationProc

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

Display Manager functions needed for dependency notification and event processing use the notification message selectors in extended application-defined functions. DMRegisterExtendedNotifyProc gets all these messages. Applications should update all information about the display configurations at this point.

Notification Types

enum {
   kFullNotify = 0,
   kFullDependencyNotify = 1
};

Constants

kFullNotify

The Display Manager sets this bit to provide the major Apple notification event.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kFullDependencyNotify

The Display Manager sets this bit to provide notification only to those applications that need to know about interrelated functionality. It is used for updating the user interface.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

The function DMSendDependentNotification uses these values in the notifyType parameter.

Panel List Flags

enum {
   kAllowDuplicatesBit = 0
};

Port List Flags

enum {
   kPLIncludeOfflineDevicesBit = 0
};

Constants

kPLIncludeOfflineDevicesBit

Should offline devices be put into the port list (such as dummy display)

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Reserved Count Constants

enum {
   kMakeAndModelReservedCount = 4
};

Constants

kMakeAndModelReservedCount

Indicates the number of reserved fields.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Summary Change Flags

enum {
   kBeginEndConfigureBit = 0,
   kMovedDisplayBit = 1,
   kSetMainDisplayBit = 2,
   kSetDisplayModeBit = 3,
   kAddDisplayBit = 4,
   kRemoveDisplayBit = 5,
   kNewDisplayBit = 6,
   kDisposeDisplayBit = 7,
   kEnabledDisplayBit = 8,
   kDisabledDisplayBit = 9,
   kMirrorDisplayBit = 10,
   kUnMirrorDisplayBit = 11
};

Switch Flags

enum {
   kNoSwitchConfirmBit = 0,
   kDepthNotAvailableBit = 1,
   kShowModeBit = 3,
   kModeNotResizeBit = 4,
   kNeverShowModeBit = 5
};

Constants

kNoSwitchConfirmBit

If the Display Manager sets this bit the display mode is required to function correctly. Your application does not need to provide confirmation if the user switches to this mode.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kDepthNotAvailableBit

If the Display Manager sets this bit the pixel depth of the specified device is not available for the specified display mode.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kShowModeBit

If the Display Manager sets this bit your application should display this mode to the user, even though it may require confirmation.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kModeNotResizeBit

If the Display Manager sets this bit you should not use this mode to resize a display; this mode drives a different connector in cards than in a built-in display.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

kNeverShowModeBit

If the Display Manager sets this bit you should not show the mode in the user interface.

Available in Mac OS X v10.0 and later.

Declared in Displays.h.

Discussion

In its switchFlags parameter, the function DMCheckDisplayMode returns a pointer to a long integer that specifies flags in two of its bits. The constants represent bits that are set to 1. These bits are set by the Display Manager, not your application

Result Codes

The table below lists the result codes that are specific to the Display Manager.

Result Code	Value	Description
`kDMGenErr`	-6220	An indeterminate error occurred. Available in Mac OS X v10.0 and later.
`kDMMirroringOnAlready`	-6221	Video mirroring is already enabled. Available in Mac OS X v10.0 and later.
`kDMWrongNumberOfDisplays`	-6222	Wrong number of displays. Available in Mac OS X v10.0 and later.
`kDMMirroringBlocked`	-6223	Video is blocked. Available in Mac OS X v10.0 and later.
`kDMCantBlock`	-6224	Video mirroring is already enabled and can’t be blocked; use `DMUnMirrorDevice`, then call `DMBlockMirroring` again. Available in Mac OS X v10.0 and later.
`kDMMirroringNotOn`	-6225	Video mirroring is not currently enabled. Available in Mac OS X v10.0 and later.
`kSysSWTooOld`	-6226	Some piece of system software is too old for the Display Manager to operate. Available in Mac OS X v10.0 and later.
`kDMSWNotInitializedErr`	-6227	The required pieces of system software are not initialized. Available in Mac OS X v10.0 and later.
`kDMDriverNotDisplayMgrAwareErr`	-6228	The video driver for the display does not support the Display Manager. Available in Mac OS X v10.0 and later.
`kDMNotFoundErr`	-6229	Available in Mac OS X v10.0 and later.
`kDMDisplayNotFoundErr`	-6229	There are no `GDevice` structures for displays in the device list. Available in Mac OS X v10.0 and later.
`kDMDisplayAlreadyInstalledErr`	-6230	The display is already in the device list and can’t be added. Available in Mac OS X v10.0 and later.
`kDMNoDeviceTableclothErr`	-6231	Available in Mac OS X v10.0 and later.
`kDMMainDisplayCannotMoveErr`	-6231	Available in Mac OS X v10.0 and later.
`kDMFoundErr`	-6232	Item found Available in Mac OS X v10.0 and later.

Gestalt Constants

You can check for version and feature availability information by using the Display Manager Version selectors defined in the Gestalt Manager. For more information, see Gestalt Manager Reference.

Last updated: 2007-12-04

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.