Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: More Macintosh Toolbox /

Chapter 8 - Control Panels / Control Panels Reference

Application-Defined Routines / Monitors Extension Functions

MyMntrExt
You provide a monitors extension function to implement the features that allow users to set the controls for your video card. Your function should respond appropriately to any messages sent to it by the Monitors control panel. In the message parameter, the Monitors control panel passes a value indicating which action your function should perform. Here's how you declare a monitors extension function called MyMntrExt:
FUNCTION MyMntrExt (message, item, numItems: Integer; 
                  monitorValue: LongInt; mDialog: DialogPtr; 
                  theEvent: EventRecord;
                  screenNum: Integer; VAR screens: ScrnRsrcHandle;
                  VAR scrnChanged: Boolean): LongInt;
message
A value that identifies the event or action to which your monitors extension function should respond. See Table 8-4 on page 8-81 for the values your function can receive in this parameter.
item
For hitDev messages, the number of the item that the user clicked. The Monitors control panel appends your item list to its own. So, although you begin numbering your item list with 1 in your item list resource, the Monitors control panel adds the number of standard items in the Options dialog box's item list to your item. Therefore, to get the actual number of the clicked item, your monitors extension function should always subtract numItems from item.

For the startupMsg message, the item parameter indicates whether the user has selected superuser status. If so, the item parameter is 1; if not, it is 0.
numItems
The item list number of the last standard item in the Options dialog box.
monitorValue

The first time the Monitors control panel calls your monitors extension function, that is, when the message parameter equals startupMsg, the value of the monitorValue parameter is 0. After the first call, this parameter contains the result your monitors extension function returned the last time the Monitors control panel called it. Because control panel routines, including a monitors extension function, cannot use global variables to store data between calls, your function can use its function result to return a handle to any memory it allocates. The next time the Monitors control panel calls your monitors extension function, it passes the handle back to your function in the monitorValue parameter.

If your monitors extension function returns a function result in the range 1 through 255, the Monitors control panel interprets this result as an error and closes your Options dialog box. Therefore, your monitors extension function will not receive a value in this range in the monitorValue parameter.
mDialog
The dialog pointer for the Options dialog box. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for a description of dialog pointers.
theEvent
The event record for an event that caused the Monitors control panel to pass a hitMsg, nulMsg, or keyEvtMsg message to your monitors extension function. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for a description of events and event records.
screenNum
The number of the screen device (that is, the monitor) that the user selected. The Monitors control panel numbers monitors consecutively, in the same order as the slots in which the cards are installed, starting with 1.
screens
A handle to a screen ('scrn') resource. See Inside Macintosh: Devices for information on the screen resource.
scrnChanged
A Boolean value that you can use to indicate whether you have modified the screen ('scrn') resource. Set this parameter to TRUE if you have modified the screen resource. When you set the scrnChanged parameter to TRUE, the Monitors control panel checks whether the values in the screen resource are still valid; if there is a problem, the Monitors control panel tries to correct it.

This parameter makes it easier to implement a control that changes the apparent area displayed on the screen. For example, your monitor might be able to display either two pages of a document or a magnified view of a single page. If the user changes the area displayed on one screen in a system with multiple screens, the displays on adjacent screens could overlap or show gaps. When you change the screen resource to implement this change, the coordinates of the global rectangles for adjacent screens are no longer contiguous. In this case, if you have set the scrnChanged parameter to TRUE, the Monitors control panel shifts the virtual locations of the screens to eliminate the gaps or overlaps.

DESCRIPTION
The Monitors control panel calls your monitors extension function repeatedly with messages requesting your function to perform an action or handle an event that occurs while the Options dialog box is displayed. Table 8-4 lists the constant names for the values that the Monitors control panel passes in the message parameter and provides a description of the action your function should perform.
Table 8-4 Messages from the Monitors control panel (Continued)
Constant Value Description
initMsg 1 Your monitor extension function should perform initialization; it should allocate any memory it needs and set default values for its controls.
The Monitors control panel sends this message to your function before it displays the Options dialog box but after it locates any resources, such as gamma tables, that your extension includes.
okMsg 2 When the user clicks the OK button, the Monitors control panel hides the Options dialog box and calls your monitors extension function with this message. This is your function's last chance to check the values of dialog items that the user might have changed. Your function should release any memory that it previously allocated before returning control to the Monitors control panel.
The OK button is a standard control put in the Options dialog box by the Monitors control panel.
cancelMsg 3 The user clicked the Cancel button. Your monitors extension function should return the device that your monitors extension controls to the condition it was in before the user clicked the Options button, release any memory that your function previously allocated, and return control to the Monitors control panel.
The Cancel button is a standard control put in the Options dialog box by the Monitors control panel.
hitMsg 4 The user clicked an enabled control in the Options dialog box, and your extension function should handle the click.
The Monitors control panel appends your item list to the standard list of items in the Options dialog box and passes, in the item parameter, the item's item number in the combined list. To get the actual number of the clicked item as defined in your item list, subtract numItems from item.
nulMsg 5 A null event occurred. Your monitors extension function should perform tasks that have to be done repeatedly, if any. Do not assume any particular timing for this message.
updateMsg 6 An update event occurred. Your monitors extension function should update any user items and redraw any controls that are not standard items handled by the Dialog Manager.
activateMsg 7 An activate event occurred, indicating that the Options dialog box is becoming active. Currently, the Monitors control panel does not call your monitors extension function with this message, because the Options dialog box is modal. However, your function should handle this message as it would any activate event, because in future versions of the Operating System the Options dialog box might be modeless.
deactivateMsg 8 An activate event occurred, indicating that the Options dialog box is becoming inactive. Currently, the Monitors control panel does not call your extension function with this message, because the Options dialog box is modal. However, your function should handle this message as you would any activate event, because in future versions of the Operating System the Options dialog box might be modeless.
keyEvtMsg 9 A keyboard event occurred. Your monitors extension function should process the keyboard event.
superMsg 10 The user has selected superuser status. Your monitors extension function should display any controls that are reserved for superusers.
The Monitors control panel sends this message when the user holds down the Option key while clicking the Options button.
This message is provided for backward compatibility with System 6. However, your monitors extension function can respond to it by initializing any controls that you have reserved for superusers, if your function has not already done this in response to either the startupMsg or initMsg message. If your code does not handle this message, it should return as its function result a handle to any previously allocated memory.
The Monitors control panel sends this message or the normal message immediately following the initialization message.
normalMsg 11 The user is not a superuser. This message is provided for backward compatibility with System 6. However, your monitors extension function can respond to it by initializing any controls, if your function has not already done this in response to either the startupMsg or initMsg message. If your function does not handle this message, it should return as its function result a handle to any previously allocated memory.
The Monitors control panel sends this message or the superuser message immediately following the initialization message.
startupMsg 12 The Monitors control panel sends this message as soon as the code in your monitors code ('mntr') resource has been loaded, and before the Monitors control panel finds any resources that your monitors extension function refers to. If the user is a superuser, the Monitors control panel sets the item parameter to 1 when it sends the startup message.
When your monitors extension function receives this message, it can load and modify any resources that must allow for the capabilities of the system or for superusers. For example, your function can modify the item list resource to display special controls for superusers.

Your monitors extension function can return either an error code or a value that you want to have available the next time the Monitors control panel calls your function. For example, if your monitors extension function allocates memory, it can return a handle to the memory as its function result. Each time the Monitors control panel calls your monitors extension function, the monitorValue parameter contains the value that your function returned the last time it was called.
Your monitors extension function must also detect and recover from any error conditions or report them to the user. If it cannot recover from an error, your monitors extension function should display an error dialog box and then return a value between 1 and 255. If your function returns a value in this range, the Monitors control panel closes the Options dialog box immediately and does not call your function again. If your function returns an error in response to the initMsg or startupMsg message, the Monitors control panel does not display the Options dialog box. Your function can display an alert box describing the error before returning control to the Monitors control panel.

SEE ALSO
For more information about the messages the Monitors control panel sends to your monitors extension function and how to handle them, see "Writing a Monitors Extension Function" beginning on page 8-61.

**Table 8-4 Messages from the Monitors control panel** (Continued)
Constant	Value	Description
initMsg	1	Your monitor extension function should perform initialization; it should allocate any memory it needs and set default values for its controls.
	The Monitors control panel sends this message to your function before it displays the Options dialog box but after it locates any resources, such as gamma tables, that your extension includes.
okMsg	2	When the user clicks the OK button, the Monitors control panel hides the Options dialog box and calls your monitors extension function with this message. This is your function's last chance to check the values of dialog items that the user might have changed. Your function should release any memory that it previously allocated before returning control to the Monitors control panel.
	The OK button is a standard control put in the Options dialog box by the Monitors control panel.
cancelMsg	3	The user clicked the Cancel button. Your monitors extension function should return the device that your monitors extension controls to the condition it was in before the user clicked the Options button, release any memory that your function previously allocated, and return control to the Monitors control panel.
	The Cancel button is a standard control put in the Options dialog box by the Monitors control panel.
hitMsg	4	The user clicked an enabled control in the Options dialog box, and your extension function should handle the click.
	The Monitors control panel appends your item list to the standard list of items in the Options dialog box and passes, in the `item` parameter, the item's item number in the combined list. To get the actual number of the clicked item as defined in your item list, subtract `numItems` from `item`.
nulMsg	5	A null event occurred. Your monitors extension function should perform tasks that have to be done repeatedly, if any. Do not assume any particular timing for this message.
updateMsg	6	An update event occurred. Your monitors extension function should update any user items and redraw any controls that are not standard items handled by the Dialog Manager.
activateMsg	7	An activate event occurred, indicating that the Options dialog box is becoming active. Currently, the Monitors control panel does not call your monitors extension function with this message, because the Options dialog box is modal. However, your function should handle this message as it would any activate event, because in future versions of the Operating System the Options dialog box might be modeless.
deactivateMsg	8	An activate event occurred, indicating that the Options dialog box is becoming inactive. Currently, the Monitors control panel does not call your extension function with this message, because the Options dialog box is modal. However, your function should handle this message as you would any activate event, because in future versions of the Operating System the Options dialog box might be modeless.
keyEvtMsg	9	A keyboard event occurred. Your monitors extension function should process the keyboard event.
superMsg	10	The user has selected superuser status. Your monitors extension function should display any controls that are reserved for superusers.
	The Monitors control panel sends this message when the user holds down the Option key while clicking the Options button.
	This message is provided for backward compatibility with System 6. However, your monitors extension function can respond to it by initializing any controls that you have reserved for superusers, if your function has not already done this in response to either the `startupMsg` or `initMsg` message. If your code does not handle this message, it should return as its function result a handle to any previously allocated memory.
	The Monitors control panel sends this message or the normal message immediately following the initialization message.
normalMsg	11	The user is not a superuser. This message is provided for backward compatibility with System 6. However, your monitors extension function can respond to it by initializing any controls, if your function has not already done this in response to either the `startupMsg` or `initMsg` message. If your function does not handle this message, it should return as its function result a handle to any previously allocated memory.
	The Monitors control panel sends this message or the superuser message immediately following the initialization message.
startupMsg	12	The Monitors control panel sends this message as soon as the code in your monitors code (`'mntr'`) resource has been loaded, and before the Monitors control panel finds any resources that your monitors extension function refers to. If the user is a superuser, the Monitors control panel sets the `item` parameter to 1 when it sends the startup message.
	When your monitors extension function receives this message, it can load and modify any resources that must allow for the capabilities of the system or for superusers. For example, your function can modify the item list resource to display special controls for superusers.

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