The Monitor Function
The 'mntr' resource must contain a function that responds to the various events that can occur while the Options dialog box is on the screen. The
declaration for a monitor function named MyMntr is as follows:
pascal long MyMntr ( short ˜ message,
short ˜item,
short ˜ numItems,
long ˜ monitorValue,
DialogPtr mDialog,
EventRecord * theEvent,
short ˜ screenNum,
ScrnRsrcHandle * screens,
Boolean *scrnChanged
);
Parameter descriptions
message A message number, from the list defined in the
following section, that your monitor function can
use to determine what action to take.
item The dialog-item-list number of the item that the
user clicked. To calculate the dialog-item-list
number in your 'DITL' resource, subtract the
number passed in the numItems parameter from the
number in the item parameter. When the message
parameter equals StartupMsg, the item parameter
indicates whether the user is a superuser-that is,
whether the user can be assumed to be very
knowledgeable. If the user is a superuser, the item
parameter is 1; if not, it is 0.
numItems The dialog-item-list number of the last standard
item in the Options dialog box. You number the items
in your 'DITL' resource starting with 1; the
Monitors control panel adds the value of the
numItems parameter to each number in the 'DITL'
resource and uses the result for the dialog-item-list
number.
monitorValue The result returned by your monitor function the
last time it was called. Because control panel
routines cannot have global variables, you might
want to use the function result to return a handle to
the storage of your local data. This handle is then
available in the monitorValue parameter the next
time the monitor function is called. The
monitorValue parameter is 0 the first time the
Monitors control panel calls your monitor function
(that is, when the message parameter equals
startupMsg). If your monitor 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 monitor function cannot receive a value in this
range in the monitorValue parameter.
mDialog The dialog pointer for the Options dialog box.
theEvent The event record for an event that caused a hitMsg,
nulMsg, or keyEvtMsg message.
screenNum The number of the screen device (that is, the
monitor) that the user has 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 the 'scrn' resource. The 'scrn' resource is described in the description of the
scrnChanged A Boolean value that you can use to indicate whether you have modified the 'scrn' resource. Set this
parameter to TRUE if you have modified the 'scrn' resource. When the scrnChanged parameter is TRUE, the Monitors control panel checks the 'scrn'
resource to make sure that the values in it 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
'scrn' 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.
Your monitor function can return either an error code or a value that you
want to have available the next time the Monitors extension is called. Each time
the extension is called, the monitorValue parameter contains the value that
your monitor function returned the last time it was called.
If an error occurs, your monitor function should display an error dialog box
and then return a value between 1 and 255. If your code returns a value in this
range, the Monitors control panel closes the Options dialog box immediately and
no more calls are made to your code. If your code returns an error in response
to the initMsg or startupMsg message, the Monitors control panel does not
display the Options dialog box. You can display an alert box describing the
error before returning control to the Monitors control panel.