CHAPTER 8 - PART 2
Displaying Alert and Dialog Boxes
As previously stated:
- Alert, NoteAlert, CautionAlert and StopAlert are used to create and display alert boxes using descriptive information supplied by 'ALRT' and 'alrx' resources, and StandardAlert is used, in conjunction with information suppled by a standard alert structure, to create and display alert boxes programmatically.
- GetNewDialog is used to create dialog boxes using descriptive information supplied by 'DLOG' and 'dlgx' resources, and NewFeaturesDialog is used to create dialog boxes programmatically. Both creation methods allow you to specify whether the dialog box is to be initially visible, and both allow you to specify whether or not the dialog box is to be brought to the front of all other windows when it is opened.
To display a dialog box which is specified to be invisible on creation, you must call ShowWindow following the GetNewDialog or NewFeaturesDialog call to display the dialog box. In addition, you should invariably pass (WindowPtr) -1 in the behind and inBehind and parameters of, respectively, GetNewDialog and NewFeaturesDialog call so as to display a dialog box as the active (frontmost) window.
Window Deactivation and Menu Adjustment
When an alert box or dialog box is displayed:
- The frontmost window (assuming one exists) must be deactivated.
- The application's menus must be adjusted to reflect the differing levels of permitted menu access which apply in the presence of the various types of alert box and dialog box. (As will be seen, the system software automatically performs some of this menu adjustment for you.)
Historical Note
Prior to the introduction of Mac OS 8 and the Appearance Manager, window deactivation when a movable modal dialog box was displayed was handled in the same way as applies in the case of a modeless dialog box, that is, within the application's main event loop. However, under Appearance, when the kDialogFlagsHandleMovableModal bit is set in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, ModalDialog is used to handle all user interaction within the dialog. (Previously, this user interaction was handled within the main event loop.) This has implications for the way your application deactivates the front window when a movable modal dialog is displayed.
Prior to the introduction of Mac OS 8 and the Appearance Manager, menu adjustment when a movable modal dialog box was displayed was performed by the application. However, when a movable modal dialog is created by setting the kDialogFlagsHandleMovableModal bit in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, menu adjusment is performed by the Dialog Manager and Menu Manager.
All that follows assumes that the kDialogFlagsHandleMovableModal bit is set in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, and that, as a consequence:
- Your application calls ModalDialog to handle all user interaction within movable modal dialog boxes (as is the case with modal dialog boxes).
- Menu adjustment will be performed automatically by the Dialog Manager and Menu Manager when a movable modal dialog is displayed (as is the case with modal dialog boxes).
|
Window Deactivation - Modeless Dialog Boxes
You do not have to deactivate the front window explicitly when displaying a modeless dialog box. The Event Manager continues sending your application activate events for your windows as needed, which you typically handle in your main event loop.
Window Deactivation - Modal and Movable Modal Alert and Dialog Boxes
When a modal or movable modal dialog box is created and displayed, your application calls ModalDialog to handle all user interaction within the dialog until the dialog is dismissed. Events, which are ordinarily handled within your application's main event loop, will then be trapped and handled by ModalDialog. This means that your window activation/deactivation function will not now be called as it normally would following the opening of a new window. Accordingly, if one of your application's windows is active, you must explicitly deactivate it before displaying a modal or movable modal alert or dialog box.
If your application does not display an alert box during certain alert stages, you should call the GetAlrtStage function to test for those stages before deactivating the active window.
Menu Adjustment - Modeless Dialog Boxes
When your application displays a modeless dialog box, it is responsible for all menu disabling and enabling. Your application should thus perform the following tasks:
- Disable only those menus whose items are invalid in the current context.
- If the modeless dialog box includes edit text fields, enable the Edit menu and use the Dialog Manager functions DialogCut, DialogCopy, DialogPaste and DialogDelete to support the Cut, Copy, Paste, and Clear items in that menu.
Your application is also responsible for all menu enabling when a modeless dialog box is dismissed.
Menu Adjustment - Modal Alert and Dialog Boxes
When your application displays a modal alert or dialog box, the Dialog Manager and Menu Manager interact to provide varying degrees of access to the menus in your menu bar, as follows:
Modal Dialog Boxes with Edit Text Field Items
When your application displays modal dialog boxes with no edit text field items, it can safely allow system software to handle menu bar access. However, because system software cannot handle the Undo and Clear commands (or any other context-dependent command), you may wish to handle your own menu bar access for modal dialog boxes with edit text field items by performing the following tasks:
- Disable the Apple menu or its first item (typically, the About... item) in order to take control of menu bar access away from the Dialog Manager.
- Disable all of the application's menus except the Edit menu, as well as any inappropriate items in the Edit menu.
- Use DialogCut, DialogCopy, DialogPaste, and DialogDelete to support the Cut, Copy, Paste, and Clear items in edit text fields.
- Provide your own code for supporting the Undo item.
- Enable your application's items in the Help menu as appropriate.
When the user dismisses the modal alert or dialog box, the Menu Manager restores all menus to their previous state unless your application handles its own menu bar access, in which case your application must restore the menu bar to its previous state.
Menu Adjustment - Movable Modal Alert and Dialog Boxes
When your application displays a movable modal alert or dialog box, the Dialog Manager and Menu Manager interact to provide the same access to the menus in your menu bar as applies in the case of modal alert and dialog boxes except that, in this case, the Help and Application menus are enabled.
The alternative of taking control of menu bar access from the Dialog Manager where the dialog box contain edit text field items also applies in the case of movable modal dialogs.
When the user dismisses the movable modal alert or dialog box, the Menu Manager restores all menus to their previous state unless your application handles its own menu bar access, in which case your application must restore the menu bar to its previous state.
Displaying Multiple Alert and Dialog Boxes
The user should never see more than one modal dialog box and one modal alert box on the screen simultaneously. However, you can present multiple simultaneous modeless dialog boxes just as you can present multiple document windows.
Resizing a Dialog
You can use the function AutoSizeDialog to automatically resize static text fields and their dialog boxes to accommodate changed static text. For each static text field item found, AutoSizeDialog adjusts the static text field and the bottom of the dialog box window. Any items below a static text field are moved down. If the dialog box is visible, when AutoSizeDialog is called, it is hidden, resized, and then shown.
Displaying Alert and Dialog Boxes From the Background
If you ever need to display a modal alert or dialog box while your application is running in the background or is otherwise invisible to the user, you should use the Notification Manager to post a notification to the user. The Notification Manager automatically displays an alert box containing whatever message you specify; you do not need to use the Dialog Manager to create the alert yourself. (See Chapter 23 - Miscellany for a description of the Notification Manager).
Handling Events in Alert and Dialog Boxes
Overview
Modal and Movable Modal Alert and Dialog Boxes
When Alert, NoteAlert, CautionAlert, StopAlert, and StandardAlert are used to display alert boxes, the Dialog Manager handles all of the events generated by the user until the user clicks a push button. (These functions are actually just variations of ModalDialog which create and destroy their own windows.) When the user hits a push button, these functions highlight the push button briefly, close the alert box and report the user's selection to the application.
As previously stated, ModalDialog handles all user interaction within modal and movable modal dialogs. When the user selects an enabled item, ModalDialog reports that the user selected the item and then exits. Your application is then responsible for performing the appropriate action in relation to that item. Your application typically calls ModalDialog repeatedly until the user dismisses the dialog.
The modalFilter parameters in the Alert, NoteAlert, CautionAlert, StopAlert, StandardAlert and ModalDialog functions, and the filterProc field of the standard alert structure associated with the StandardAlert function, take a universal procedure pointer to an event filter function. The Dialog Manager provides a standard event filter function, which is used if NULL is passed in the modalFilter parameter or filterProc field; however, you should supply an application-defined event filter function for modal and movable modal alert and dialog boxes so as to avoid a basic limitation of the standard event filter function. (See Event Filter Functions For Modal and Movable Modal Alert and Dialog Boxes, below)
Modeless Dialog Boxes
For modeless dialog boxes, you can use the function IsDialogEvent to determine whether the event occurred while a modeless dialog box was the frontmost window and then, optionally, use the function DialogSelect to handle the event if it belongs to a modeless dialog box. DialogSelect is similar to ModalDialog except that it returns control after every event, not just events relating to an enabled item. Also, DialogSelect does not pass events to an event filter function.
Responding to Events in Controls
Controls and Control Values
For clicks in those types types of controls for which you need to determine or change the control's value, your application should use the Control Manager functions GetControlValue and SetControlValue to get and set the value. When the user clicks on the OK push button, your application should perform whatever action is necessary according to the values returned by the controls.
Controls That Accept Keyboard Input
Edit text fields and clock controls, which both accept keyboard input, are typically disabled because you generally do not need to be informed every time the user clicks on one of them or types a character. Instead, you simply need to retrieve the text in the edit text field control, or the clock's date/time value, when the user clicks the OK push button.
When you use ModalDialog (key-down events in edit text fields and clock controls in modal or movable modal dialogs) or DialogSelect (key-down events in edit text fields and clock controls in modeless dialogs), keystrokes and mouse actions within those controls are handled automatically. In the case of an edit text field, this means that:
- When the user clicks the item, a blinking vertical bar, called the insertion point caret, appears.
- When the user drags over text or double-clicks a word, that text is highlighted and replaced by whatever the user types.
- When the user holds down the Shift key while clicking and dragging, the highlighted section is extended or shortened appropriately.
- When the user presses the backspace key, the highlighted selection or the character preceding the insertion point is deleted.
- When the user presses the Tab key, the cursor and keyboard focus frame automatically advances to the next edit text field, clock control, or list box (if any) in the item list, wrapping around to the first one if there are no more items.
Caret Blinking in Edit Text Fields
ModalDialog will cause the the insertion point caret to blink in edit text fields in modal and movable modal dialog boxes. For edit text fields in a modeless dialog box, you should call IdleControls in your main event loop's idle processing function. IdleControls calls the edit text field control with an idle event so that the control can call TEIdle to make the insertion point caret blink.
 |
You should also ensure that, when caret blinking is required, the sleep parameter in the WaitNextEvent call is set to a value no greater that that returned by GetCaretTime. |
Historical Note
IdleControl, and idle processing within certain control definition functions, was introduced with Mac OS 8 and the Appearance Manager. Prior to the introduction of Mac OS 8 and the Appearance Manager, the method used to cause the insertion point caret to blink in a modeless dialog was to call DialogSelect in the main event loop's idle processing function. DialogSelect calls TEIdle to make the caret blink. This method remains a valid alternative.
|
Responding to Events in Modal and Movable Modal Alert Boxes
After displaying a modal or movable modal alert box, Alert, NoteAlert, CautionAlert, StopAlert, and StandardAlert call ModalDialog to handle events automatically.
If the event is a mouse-down anywhere outside the content region of a modal alert box, ModalDialog emits the system alert sound and gets the next event.
If the event is a mouse-down outside the content region of a movable modal alert box and within a window belonging to the application, ModalDialog emits the system alert sound and gets the next event. If the mouse-down is not within the content region or a window belonging to the application, ModalDialog performs alert box dragging (if the mouse-down is within the title bar) or sends the application to the background (if the mouse-down is not within the title bar).
ModalDialog is continually called until the user selects an enabled control, at which time Alert, NoteAlert, CautionAlert, StopAlert, and StandardAlert remove the alert box from the screen and return the item number of the selected control. Your application then should then respond appropriately.
The standard event filter function allows users to press the Return or Enter key in lieu of clicking the default push button. When you write your own event filter function, you should ensure that that function retains this behaviour. For events inside the alert box, ModalDialog passes the event to your event filter function before handling the event. Your event filter function thus provides a means to:
- Handle events which ModalDialog does not handle.
- Override events ModalDialog would otherwise handle.
Unless your event filter function handles the event in its own way, ModalDialog handles the event inside the alert box as follows:
- In response to an activate or update event for the alert box, ModalDialog activates or updates the alert box window.
- If the user presses the mouse button while the cursor is in a trackable control, TrackControl is called to track the mouse. If the user releases the mouse button while the cursor is still in the control, the alert box is removed and the control's item number is returned.
- If the user presses the mouse button while the cursor is in a disabled item, or if it is in no item, or if any other event occurs, nothing happens.
Responding To Events in Modal and Movable Modal Dialog Boxes
Your application should call ModalDialog immediately after displaying a modal or movable modal dialog box. ModalDialog repeatedly handles events inside the dialog box until an event involving an enabled item occurs, at which time ModalDialog exits, returning the item number. Your application should then respond appropriately. Your application should continually call ModalDialog until the user clicks on the OK or Cancel push button, at which time your application should close the dialog box.
If the event is a mouse-down anywhere outside the content region of a modal dialog box, ModalDialog emits the system alert sound and gets the next event.
If the event is a mouse-down outside the content region of a movable modal dialog box and within a window belonging to the application, ModalDialog emits the system alert sound and gets the next event. If the mouse down is not within the content region or a window belonging to the application, ModalDialog performs dialog box dragging (if the mouse-down is within the title bar) or sends the application to the background (if the mouse-down is not within the title bar).
If your event filter function does not handle the event, ModalDialog handles the event as follows:
- If the event is an activate or update event for the dialog box, ModalDialog activates or updates the dialog box window.
- If the event is a mouse-down while the cursor is in a control that accepts keyboard input (that is, an edit text field or a clock control), ModalDialog responds to the mouse activity as appropriate, that is, by either displaying an insertion point or by selecting text in an edit text field or by highlighting the appropriate part of the clock control. Where there is more than one control that accepts keyboard input, ModalDialog moves the keyboard focus to that control. If a key-down event occurs and there is an edit text field in the dialog, ModalDialog uses TextEdit to handle text entry and editing automatically. If the edit text field is enabled, ModalDialog returns its item number after it receives either the mouse-down or key-down event. (Normally, edit text fields are disabled, and you use the GetDialogItemText function to read the information in the items only after the user clicks the OK button.)
- If the event is a mouse-down while the cursor is in a trackable control, ModalDialog calls the Control Manager function TrackControl. If the user releases the mouse button while the cursor is in an enabled control, ModalDialog returns the control's item number. Your application should then respond appropriately.
- If the event is a Tab key key-down event and there is more than one control that accepts keyboard input, ModalDialog moves the keyboard focus to the next such item in the item list.
- If the event is a mouse-down while the cursor is in a disabled item or in no item, or if any other event occurs, ModalDialog does nothing.
Specifying the Events To Be Received by ModalDialog
The function SetModalDialogEventMask may be used to specify the events to be received by the ModalDialog function for a given modal or movable modal dialog box. This allows your application to specify additional events that are not by default received by ModalDialog, such as disk-inserted events and operating system events. If you us this function to change the ModalDialog function's event mask, you must pass ModalDialog a pointer to your own event filter function to handle the added events.
You can ascertain the events to be received by ModalDialog by calling GetModalDialogEventMask.
Historical Note
SetModalDialogEventMask and GetDialogEventMask were introduced with Mac OS 8.5.
|
Simulating Item Selection
You can cause the Dialog Manager to simulate item selection in a modal or movable modal dialog box using the function SetDialogTimeout. Your application calls this function each time you wish to start a countdown for a specified duration for a specified dialog box. When the specified time elapses, the Dialog Manager simulates a click on the button specified in the SetDialogTimeout call. The Dialog Manager will not simulate item selection until ModalDialog processes an event.
You can ascertain the original countdown duration, the time remaining, and the item selection to be simulated by calling GetDialogTimeout.
Historical Note
SetDialogTimeout and GetDialogTimeout were introduced with Mac OS 8.5.
|
Event Filter Functions For Modal and Movable Modal Alert and Dialog Boxes
In early versions of the system software, when a single application controlled the computer, the standard event filter for the (modal) alert and modal dialog boxes of the day was usually sufficient. However, because the standard event filter does not cater for the updating of either the parent application's windows or those belonging to background applications, it has long been inadequate. Your application should therefore provide an event filter function which compensates for this inadequacy. In most cases, you can use the same filter function for all of your modal and movable modal alert and dialog boxes.
The standard event filter function performs the following checks and actions:
- Checks whether the user has pressed the Return or Enter key and, if so, highlights the default push button for eight ticks and returns the item number of that push button.
|
Unless informed otherwise, the Dialog Manager assumes that the first item in the item list is the default push button. As will be seen, it is possible to specify another push button as the default push button in dialog boxes; however, changing the default push button in alert boxes is possible only when the alert box is created using StandardAlert. This is why the default push button in an 'ALRT' resource must be the first item in the item list. |
- For dialog boxes only, and only if the application has previously called certain Dialog Manager functions (see below):
- Checks whether the user has pressed the Escape key or Command-period and, if so, highlights the Cancel push button for eight ticks and returns the item number of that button.
- Check whether the cursor is over an edit text field and, if so, changes the cursor shape to the I-Beam cursor.
As a minimum, your application-defined event filter function should ensure that these checks and actions are performed and should also:
- Handle update events not belonging to the alert or dialog box so as to allow the application to update its own windows, and return false. (Note that, by responding to update events in the application's own windows in this way, you also allow ModalDialog to perform a minor switch when necessary so that background applications can update their windows as well.)
- Return false for all events that your event filter function does not handle.
Defining an Event Filter Function
Part of the recommended approach to defining a basic event filter function is to continue to use the standard event filter function to perform its checks and actions as described above. This requires certain preliminary action which, for dialog boxes, requires calls similar to the following examples after the dialog is created and before the call to ModalDialog:
// Tell the Dialog Manager which is the default push button item, alias the
// Return andEnter keys to that item, and draw the default ring around that item.
SetDialogDefaultItem(myDialogPtr,iOK);
// Tell the Dialog Manager which is the Cancel push button item, and alias the
// escape key and Command-period key presses to that item.
SetDialogCancelItem(myDialogPtr,iCancel);
// Tell the Dialog Manager to track the cursor and change it to the I-Beam cursor
// shape whenever it is over an edit text field.
SetDialogTracksCursor(myDialogPtr,true);
Note that, for all this to work, it is essential that default and Cancel push buttons, and edit text fields, be specified as primitives, not as actual controls, in the 'DLOG' resource.
With those preparations made, you would define your basic event filter function as in the following example:
pascal Boolean eventFilter(DialogPtr dialogPtr,EventRecord *eventFuncPtr,
SInt16 *itemHit)
{
Boolean handledEvent;
GrafPtr oldPort;
handledEvent = false;
if((eventFuncPtr->what == updateEvt) &&
((WindowPtr) eventFuncPtr->message != dialogPtr))
{
// If the event is an update event, and if it is not for the dialog or
// alert, call your application's window updating function, and return false.
doUpdate(eventFuncPtr);
}
else
{
// If the event was not an update, first save the current graphics port and
// set the alert box or dialog box's graphics port as the current graphics
// port. This is necessary when you have called SetDialogTrackCursor to cause
// the Dialog Manager to track cursor position.
GetPort(&oldPort);
SetPort(dialogPtr);
// Pass the event to the standard event filter function for handling. If the
// function handles the event, it will return true and, in the itemHit
// parameter, the number of the item that it handled. ModalDialog, Alert,
// NoteAlert,CautionAlert, StopAlert, and StandardAlert then return this
// item number in their own itemHit parameter.
handledEvent = StdFilterProc(dialogPtr,eventFuncPtr,itemHit);
// Make the saved graphics port the current graphics port again.
SetPort(oldPort);
}
// Return true or false, as appropriate.
return(handledEvent);
}
Alert, NoteAlert, CautionAlert, StopAlert, StandardAlert and ModalDialog pass events to your event filter function before handling each event, and will handle the event if your event filter function returns false.
|
A major difference between modal alert and dialog boxes and movable modal alert and dialog boxes is that, in the case of the latter, all events are passed to your event filter function for handling. This allows you to, for example, handle suspend and resume events when your application is either moved to the background or brought to the front, as well as other events you might want to handle. |
You can also use your event filter function to handle events that ModalDialog does not handle, such as disk-inserted events, keyboard equivalents, and mouse-down events.
|
Because ModalDialog calls GetNextEvent with a mask which excludes disk-inserted events, your event filter function can call SetSystemEventMask to reset the mask to accept disk-inserted events if you wish the filter function to handle disk-inserted events. |
Alert Boxes and the Event Filter Function
The example event filter, as written, has a limitation in the case of alert boxes with Cancel buttons. Because the standard event filter function is used, and because the SetDialogCancelItem function does not apply in the case of alert boxes, the filter function will not check whether the user has pressed the Escape key or Command-period, highlight the Cancel push button, or return the item number of that button. It is possible to write an event filter function which rectifies that deficiency; however, a better approach is to simply use StandardAlert to create alert boxes which require Cancel buttons. The standard alert structure associated with StandardAlert allows you to specify which are to be the default and Cancel buttons in an alert. This is, in effect, the alert box equivalent of the SetDialogDefaultItem and SetDialogCancelItem calls used in the case of dialog boxes.
Responding to Events in Modeless Dialog Boxes
As previously stated, you can use the function IsDialogEvent to determine whether an event occurred in a modeless dialog box or a document window and then call DialogSelect to handle the event if it occurred in a modeless dialog box. DialogSelect handles the event as follows:
- If the event is an activate or update event, DialogSelect activates or updates the modeless dialog box and returns false.
- If the event is a key-down or auto-key event, and there is an edit text field in the modeless dialog box, DialogSelect uses TextEdit to handle text entry and editing and returns true and the item number. If there is no edit-text field, DialogSelect returns false.
- If the user presses the mouse button while the cursor is in an edit text field, DialogSelect responds to the mouse activity as appropriate, that is, by either displaying the insertion point caret or selecting text. DialogSelect returns false if the edit text field is disabled, and true and the item number if it is enabled. (Normally, edit text field items should be disabled.)
- If the user presses the mouse button while the cursor is in an enabled trackable control, DialogSelect calls TrackControl and, if the user releases the mouse button while the cursor is still within the control, returns true and the item number.
- If the user presses the mouse button while the cursor is on a disabled item, or if it is in no item, or if any other event occurs, DialogSelect does nothing.
In the case of a key-down or auto-key event in an edit text field, you will ordinarily need to filter out Return and Enter key presses and certain Command-key equivalents so that they are not passed to DialogSelect. In the case of Return and Enter key presses, you should also highlight the associated push button for eight ticks before calling the application-defined function which responds to hits on the OK button. In the case of Command-key presses, you should only allow Command-X, Command-C, and Command-V to be passed to DialogSelect (so that DialogSelect can support cut, copy, and paste actions within the edit text field) and pass any other Command-key equivalents to your application's menu handling function.
Closing Dialog Boxes
Use CloseDialog to dispose of a dialog box if you allocated the memory for the dialog structure yourself, otherwise use DisposeDialog.
CloseDialog removes a dialog from the screen and deletes it from the window list. It also releases memory occupied by the data structures associated with the dialog box, such as control records and text handles. CloseDialog does not dispose of the dialog structure or the 'DITL' resource.
DisposeDialog, on the other hand, calls CloseDialog and, in addition, releases the memory occupied by the dialog structure and item list resource.
For modeless dialog boxes, you might find it more efficient to hide the dialog box with HideWindow rather than remove its structures. In that way, the dialog will remain available, and in the same location and with the same settings as when it was last used.
If you adjust the menus when you display a dialog box, be sure to return them to an appropriate state when you close the dialog box.
Balloon Help For Alert and Dialog Boxes
Two basic options are available for adding help balloons to alert and dialog boxes:
- Adding a balloon help item to the item list ('DITL') resource, which will associate either a rectangle help ('hrct') resource or a dialog help ('hdlg') resource with that 'DITL' resource. Each hot rectangle component in the 'hrct' resource, and each dialog item component in the 'hdlg' resource, corresponds to an item number in the 'DITL' resource.
- By supplying a window help ('hwin') resource, which will associate help balloons defined in either 'hrct' resources or 'hdlg' resources with the alert or dialog's window.
|
'hrct' and 'hwin' resources are described at Chapter 4 - Windows. |
The option of using a balloon help item (usually referred to as simply a "help item") overcomes the major limitation of the 'hwin' resource methodology, which is the inability to adequately differentiate between alert and dialog boxes with no titles (see Chaper 4 - Windows, Fig 12). On the other hand, adopting the help item methodology means that you can only associate help balloons with items in the 'DITL' resource; you cannot provide a single help balloon for a group of related items (unless, of course, they are grouped within a primary or secondary group box).
Help items are invisible. In Resorcerer, the presence of a balloon help item in a 'DITL' resource is indicated only by a checkmark in the Balloon Help... item in the Item menu. A help item's presence in the 'DITL' resource is completely ignored by the Dialog Manager.
When the help item methodolgy is used, the Help Manager automatically tracks the cursor and displays help balloons when the following conditions are met: the alert or dialog box has a help item in its 'DITL' resource; your application calls the Dialog Manager function ModalDialog, IsDialogEvent, Alert, NoteAlert, CautionAlert or StopAlert; balloon help is enabled.
Figs 11 and 12 at Chapter 4 - Windows show 'hrct' and 'hwin' resources being created using Resorcerer.
Fig 16 shows a help item being created using Resorcerer.
Fig 17 shows a 'hdlg' (dialog help) resource being created using Resorcerer.
Main Dialog Manager Constants, Data Types and Functions
In the following:
- The constants, data types, and functions introduced with Mac OS 8 and the Appearance Manager are shown in light blue.
- The functions introduced with Mac OS 8.5 are shown in dark blue.
Constants
Dialog Item Types
kControlDialogItem = 4
kButtonDialogItem = kControlDialogItem | 0
kCheckBoxDialogItem = kControlDialogItem | 1
kRadioButtonDialogItem = kControlDialogItem | 2
kResourceControlDialogItem = kControlDialogItem | 3
kStaticTextDialogItem = 8
kEditTextDialogItem = 16
kIconDialogItem = 32
kPictureDialogItem = 64
kUserDialogItem = 0
kItemDisableBit = 128
Item Numbers for OK and Cancel Push Buttons
kStdOkItemIndex = 1
kStdCancelItemIndex = 2
Resource IDs of Alert Box Icons
kStopIcon = 0
kNoteIcon = 1
kCautionIcon = 2
Constants Used for theMethod Parameter in AppendDITL
overlayDITL = 0
appendDITLRight = 1
appendDITLBottom = 2
Alert Types
kAlertStopAlert = 0
kAlertNoteAlert = 1
kAlertCautionAlert = 2
kAlertPlainAlert = 3
Alert Button Constants
kAlertStdAlertOKButton = 1
kAlertStdAlertCancelButton = 2
kAlertStdAlertOtherButton = 3
kAlertStdAlertHelpButton = 4
Alert Default Text Constants
kAlertDefaultOKText = -1
kAlertDefaultCancelText = -1
kAlertDefaultOtherText = -1
Dialog Feature Flag Constants
kDialogFlagsUseThemeBackground = (1 << 0)
kDialogFlagsUseControlHierarchy = (1 << 1)
kDialogFlagsHandleMovableModal = (1 << 2)
kDialogFlagsUseThemeControls = (1 << 3)
Alert Feature Flag Constants
kAlertFlagsUseThemeBackground = (1 << 0)
kAlertFlagsUseControlHierarchy = (1 << 1)
kAlertFlagsAlertIsMovable = (1 << 2)
kAlertFlagsUseThemeControls = (1 << 3)
Dialog Font Flag Constants
kDialogFontNoFontStyle = 0
kDialogFontUseFontMask = 0x0001
kDialogFontUseFaceMask = 0x0002
kDialogFontUseSizeMask = 0x0004
kDialogFontUseForeColorMask = 0x0008
kDialogFontUseBackColorMask = 0x0010
kDialogFontUseModeMask = 0x0020
kDialogFontUseJustMask = 0x0040
kDialogFontUseAllMask = 0x00FF
kDialogFontAddFontSizeMask = 0x0100
kDialogFontUseFontNameMask = 0x0200
Constants Used for procID Parameter in NewDialog and NewColorDialog and inProcID Parameter in NewFeaturesDialog
kWindowDocumentProc 1024 // Modeless dialog box
kWindowPlainDialogProc 1040 // Modal dialog box
kWindowShadowDialogProc 1041 // Modal dialog box
kWindowModalDialogProc 1042 // Modal dialog box
kWindowMovableModalDialogProc 1043 // Movable modal dialog box
kWindowAlertProc 1044 // Modal alert box
kWindowMovableAlertProc 1045 // Movable modal alert box
Data Types
typedef WindowPtr DialogPtr;
Dialog Structure
struct DialogRecord
{
WindowRecord window; // Dialog's window structure.
Handle items; // Item list resource.
TEHandle textH; // Current editable text item.
SInt16 editField; // Editable text item number minus 1.
SInt16 editOpen; // (Used internally.)
SInt16 aDefItem; // Default push button item number.
};
typedef struct DialogRecord DialogRecord;
typedef DialogRecord *DialogPeek;
Standard Alert Structure
struct AlertStdAlertParamRec
{
Boolean movable; // Make alert movable modal.
Boolean helpButton; // Is there a help button?
ModalFilterUPP filterProc; // Event filter.
StringPtr defaultText; // Text for button in OK position.
StringPtr cancelText; // Text for button in cancel position.
StringPtr otherText; // Text for button in left position.
SInt16 defaultButton; // Which button behaves as the default.
SInt16 cancelButton; // Which one behaves as cancel (can be 0).
UInt16 position; // Position (kWindowDefaultPosition in this case
// equals kWindowAlertPositionParentWindowScreen).
};
typedef struct AlertStdAlertParamRec AlertStdAlertParamRec;
typedef AlertStdAlertParamRec * AlertStdAlertParamPtr;
Functions
Initialising the Dialog Manager
void InitDialogs(void *ignored);
void ErrorSound(SoundUPP soundProc);
void SetDialogFont(short value);
Creating Alerts
short Alert(short alertID, ModalFilterUPP modalFilter);
short StopAlert(short alertID, ModalFilterUPP modalFilte);
short NoteAlert(short alertID, ModalFilterUPP modalFilte);
short CautionAlert(short alertID, ModalFilterUPP modalFilte);
OSErr StandardAlert(AlertType inAlertType,StringPtr inError,StringPtr inExplanation,
AlertStdAlertParamPtr inAlertParam,SInt16 *outItemHit);
short GetAlertStage(void);
void ResetAlertStage(void);
Creating and Disposing of Dialog Boxes
DialogPtr GetNewDialog(short dialogID,void *dStorage,WindowRef behind);
DialogPtr NewDialog(void *wStorage,const Rect *boundsRect,ConstStr255Param title,
Boolean visible,short procID,WindowRef behind,Boolean goAwayFlag,
long refCon, Handle itmLstHndl);
DialogPtr NewColorDialog(void *dStorage,const Rect *boundsRect,ConstStr255Param title,
Boolean visible,short procID,WindowRef behind,Boolean goAwayFlag,long refCon,
Handle items);
DialogPtr NewFeaturesDialog(void *inStorage, const Rect *inBoundsRect,
ConstStr255Param inTitle, Boolean inIsVisible,SInt16 inProcID,
WindowPtr inBehind,Boolean inGoAwayFlag,SInt32 inRefCon,
Handle inItemListHandle,UInt32 inFlags);
void CloseDialog(DialogPtr theDialog);
void DisposeDialog(DialogPtr theDialog);
Manipulating Items in Alert and Dialog Boxes
void GetDialogItem(DialogPtr theDialog,short itemNo,short *itemType,Handle *item,
Rect *box);
void SetDialogItem(DialogPtr theDialog,short itemNo,short itemType,Handle item,
const Rect *box);
OSErr GetDialogItemAsControl(DialogPtr inDialog,SInt16 inItemNo,
ControlHandle *outControl);
OSErr MoveDialogItem(DialogPtr inDialog,SInt16 inItemNo,SInt16 inHoriz,SInt16 inVert);
OSErr SizeDialogItem(DialogPtr inDialog,SInt16 inItemNo,SInt16 inHeight,SInt16 inWidth);
OSErr AutoSizeDialog(DialogPtr inDialog);
void HideDialogItem(DialogPtr theDialog,short itemNo);
void ShowDialogItem(DialogPtr theDialog,short itemNo);
short FindDialogItem(DialogPtr theDialog,Point thePt);
void AppendDITL(DialogPtr theDialog,Handle theHandle,DITLMethod theMethod);
void ShortenDITL(DialogPtr theDialog,short numberItems);
short CountDITL(DialogPtr the Dialog);
Handling Text in Alert and Dialog Boxes
void ParamText(ConstStr255Param param0,ConstStr255Param param1,ConstStr255Param param2,
ConstStr255Param param3);
void GetDialogItemText(Handle item,Str255 text)
void SetDialogItemText(Handle item,ConstStr255Param text);
void SelectDialogItemText(DialogPtr theDialog,short itemNo,short strtSel,short endSel);
void DialogCut(DialogPtr theDialog);
void DialogPaste(DialogPtr theDialog);
void DialogCopy(DialogPtr theDialog);
void DialogDelete(DialogPtr theDialog);
Handling Events in Dialog Boxes
void ModalDialog(ModalFilterUPP modalFilter,short *itemHit);
Boolean IsDialogEvent(const EventRecord *theEvent);
Boolean DialogSelect(const EventRecord *theEvent,DialogPtr *theDialog,short *itemHit);
void DrawDialog(DialogPtr theDialog);
void UpdateDialog(DialogPtr theDialog,RgnHandle updateRgn);
OSStatus SetModalDialogEventMask(DialogPtr inDialog,EventMask inMask);
OSStatus GetModalDialogEventMask(DialogPtr inDialog,EventMask *outMask);
OSStatus SetDialogTimeout(DialogPtr inDialog,SInt16 inButtonToPress,UInt32 inSecondsToWait);
OSStatus GetDialogTimeout(DialogPtr inDialog,SInt16 *outButtonToPress,
UInt32 *outSecondsToWait,UInt32 *outSecondsRemaining);
Creating a Routine Descriptor For an Event Filter Function
#define NewModalFilterProc(userRoutine)
(ModalFilterUPP) NewRoutineDescriptor((ProcPtr)(userRoutine),
uppModalFilterProcInfo,
GetCurrentArchitecture())
|
