Discussion

The Alert function displays an alert box or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box. The Alert function creates the alert defined in the specified alert resource and its corresponding extended alert resource. The function calls the current alert sound function and passes it the sound number specified in the alert resource for the current alert stage. If no alert box is to be drawn at this stage, Alert returns –1 otherwise, it uses the NewDialog function to create and display the alert box. The default system window colors are used unless your application provides an alert color table resource with the same resource ID as the alert resource. The Alert function uses the ModalDialog function to get and handle most events for you.

The Alert function does not display a default icon in the upper-left corner of the alert box you can leave this area blank, or you can specify your own icon in the alert’s item list resource, which in turn is specified in the alert resource.

The Alert function continues calling ModalDialog until the user selects an enabled control (typically a button), at which time the Alert function removes the alert box from the screen and returns the item number of the selected control. Your application then responds as appropriate when the user clicks this item.

Your application should never draw its own default rings. Prior to Mac OS 8, the Alert function would only redraw the default button ring once and never redraw it on an update event. However, when Appearance is available, default rings do redraw when you call Alert.

See also the functions NoteAlert , CautionAlert , and StopAlert.

Discussion

To be Appearance-compliant, your program should use the AppendDialogItemList function rather than the AppendDITL function. Unlike AppendDITL, the AppendDialogItemList function takes a 'DITL' resource ID instead of a handle as the parameter describing the dialog item list to be appended, and it properly appends entries from a dialog font table ( 'dftb') resource, if there is a 'dftb' resource with the same resource ID as the 'DITL' resource.

The AppendDialogItemList function adds the items in the item list resource specified in the parameter ditlID to the items of a dialog box. This is especially useful if several dialog boxes share a single item list resource, because you can use AppendDialogItemList to add items that are appropriate for individual dialog boxes. Your application can use the Resource Manager function GetResource to get a handle to the item list resource whose items you wish to add.

You typically create an invisible dialog box, call the AppendDialogItemList function, then make the dialog box visible by using the Window Manager function ShowWindow.

Discussion

The AppendDITL function adds the items specified in the theHandle parameter to the items of a dialog box (handle-based). This function is especially useful if several dialog boxes share a single item list resource, because you can use AppendDITL to add items that are appropriate for individual dialog boxes. Your application can use the Resource Manager function GetResource to get a handle to the item list resource whose items you wish to add.

In the parameter method, you specify how to append the new items, as follows:

• If you use the overlayDITL constant, AppendDITL superimposes the appended items over the dialog box. That is, AppendDITL interprets the coordinates of the display rectangles for the appended items (as specified in their item list resource) as local coordinates within the dialog box.

• If you use the appendDITLRight constant, AppendDITL appends the items to the right of the dialog box by positioning the display rectangles of the appended items relative to the upper-right coordinate of the dialog box. The AppendDITL function automatically expands the dialog box to accommodate the new dialog items.

• If you use the appendDITLBottom constant, AppendDITL appends the items to the bottom of the dialog box by positioning the display rectangles of the appended items relative to the lower-left coordinate of the dialog box. The AppendDITL function automatically expands the dialog box to accommodate the new dialog items.

• You can also append a list of items relative to an existing item by passing a negative number in the parameter method. The absolute value of this number is interpreted as the item in the dialog box relative to which the new items are to be positioned. For example, if you pass –2, the display rectangles of the appended items are offset relative to the upper-left corner of item number 2 in the dialog box.

You typically create an invisible dialog box, call the AppendDITL function, then make the dialog box visible by using the Window Manager function ShowWindow.

Discussion

The AutoSizeDialog function is useful in situations such as localization, where the size of a static text field (and the dialog box that contains it) may need to be altered to accommodate a change in the size of the static text.

For each static text item AutoSizeDialog finds in the item list resource, it adjusts the static text field and the bottom of the dialog box window to accommodate the text. Any items below a static text field are moved down. If the dialog box is visible when this function is called, it is hidden, resized, and then shown. If the dialog box has enough room to show the text as is, no resizing is done.

Note that the AutoSizeDialog function does not process update events for your dialog box, so your program must call the DrawDialog function or the DialogSelect function to process the update event generated from showing the window.

Discussion

Displays an alert box with a caution icon in its upper-left corner or, if appropriate for the alert stage, to play an alert sound instead of or in addition to displaying the alert box.

The CautionAlert function is the same as the Alert function except that, before drawing the items in the alert box, CautionAlert draws the caution icon in the upper-left corner. The caution icon has resource ID 2, which you can also specify with the constant kCautionIcon. By default, the Dialog Manager uses the standard caution icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 2.

Use a caution alert to alert the user of an operation that may have undesirable results if it’s allowed to continue. Give the user the choice of continuing the action (by clicking an OK button) or stopping it (by clicking a Cancel button).

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the CautionAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call CautionAlert.

See also the functions NoteAlert and StopAlert.

Discussion

The CloseDialog function removes a dialog box from the screen and deletes it from the window list. The CloseDialog function releases the memory occupied by

• the data structures associated with the dialog box (such as its structure, content, and update regions)

• all the items in the dialog box (except for pictures and icons, which might be shared by other resources) and any data structures associated with them

Generally, you should provide memory for the dialog structure of modeless dialog boxes when you create them. (You can let the Dialog Manager provide memory for modal and movable modal dialog boxes.) You should then use CloseDialog to close a modeless dialog box when the user clicks the close box or chooses Close from the File menu.

Because CloseDialog does not dispose of the dialog resource or the item list resource, it is important to make these resources purgeable. Unlike GetNewDialog , NewColorDialog does not use a copy of the item list resource. Thus, if you use NewColorDialog to create a dialog box, you may want to use CloseDialog to keep the item list resource in memory even if you didn’t supply a pointer to the memory.

Discussion

You typically use CountDITL in conjunction with ShortenDITL to remove items from a dialog box.

Discussion

This function should be used in conjunction with RunStandardAlert. After CreateStandardAlert returns, the alert is still invisible. RunStandardAlert shows the alert and runs a modal dialog loop to process events in the alert.

Discussion

This function should be used in conjunction with ShowSheetWindow. After CreateStandardSheet returns, the alert is still invisible. ShowSheetWindow will show the alert as a sheet and then return. Events in the sheet are handled asynchronously; the application should be prepared for the sheet window to be part of its window list while running its own event loop.

When a button in the sheet is pressed, the event target passed to CreateStandardSheet will receive a command event with one of the following commands: kHICommandOK, kHICommandCancel, or kHICommandOther. The system takes care of closing the sheet and releasing the alert. Therefore after using ShowSheetWindow, you do not need to call HideSheetWindow or DisposeDialog.

Typically, the event target you pass in the notifyTarget parameter is the parent window of the sheet. A standard practice is to install a command event handler on the parent window just before showing the sheet window, and to remove the handler from the parent window after the sheet has been closed.

It is also possible to install a handler on the sheet window itself, in which case you would pass NULL in the notifyTarget parameter, since the command event is automatically sent to the sheet window already. If you install a handler on the sheet itself, make sure to return eventNotHandledErr from your handler, because CreateStandardSheet installs its own handler on the sheet and that handler must be allowed to run to close the sheet window and release the alert.

Discussion

The DialogCopy function checks whether the dialog box has any edit text items and, if so, applies the TextEdit function TECopy to the selected text. Your application should test whether a dialog box is the frontmost window when handling mouse-down events in the Edit menu and then call this function when appropriate.

Discussion

The DialogCut function checks whether the dialog box has any edit text items and, if so, applies the TextEdit function TECut to the selected text. Your application should test whether a dialog box is the frontmost window when handling mouse-down events in the Edit menu and then call this function when appropriate.

Discussion

The DialogDelete function checks whether the dialog box has any edit text items and, if so, applies the TextEdit function TEDelete to the selected text. Your application should test whether a dialog box is the frontmost window when handling mouse-down events in the Edit menu and then call this function when appropriate.

Discussion

The DialogPaste function checks whether the dialog box has any edit text items and, if so, applies the TextEdit function TEPaste to the selected edit text item. Your application should test whether a dialog box is the frontmost window when handling mouse-down events in the Edit menu and then call this function when appropriate.

Discussion

The DialogSelect function handles most of the events relating to a dialog box. Through its itemHit parameter, it returns the item number of the item selected by the user. Through the parameter theDialog, it returns a pointer to the dialog structure for the dialog box where the event occurred. In all other cases, the DialogSelect function returns false. When DialogSelect returns true, do whatever is appropriate as a response to the event involving that item in that particular dialog box; when it returns false, do nothing.

Generally, only controls should be enabled in a dialog box; therefore your application should normally respond only when DialogSelect returns true after the user clicks an enabled control, such as the OK button.

The DialogSelect function first obtains a pointer to the window containing the event. For update and activate events, the event structure contains the window pointer. For other types of events, DialogSelect calls the Window Manager function FrontWindow. The Dialog Manager then makes this window the current graphics port by calling the QuickDraw function SetPort. Then DialogSelect prepares to handle the event by setting up text information if there are any edit text items in the active dialog box.

When an item is a control defined in a control resource, the rectangle added to the update region is the rectangle defined in the control resource, not the display rectangle defined in the item list resource.

The DialogSelect function handles the event as follows:

• In response to an activate or update event for the dialog box, DialogSelect activates or updates its window and returns false.

• If a key-down event or an auto-key event occurs and there’s an edit text item in the dialog box, DialogSelect uses TextEdit to handle text entry and editing, and DialogSelect returns true for a function result. Through its itemHit parameter, DialogSelect returns the item number.

• If a key-down event or an auto-key event occurs and there’s no edit text item in the dialog box, DialogSelect returns false.

• If the user presses the mouse button while the cursor is in an edit text item, DialogSelect responds to the mouse activity as appropriate—that is, either by displaying an insertion point or by selecting text. If the edit text item is disabled, DialogSelect returns false. If the edit text item is enabled, DialogSelect returns true and through its itemHit parameter returns the item number. Normally, edit text items are disabled, and you use the GetDialogItemText function to read the information in the items only after the OK button is clicked.

• If the user presses the mouse button while the cursor is in a control, DialogSelect tracks the control. If the user releases the mouse button while the cursor is in an enabled control, DialogSelect returns true for a function result and through its itemHit parameter returns the control’s item number. Your application should respond appropriately—for example, by performing a command after the user clicks the OK button.

• If the user presses the mouse button while the cursor is in any other enabled item in the dialog box, DialogSelect returns true for a function result and through its itemHit parameter returns the item’s number. Generally, only controls should be enabled. If your application creates a complex control—such as one that measures how far a dial is moved—your application must handle mouse events in that item before passing the event to DialogSelect.

• 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, DialogSelect does nothing.

• If the event isn’t one that DialogSelect specifically checks for (if it’s a null event, for example), and if there’s an edit text item in the dialog box, DialogSelect calls the TextEdit function TEIdle to make the insertion point blink.

Discussion

The DisposeDialog function calls CloseDialog and, in addition, releases the memory occupied by the dialog box’s item list resource and the dialog structure. Call DisposeDialog when you’re done with a dialog box if you pass null in the dStorage parameter to GetNewDialog , NewColorDialog , or NewDialog.

Discussion

The DrawDialog function draws all dialog items, calls the Control Manager function DrawOneControl to draw all controls, and calls the TextEdit function TEUpdate to update all static and edit text items and to draw their display rectangles. The DrawDialog function also calls the application-defined items’ draw functions if the items’ rectangles are within the update region.

DialogSelect , ModalDialog , Alert , StopAlert , NoteAlert , and CautionAlert use DrawDialog automatically. If you use GetNewDialog to create a dialog box but don’t use any of these other Dialog Manager functions when handling events in the dialog box, you can use DrawDialog to redraw the contents of the dialog box when it’s visible. If the dialog box is invisible, first use the Window Manager function ShowWindow and then use DrawDialog.

Discussion

The function FindDialogItem is useful for changing the cursor when the user moves the cursor over a particular item.

To get the proper item number before calling the GetDialogItem function or the SetDialogItem function, add 1 to the result of FindDialogItem, as shown here:

theItem = FindDialogItem(theDialog, thePoint) + 1;

Note that FindDialogItem returns the item number of disabled items as well as enabled items.

Discussion

You can use the GetAlertStage function to ensure that your application deactivates the active window only if an alert box is to be displayed at that stage.

Discussion

If you don’t explicitly call GetDialogCanceltItem, the standard filter function treats item 2 as the cancel item.

Discussion

If you don’t explicitly call GetDialogDefaultItem, the standard filter function treats item 1 as the default item.

Discussion

The GetDialogItem function produces the item type, a handle to the item (or, for application-defined draw functions, the function pointer), and the display rectangle for a specified item in an item list resource. When a control hierarchy is present in the dialog box, GetDialogItem gets the appropriate information (for example, a text handle) from the controls. If you wish to get a control handle for a dialog item in an embedding hierarchy, see GetDialogItemAsControl.

You should call GetDialogItem before calling functions such as SetDialogItemText that need a handle to a dialog item.

See also the function SetDialogItem.

Discussion

When an embedding hierarchy is established, GetDialogItemAsControl produces a handle to the embedded controls (except Help items). It should be used instead of GetDialogItem when an embedding hierarchy is established.

Discussion

The GetDialogItemText function will only return the first 255 characters in an edit text item.

Discussion

When the Appearance Manager is available and an embedding hierarchy is established, you should call the Control Manager function GetKeyboardFocus instead of GetDialogKeyboardFocusItem to return the item number of the item in a dialog box that has keyboard focus.

The GetDialogKeyboardFocusItem function accesses the edit field in the dialog structure. GetDialogKeyboardFocusItem should only be called when there is no embedding hierarchy in the dialog box.

Discussion

Discussion

Also see the function SetDialogTimeout.

Discussion

Also see the function SetModalDialogEventMask.

Discussion

The GetNewDialog function creates a dialog structure from information in a dialog resource and an extended dialog resource (if it exists) and returns a pointer to the dialog structure. You can use this pointer with Window Manager or QuickDraw functions to manipulate the dialog box. If the dialog resource specifies that the dialog box should be visible, the dialog box is displayed. If the dialog resource specifies that the dialog box should initially be invisible, use the Window Manager function ShowWindow to display the dialog box.

The dialog resource contains a resource ID that specifies both the dialog box’s item list ( 'DITL') resource and its dialog font table ( 'dftb') resource. After calling the Resource Manager to read these resources into memory (if they are not already in memory), GetNewDialog makes a copy of the 'DITL' resource and uses that copy; thus you may have several dialog boxes with identical items.

If you supply a dialog color table ( 'dctb') resource with the same resource ID as the dialog resource, GetNewDialog uses NewColorDialog and returns a pointer to a color graphics port. If no dialog color table resource is present, GetNewDialog uses NewDialog to return a pointer to a black-and-white graphics port, although system software draws the window frame using the system’s default colors. However, if the Appearance Manager is available and the kDialogFlagsUseThemeBackground feature bit of the extended dialog resource is set, then the 'dctb' resource is ignored and a color graphics port is created.

Discussion

The GetStdFilterProc function gets a pointer to the standard filter function. You must dispatch the function yourself using the CallModalFilterProc macro; see ModalFilterProcPtr.

You normally don’t need to use GetStdFilterProc unless your development environment doesn’t include the code required to support StdFilterProc.

Discussion

The HideDialogItem function hides the item specified by itemNo by giving it a display rectangle that’s off the screen. Specifically, if the left coordinate of the item’s display rectangle is less than 8192 (hexadecimal 0x2000), HideDialogItem adds 16,384 (hexadecimal 0x4000) to both the left and right coordinates of the rectangle. If the item is already hidden (that is, if the left coordinate is greater than 8192), HideDialogItem does nothing. To redisplay an item that’s been hidden by HideDialogItem, you can use the ShowDialogItem function.

Discussion

When IsDialogEvent returns false, pass the event to the rest of your event-handling code. When IsDialogEvent returns true, pass the event to DialogSelect after testing for the events that DialogSelect does not handle.

A dialog structure includes a window structure. When you use the GetNewDialog , NewDialog , NewFeaturesDialog , or NewColorDialog functions to create a dialog box, the Dialog Manager sets the windowKind field in the window structure to dialogKind. To determine whether the active window is a dialog box, IsDialogEvent checks the windowKind field.

Before passing the event to DialogSelect, you should perform the following tests whenever IsDialogEvent returns true :

• Check whether the event is a key-down event for the Return, Enter, Esc, or Command-period keystrokes. When the user presses the Return or Enter key, your application should respond as if the user had clicked the default button; when the user presses Esc or Command-period, your application should respond as if the user had clicked the Cancel button. Use the Control Manager function HiliteControl to highlight the applicable button for 8 ticks.

• At this point, you may also want to check for and respond to any special events that you do not wish to pass to DialogSelect or that require special processing before you pass them to DialogSelect. You would need to do this, for example, if the dialog box needs to respond to disk-inserted events.

• Check whether the event is an update event for a window other than the dialog box and, if it is, update your window.

• For complex items that you create, such as pictures or application-defined items that emulate complex controls, test for and respond to mouse events inside those items as appropriate. When DialogSelect calls the Control Manager function TrackControl, it does not allow you to specify the action function necessary for anything more complex than a button, radio button, or checkbox. If you need a more complex control (for example, one that measures how long the user holds down the mouse button or how far the user has moved an indicator), you can create your own control or a picture or an application-defined item that draws a control-like object in your dialog box. You must then test for and respond to those events yourself.

If your application uses IsDialogEvent to help handle events when you display a movable modal dialog box, perform the following additional tests before passing events to DialogSelect :

• Test for mouse-down events in the title bar of the movable modal dialog box and respond by dragging the dialog box accordingly.

• Test for and respond to mouse-down events in the Apple menu and, if the movable modal dialog box includes edit text items, in the Edit menu. (You should disable all other menus when you display a movable modal dialog box.)

• Play the system alert sound for every other mouse-down event outside the movable modal dialog box.

Discussion

Call the ModalDialog function immediately after displaying a modal or movable modal dialog box. Your application should continue calling ModalDialog until the user dismisses your dialog.

For modal dialogs, the ModalDialog function repeatedly handles events until an event involving an enabled dialog box item—such as a click in a radio button, for example—occurs. If the event is a mouse-down event outside the content region of the dialog box, ModalDialog plays the system alert sound and gets the next event.

For movable modal dialogs, if the kDialogFlagsHandleMovableModal feature bit in the extended dialog resource is set, the ModalDialog function will handle all standard movable modal user interactions, such as dragging a dialog box by its title bar and allowing the user to switch into another application. However, a difference between the ModalDialog function’s behavior with movable modal and modal dialogs is that, with movable modal dialogs, your event filter function receives all events. If you want the Dialog Manager to assist you in handling events in movable modal dialog boxes, call GetStdFilterProc and StdFilterProc.

For events inside the dialog box, ModalDialog passes the event to the event filter function pointed to in the modalFilter parameter before handling the event. When the event filter returns false, ModalDialog handles the event. If the event filter function handles the event, returning true, ModalDialog performs no more event handling.

If you set the modalFilter parameter to null, the standard event filter function is executed. The standard event filter function checks whether

• the user has pressed the Enter or Return key and, if so, returns the item number of the default button

• the user has pressed the Escape key or Command-period and, if so, returns the item number of the Cancel button

• the cursor is over an editable text box, and optionally changes the cursor to an I-beam whenever this is the case

If you set the modalFilter parameter to point to your own event filter function, that function can use the standard filter function to accomplish the above tasks. (To do so, you can call GetStdFilterProc, and dispatch the event to the standard filter function yourself, or you can call StdFilterProc, which obtains a ModalFilterUPP for the standard filter function and then dispatches the function.) Additionally, your own event filter function should also

• handle update events, so that background processes can receive processor time, and return false

• return false for all events that your event filter function doesn’t handle

You can also use your event filter function to test for and respond to keyboard equivalents and more complex events—for instance, the user dragging the cursor within an application-defined item. You can use your same event filter function in most or all of your alert and modal dialog boxes.

If the event filter function does not handle the event (returning false), ModalDialog handles the event as follows:

• In response to an activate or update event for the dialog box, ModalDialog activates or updates its window.

• If the user presses the mouse button while the cursor is in an editable text item, ModalDialog responds to the mouse activity as appropriate—that is, either by displaying an insertion point or by selecting text. If a key-down event occurs and there’s an editable text item, ModalDialog uses TextEdit to handle text entry and editing automatically. If the editable text item is enabled, ModalDialog produces its item number after it receives either the mouse-down or key-down event. Normally, editable text items 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 user presses the mouse button while the cursor is in a control, ModalDialog calls the Control Manager function TrackControl. If the user releases the mouse button while the cursor is in an enabled control, ModalDialog produces the control’s item number. Your application should respond appropriately—for example, by performing a command after the user clicks the OK button.

• If the user presses the mouse button while the cursor is in any other enabled item in the dialog box, ModalDialog produces the item’s number, and your application should respond appropriately. Generally, only controls should be enabled. If your application creates a control more complex than a button, radio button, or checkbox, your application must handle events inside that item with your event filter function.

• If the user presses the mouse button while the cursor is in a disabled item or in no item, or if any other event occurs, ModalDialog does nothing.

Discussion

The MoveDialogItem function moves a dialog item to a specified location in a window. MoveDialogItem ensures that if the item is a control, the control rectangle and the dialog item rectangle (maintained by the Dialog Manager) are always the same.

Discussion

The NewColorDialog function creates a dialog box as specified by its parameters. The first eight parameters ( dStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog box. You can use this pointer with Window Manager or QuickDraw functions to manipulate the dialog box.

The Dialog Manager uses the default window colors for the dialog box. By using the system’s default colors, you ensure that your application’s interface is consistent with that of the Finder and other applications. However, if you absolutely feel compelled to break from this consistency, you can use the Window Manager function SetWinColor to use your own dialog color table resource that specifies colors other than the default colors. Be aware, however, that nonstandard colors in your alert and dialog boxes may initially confuse your users.

The Window Manager creates an auxiliary window structure for the color dialog box. You can access this structure with the Window Manager function GetAuxWin. If the dialog box’s content color isn’t white, it’s a good idea to call NewColorDialog with the visible flag set to false. After the color table and color item list resource are installed, use the Window Manager function ShowWindow to display the dialog box if it’s the frontmost window. If the dialog box is a modeless dialog box that is not in front, use the Window Manager function ShowHide to display it.

The NewColorDialog function generates an update event for the entire window contents. Thus, with the exception of controls, items aren’t drawn immediately. The Dialog Manager calls the Control Manager to draw controls, and the Control Manager draws them immediately. So that the controls won’t be drawn twice, the Dialog Manager calls the Window Manager function ValidRect for the enclosing rectangle of each control. If you find that there is too great a lag between the drawing of controls and the drawing of other items, try making the dialog box initially invisible and then calling the Window Manager function ShowWindow to show it.

Discussion

The NewDialog function is identical to the NewColorDialog function, except that NewDialog returns a pointer to a black-and-white graphics port. See the discussion of NewColorDialog for descriptions of the parameters that you also pass to NewDialog.

The NewDialog function creates a dialog box as specified by its parameters and returns a pointer to a black-and-white graphics port for the new dialog box. The first eight parameters ( wStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog box.

Discussion

The NewFeaturesDialog function creates a dialog box without using 'DLOG' or 'dlgx' resources. Although the inItemListHandle parameter specifies an item list ( 'DITL') resource for the dialog box, the corresponding dialog font table ( 'dftb') resource is not automatically accessed. You must explicitly set the dialog box’s control font style(s) individually.

Discussion

Discussion

The NoteAlert function displays an alert box with a note icon in its upper-left corner or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box.

The NoteAlert function is the same as the Alert function except that, before drawing the items in the alert box, NoteAlert draws the note icon in the upper-left corner. The note icon has resource ID 1, which you can also specify with the constant noteIcon. By default, the Dialog Manager uses the standard note icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 1.

Use a note alert to inform users of a minor mistake that won’t have any disastrous consequences if left as is. Usually this type of alert simply offers information, and the user responds by clicking an OK button. Occasionally, a note alert may ask a simple question and provide a choice of responses.

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the NoteAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call NoteAlert.

See also the functions CautionAlert and StopAlert.

Discussion

The ParamText function replaces the special strings ^0 through ^3 in the static text items of all subsequently created alert and dialog boxes with the text strings you pass as parameters. Pass empty strings (not null) for parameters not used.

Discussion

The ResetAlertStage function resets every alert to a first-stage alert.

Discussion

This function displays and runs an alert created by CreateStandardAlert. RunStandardAlert handles all user interaction with the alert.

Discussion

If the item in the itemNo parameter is an edit text item that contains text, the SelectDialogItemText function sets the text selection range to extend from the character position specified in the strtSel parameter up to but not including the character position specified in the endSel parameter. The selection range is highlighted unless strtSel equals endSel, in which case a blinking vertical bar is displayed to indicate an insertion point at that position. If the edit text item doesn’t contain text, SelectDialogItemText displays the insertion point.

You can select the entire text by specifying the number 0 in the strtSel parameter and the number 32767 in the endSel parameter.

For example, if the user makes an unacceptable entry in the edit text item, your application can display an alert box reporting the problem and then use SelectDialogItemText to select the entire text so it can be replaced by a new entry. Without this function, the user would have to select the item before making the new entry.

Discussion

If you intend to use the standard filter function, you can first use the functions SetDialogDefaultItem and SetDialogCancelItem to set the items that the standard filter function will treat as the default and cancel items. You can use GetDialogDefaultItem and GetDialogCancelItem to determine the dialog item numbers that the standard filter function will treat as the default and cancel items.

If you call the SetDialogCancelItem function before you call the standard filter function, the standard filter function automatically interprets Escape and Command-period keypresses to mean that the specified cancel item has been selected.

If you don’t explicitly call SetDialogCancelItem, the standard filter function treats item 2 as the cancel item.

Discussion

If you call the SetDialogDefaultItem function before you call the standard filter function, the standard filter function automatically interprets Return and Enter keypresses to mean that the specified default item has been selected.

If you don’t explicitly call SetDialogDefaultItem, the standard filter function treats item 1 as the default item.

Discussion

For subsequently created dialog and alert boxes, SetDialogFont sets the font of the dialog or alert box’s graphics port to the specified font. If you don’t call this function, the system font is used. The SetDialogFont function does not affect titles of controls, which are always displayed in the system font.

Discussion

The SetDialogItem function sets the item specified by the itemNo parameter for the specified dialog box. If an embedding hierarchy exists, however, you cannot change the type or handle of an item, although application-defined item drawing functions can still be set.

See also the function GetDialogItem.

Discussion

The SetDialogItemText function sets and redraws text strings for static text and editable text fields. SetDialogItemText is useful for supplying a default text string—such as a document name—for an editable text field while your application is running.

Discussion

Your application calls the SetDialogTimeout function each time you wish to start a countdown of the specified duration for a given modal dialog box. When the amount of time specified in the inSecondsToWait parameter has elapsed, the Dialog Manager simulates a click on the button specified in the inButtonToPress parameter. If your application calls SetDialogTimeout again, or if any event is received for the dialog box, the countdown is restarted.

In order to use SetDialogTimeout with a given modal dialog box, your application must handle events for the dialog box through the ModalDialog function. The Dialog Manager will not simulate an item selection for the dialog box until ModalDialog processes an event (including null events).

Also see the function GetDialogTimeout.

Discussion

You should call SetDialogTracksCursor before you call the standard filter function.

Discussion

Your application can use the SetModalDialogEventMask function to specify the events received by the ModalDialog function for a given 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 use SetModalDialogEventMask to change the ModalDialog function’s event mask, you should pass ModalDialog a pointer to your own event filter function to handle any added events.

Also see the function GetModalDialogEventMask.

Discussion

The ShortenDITL function removes the specified number of items from the dialog box. This function is especially useful if several dialog boxes share a single item list resource, because you can use ShortenDITL to remove items as necessary for individual dialog boxes.

You typically create an invisible dialog box, call the ShortenDITL function, then make the dialog box visible by using the Window Manager function ShowWindow. Note that ShortenDITL does not automatically resize the dialog box; you can use AutoSizeDialog or the Window Manager function SizeWindow if you need to resize the dialog box.

Discussion

The ShowDialogItem function redisplays the item specified in the itemNo parameter by restoring the display rectangle the item had prior to HideDialogItem. If the left coordinate of the item’s display rectangle is greater than 8192, ShowDialogItem subtracts 16,384 from both the left and right coordinates of the rectangle. If the item is already visible (that is, if the left coordinate is less than 8192), ShowDialogItem does nothing.

The ShowDialogItem function adds the rectangle that contained the item to the update region so that it will be drawn. Note that if the item is a control you define in a control (' CNTL ') resource, the rectangle added to the update region is the rectangle defined in the control resource, not the display rectangle defined in the item list resource. If the item is an edit text item, ShowDialogItem activates it by calling the TextEdit function TEActivate.

Discussion

The SizeDialogItem function resizes a dialog item to a specified size. If the dialog item is a control, the control rectangle and the dialog item rectangle (maintained by the Dialog Manager) are always the same.

Discussion

The StandardAlert function displays an alert box based on the values you pass it. You can pass the error text you wish displayed in the error and explanation parameters, and customize the alert button text by filling in the appropriate fields of the standard alert structure passed in the inAlertParam parameter.

StandardAlert automatically resizes the height of a dialog box to fit all static text. It ignores alert stages and therefore provides no corresponding alert sounds.

Discussion

To use the standard filter function from within your own filter function, you can call GetStdFilterProc , then dispatch the event to the standard filter function yourself; or you can call StdFilterProc, which performs both steps for you. Calling StdFilterProc is equivalent to calling GetStdFilterProc and then calling ModalFilterProcPtr.

Discussion

The StopAlert function displays an alert box with a stop icon in its upper-left corner or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box.

The StopAlert function is the same as the Alert function except that, before drawing the items in the alert box, StopAlert draws the stop icon in the upper-left corner. The stop icon has resource ID 0, which you can also specify with the constant stopIcon . By default, the Dialog Manager uses the standard stop icon from the System file. You can change this icon by providing your own 'ICON' resource with resource ID 0.

Use a stop alert to inform the user that a problem or situation is so serious that the action cannot be completed. Stop alerts typically have only a single button (OK), because all the user can do is acknowledge that the action cannot be completed.

Your application should never draw its own default rings or alert icons. Prior to Mac OS 8, the StopAlert function would only redraw the alert icon and default button ring once and never redraw them on an update event. However, when Appearance is available, alert icons and default rings do redraw when you call StopAlert.

See also the functions NoteAlert and CautionAlert.

Discussion

The UpdateDialog function redraws only the region in a dialog box specified in the updateRgn parameter. Your application generally should not use UpdateDialog. The Dialog Manager generally handles update events in alert and dialog boxes. Alert. StopAlert , NoteAlert , and CautionAlert handle update events on their own.

Instead of drawing the entire contents of the specified dialog box, UpdateDialog draws only the items in the specified update region. You can use UpdateDialog in response to an update event, and you should usually bracket it by calls to the Window Manager functions BeginUpdate and EndUpdate. UpdateDialog uses the QuickDraw function SetPort to make the dialog box the current graphics port.

Discussion

To supplement the Dialog Manager’s ability to handle events in the Mac OS multitasking environment, you should provide an event filter function that the Dialog Manager calls whenever it displays alert boxes and modal dialog boxes. This function can receive all events that are sent to your application.

The ModalDialog function and, in turn, the Alert , NoteAlert , StopAlert , and CautionAlert functions return the item number that your event filter function returns in the itemHit parameter in their own itemHit parameters.

For alert and modal dialog boxes, the Dialog Manager provides a standard event filter function that checks whether

• the user has pressed the Enter or Return key and, if so, returns the item number of the default button

• the user has pressed the Escape key or Command-period and, if so, returns the item number of the Cancel button

• the cursor is over edit text in a dialog box, and optionally changes the cursor to an I-beam whenever this is the case

If the dialog box is movable modal and the kDialogHandleMovable bit is set, your filter function will receive all events (including apple events and update events) that your application receives.

Your own filter function should use the standard filter function to accomplish these tasks. To do so, you can call GetStdFilterProc , and dispatch the event to the standard filter function yourself; or you can call StdFilterProc , which obtains a ModalFilterUPP for the standard filter function and then dispatches the function.

Your event filter function should also perform the following tasks:

• update your windows in response to update events and return false. If you do not handle update events for all the windows in your application, other processes won’t get time.

• return false for all events that your event filter function doesn’t handle

You can also use the event filter function to test for and respond to keyboard equivalents and more complex events—for instance, the user dragging the cursor in an application- defined item. For example, if you provide an application-defined item that requires you to measure how long the user holds down the mouse button or how far the user drags the cursor, use the event filter function to handle events inside that item.

Movable modal dialog boxes receive all events (not just those masked by the Event message mask).

In all alert and dialog boxes, any buttons that are activated by key sequences should highlight to indicate which item has been selected. Use the Control Manager function HiliteControl to highlight a button for 8 ticks, long enough to be noticeable but not so long as to be annoying. The Control Manager performs this action whenever users click a button, and your application should do this whenever the user presses the keyboard equivalent of a button click.

For modal dialog boxes that contain edit text items, your application should handle menu bar access to allow use of your Edit menu and its Cut, Copy, Paste, Clear, and Undo commands. Your event filter function should then test for and handle clicks in your Edit menu and keyboard equivalents for the appropriate commands in your Edit menu. Your application should respond by using the functions DialogCut , DialogCopy , DialogPaste , and DialogDelete to support the Cut, Copy, Paste, and Clear commands.

For an alert box, you specify a universal procedure pointer to your event filter function in a parameter that you pass to the Alert , StopAlert , CautionAlert , and NoteAlert functions. For a modal dialog box, specify a pointer to your event filter function in a parameter that you pass to UpdateDialog.

The Dialog Manager defines the data type ModalFilterUPP to identify this application-defined function:

typedef UniversalProcPtr ModalFilterUPP;

You typically use the NewModalFilterProc macro like this:

ModalFilterUPP myEventFilterProc;

myEventFilterProc = NewModalFilterProc(MyEventFilter);

Discussion

For each of the four alert stages that can be reported in the soundNumber parameter, your function can emit any sound that you define. When the Dialog Manager calls your function, it passes 0 as the sound number for alert sounds specified by the silent constant in the alert resource. The Dialog Manager passes 1 for sounds specified by the sound1 constant, 2 for sounds specified by the sound2 constant, and 3 for sounds specified by the sound3 constant.

The Dialog Manager defines the universal procedure pointer SoundUPP to identify this application-defined function:

typedef UniversalProcPtr SoundUPP; /

You typically use the NewSoundProc macro like this:

SoundUPP mySoundProc;

mySoundProc = NewSoundProc(MyAlertSound)

Discussion

When the Appearance Manager is available and an embedding hierarchy is established in a dialog box, you should provide the Control Manager user pane drawing function MyUserPaneDrawCallback instead of the user item drawing function MyUserItemCallback to draw an application-defined control (a dialog item becomes a control in a dialog box with an embedding hierarchy).

You can provide other user pane application-defined functions to hit test, track, perform idle processing, handle keyboard, activate, and deactivate event processing, handle keyboard focus, and set the background color or pattern in a user pane control.

When calling your draw function, the Dialog Manager sets the current port to the dialog box’s graphics port. Normally, you create an invisible dialog box and then use the Window Manager function ShowWindow to display the dialog box.

Before you display the dialog box, use SetDialogItem to install this function in the dialog structure. Before using SetDialogItem, you must first use GetDialogItem to obtain a handle to an item of type userItem.

If you enable the application-defined item that you draw with this function, UpdateDialog and StdFilterProc return the item’s number when the user clicks that item. If your application needs to respond to a user action more complex than this (for example, if your application needs to measure how long the user holds down the mouse or how far the user drags the cursor), your application must track the cursor itself. If you use ModalDialog, your event filter function must handle events inside the item; if you use DialogSelect, your application must handle events inside the item before handing events to DialogSelect.

The Dialog Manager defines the data type UserItemUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr UserItemUPP;

You typically use the NewUserItemProc macro like this:

UserItemUPP myItemProc;

myItemProc = NewUserItemProc (MyItem);

Discussion

A standard alert structure of type AlertStdAlertParamRec can be used when you call the function StandardAlert to customize the alert box. The AlertStdAlertParamRec type is available with Appearance Manager 1.0 and later.

Discussion

You pass this structure when calling CreateStandardAlert or CreateStandardSheet.

Discussion

A dialog structure of type DialogRecord is created whenever you call the functions Alert or GetNewDialog. These functions incorporate information from your item list resource and your alert resource or dialog resource into this structure. Your application generally should not create a dialog structure or directly access its fields.

Discussion

For more information, see the description of the ModalFilterUPP () callback function.

Discussion

For more information, see the description of the ModalFilterYDUPP () callback function.

Discussion

For more information, see the description of the SoundUPP () callback function.

Discussion

For more information, see the description of the UserItemUPP () callback function.

Discussion

You can use these constants in the defaultButton and cancelButton fields in the standard alert structure to specify which buttons act as the default and Cancel buttons in the standard alert structure. These constants are also returned in the itemHit parameter of StandardAlert. Alert button constants are available with Appearance Manager 1.0 and later.

Discussion

You can use these constants in the defaultText, cancelText, and otherText fields of the standard alert structure to specify the default text for the OK, Cancel, and Don’t Save buttons. Alert default text constants are available with Appearance Manager 1.0 and later.

Discussion

You can set these bits in the alert flags field of the extended alert resource to specify the alert box’s Appearance-compliant features. Alert feature flag constants are available with Appearance Manager 1.0 and later.

Discussion

You can pass these constants in the alertID parameter of StopAlert , NoteAlert, and CautionAlert to specify the resource ID of the alert box icon you wish displayed.

Discussion

You can pass constants of type AlertType in the inAlertType parameter of StandardAlert to specify the type of alert box you wish to create. Alert type constants are available with Appearance Manager 1.0 and later.

Discussion

You can set these bits in the dialog flags field of the extended dialog resource or pass them in the inFlags parameter of NewFeaturesDialog to specify the dialog box’s Appearance-compliant features. Dialog feature flag constants are available with Appearance Manager 1.0 and later.

Discussion

You can set the following bits in the dialog font table resource to specify fields in the dialog font table that should be used. Dialog font flag constants are available with Appearance Manager 1.0 and later.

Discussion

These constants are returned in the itemType parameter of GetDialogItem and can be passed to SetDialogItem and the dialog item list resource to specify dialog item type.

Discussion

You can pass a constant value of type DITLMethod to the function AppendDITL to specify how you want appended dialog items displayed.