Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Dialog Manager Reference

Framework
Carbon/Carbon.h
Declared in
Dialogs.h

Overview

Your application can use the Dialog Manager to alert users to unusual situations and to solicit information from users. For example, in some situations your application might not be able to carry out a command normally, and in other situations the user must specify multiple parameters before your application can execute a command. For circumstances like these, the Macintosh user interface includes these two features:

Virtually all applications need to implement alerts and dialog boxes. To avoid needless development effort, use the Dialog Manager to implement alerts and to create most dialog boxes. It is possible, however–and sometimes desirable–to bypass the Dialog Manager and instead use Window Manager, Control Manager, QuickDraw, and Event Manager routines to create or respond to events in complex dialog boxes.

Carbon supports the majority of the Dialog Manager. However, your application must access Dialog Manager data structures only through the supplied accessor functions. Furthermore, your application must use the functions provided for creating and disposing of Dialog Manager data structures.

Functions by Task

Creating Alert Boxes

Creating and Disposing of Dialog Boxes

Displaying Dialog Boxes and Items

Filtering Dialog Box Events

Handling Events in Dialog Boxes

Handling Text in Alert and Dialog Boxes

Initializing the Dialog Manager

Manipulating Items in Dialog Boxes and Alert Boxes

Simulating User Responses in Dialog Boxes

Using the Standard Filter Function

Miscellaneous

Functions

Alert

Displays an alert box and/or plays an alert sound.

DialogItemIndex Alert (
   SInt16 alertID,
   ModalFilterUPP modalFilter
);

Parameters
alertID

The resource ID of an alert resource and extended alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert. See ‘alrx’ for a description of the extended alert resource.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to null, the Dialog Manager uses the standard event filter function.

Return Value

If no alert box is to be drawn at the current alert stage or the 'ALRT' resource is not found, Alert returns –1 otherwise, it creates and displays the alert box and returns the item number of the control selected by the user see “Alert Button Constants.” See the description of the DialogItemIndex data type.

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.

Special Considerations

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser

The Dialog Manager uses the system alert sound as the error sound unless you change it by calling the ErrorSound function .

Version Notes

This function was changed with Appearance Manager 1.0 to support the extended alert ('alrx') resource.

Availability
Declared In
Dialogs.h

AppendDialogItemList

Adds items to an existing dialog box while your program is running.

OSErr AppendDialogItemList (
   DialogRef dialog,
   SInt16 ditlID,
   DITLMethod method
);

Parameters
dialog

A pointer to the dialog box to which the items in the item list resource specified in the ditlID parameter are to be appended.

ditlID

The resource ID of the item list resource whose items are to be appended to the dialog box specified in the dialog parameter.

method

The manner in which the new items are to be displayed in the dialog box.

If you use the overlayDITL constant, AppendDialogItemList superimposes the appended items over the dialog box by interpreting 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, AppendDialogItemList 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 AppendDialogItemList function automatically expands the dialog box to accommodate the new dialog items.

If you use the appendDITLBottom constant, AppendDialogItemList 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 AppendDialogItemList function automatically expands the dialog box to accommodate the new dialog items.

You can append a list of items relative to an existing item by passing a negative number. 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.

Return Value

A result code. See “Dialog Manager Result Codes.”

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.

Version Notes

This function is available with Appearance Manager 1.0 and later.

Availability
Declared In
Dialogs.h

AppendDITL

Adds items to an existing dialog box while your application is running. 

void AppendDITL (
   DialogRef theDialog,
   Handle theHandle,
   DITLMethod method
);

Parameters
theDialog

A pointer to a dialog structure. This is the dialog structure to which you will add the item list resource specified in the parameter theHandle.

theHandle

A handle to the item list resource whose items you want to append to the dialog box. To avoid item number conflicts, AppendDITL assigns new numbers to the items you are adding. For example, if you have a dialog with item numbers 1-5, and you use AppendDITL to add a 'DITL' resource containing item numbers 1-3, those become item numbers 6-8 in the dialog.

method

The manner in which you want the new items to be displayed in the existing dialog box. You can pass a negative value to offset the appended items from a particular item in the existing dialog box. You can also pass one of the values defined by the DITLMethod constant. See “Dialog Item List Display Constants” for possible values.

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:

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

Special Considerations

The AppendDITL function modifies the contents of the dialog box (for instance, by enlarging it). To use an unmodified version of the dialog box at a later time, your application should use the Resource Manager function ReleaseResource to release the memory occupied by the appended item list resource. Otherwise, if your application calls AppendDITL to add items to that dialog box again, the dialog box remains modified by your previous call—for example, it will still be longer at the bottom if you previously used the appendDITLBottom constant.

Before calling AppendDITL, you should make sure that it is available by using the Gestalt function with the gestaltDITLExtAttr selector. Test the bit indicated by the gestaltDITLExtPresent constant in the response parameter. If the bit is set, then AppendDITL is available.

Availability
Declared In
Dialogs.h

AutoSizeDialog

Automatically resizes static text fields and their dialog boxes to accommodate changed static text.

OSErr AutoSizeDialog (
   DialogRef inDialog
);

Parameters
inDialog

A pointer to a dialog box.

Return Value

A result code. See “Dialog Manager Result Codes.”

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.

Version Notes

This function is available with Appearance Manager 1.0 and later.

Availability
Declared In
Dialogs.h

CautionAlert

Displays an alert box with a caution icon and/or plays an alert sound.

DialogItemIndex CautionAlert (
   SInt16 alertID,
   ModalFilterUPP modalFilter
);

Parameters
alertID

The resource ID of an alert resource and extended alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert. See ‘alrx’ for a description of the extended alert resource.

modalFilter

A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to null, the Dialog Manager uses the standard event filter function.

Return Value

If no alert box is to be drawn at the current alert stage, CautionAlert returns –1 otherwise, it uses NewDialog to create and display the alert box and returns the item hit; see “Alert Button Constants.” See the description of the DialogItemIndex data type.

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.

Special Considerations
Version Notes

This function was changed with Appearance Manager 1.0 to support the extended alert ('alrx') resource.

Availability
Declared In
Dialogs.h

CloseDialog

Dismisses a dialog box without disposing of the dialog structure.

void CloseDialog (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

Return Value
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

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.

Carbon Porting Notes

The CloseDialog function is not supported because developers do not allocate their own memory for dialog boxes in Carbon. Use the DisposeDialog function to dismiss a dialog box instead.

Declared In
Dialogs.h

CloseStandardSheet

OSStatus CloseStandardSheet (
   DialogRef inSheet,
   UInt32 inResultCommand
);

Parameters
inSheet
inResultCommand
Return Value

A result code. See “Dialog Manager Result Codes.”

Availability
Declared In
Dialogs.h

CountDITL

Determines the number of items in a dialog box.

DialogItemIndex CountDITL (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

Return Value

The number of current items in a dialog box. See the description of the DialogItemIndex data type.

Discussion

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

Special Considerations

Before calling CountDITL, you should make sure that it is available by using the Gestalt function with the gestaltDITLExtAttr selector. Test the bit indicated by the gestaltDITLExtPresent constant in the response parameter. If the bit is set, then CountDITL is available.

Availability
Declared In
Dialogs.h

CreateStandardAlert

Creates an alert containing standard elements and using standard formatting rules.

OSStatus CreateStandardAlert (
   AlertType alertType,
   CFStringRef error,
   CFStringRef explanation,
   const AlertStdCFStringAlertParamRec *param,
   DialogRef *outAlert
);

Parameters
alertType

The type of alert to create. For a list of possible values, see “Alert Type Constants.”

error

The error string to display.

explanation

The explanation string to display. May be NULL or empty to display no explanation.

param

The parameter block describing how to create the alert. May be NULL.

outAlert

A pointer to a variable that, on return, refers to the new alert.

Return Value

A result code. See “Dialog Manager Result Codes.”

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.

Availability
Declared In
Dialogs.h

CreateStandardSheet

Creates an alert containing standard elements and using standard formatting rules, and prepares it to be displayed as a sheet.

OSStatus CreateStandardSheet (
   AlertType alertType,
   CFStringRef error,
   CFStringRef explanation,
   const AlertStdCFStringAlertParamRec *param,
   EventTargetRef notifyTarget,
   DialogRef *outSheet
);

Parameters
alertType

The type of alert to create. For a list of possible values, see “Alert Type Constants.”

error

The error string to display.

explanation

The explanation string to display. May be NULL or empty to display no explanation.

param

The parameter block describing how to create the alert. May be NULL.

notifyTarget

The event target to be notified when the user dismisses the sheet. The caller should install an event handler on this target for the kEventProcessCommand event. May be NULL if the caller does not need the command event to be sent to any target. For more information, see the Discussion below.

outSheet

A pointer to a variable that, on return, refers to the new alert.

Return Value

A result code. See “Dialog Manager Result Codes.”

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.

Availability
Declared In
Dialogs.h

DialogCopy

Handles the Copy editing command when a dialog box containing an edit text item is active. 

void DialogCopy (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

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.

Availability
Declared In
Dialogs.h

DialogCut

Handles the Cut editing command when a dialog box containing an edit text item is active. 

void DialogCut (
   DialogRef theDialog
);

Parameters
theDialog

On input, a pointer to a dialog structure.

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.

Availability
Declared In
Dialogs.h

DialogDelete

Handles the Delete editing command when a dialog box containing an edit text item is active. 

void DialogDelete (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

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.

Availability
Declared In
Dialogs.h

DialogPaste

Handles the Paste editing command when a dialog box containing an edit text item is active.

void DialogPaste (
   DialogRef theDialog
);

Parameters
theDialog

On input, a pointer to a dialog structure.

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.

Availability
Declared In
Dialogs.h

DialogSelect

Handles most of the events inside the dialog box after you have determined that an event related to an active modeless dialog box or an active movable modal dialog box has occurred.

Boolean DialogSelect (
   const EventRecord *theEvent,
   DialogRef *theDialog,
   DialogItemIndex *itemHit
);

Parameters
theEvent

A pointer to an event structure returned by an Event Manager function such as WaitNextEvent.

theDialog

A pointer to a dialog structure for the dialog box where the event occurred.

itemHit

A pointer to a short integer. DialogSelect returns a number corresponding to the position of an item within the item list resource of the active dialog box.

Return Value

A Boolean value. If the event is an activate or update event for a dialog box, DialogSelect activates or updates it and returns false. If the event involves an enabled item, DialogSelect returns a function result of true.

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:

Special Considerations

Because DialogSelect handles only mouse-down events in a dialog box and key-down events in a dialog box’s edit text items, you should handle other events as appropriate before passing them to DialogSelect. Likewise, when DialogSelect calls the Control Manager function TrackControl , it does not allow you to specify any 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.

Within dialog boxes, use the functions DialogCut, DialogCopy, DialogPaste, and DialogDelete to support Cut, Copy, Paste, and Clear commands in edit text boxes.

Availability
Declared In
Dialogs.h

DisposeDialog

Dismisses a dialog box for which the Dialog Manager supplies memory and disposes of the dialog structure.

void DisposeDialog (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

Return Value
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.

Availability
Declared In
Dialogs.h

DisposeModalFilterUPP

void DisposeModalFilterUPP (
   ModalFilterUPP userUPP
);

Parameters
userUPP
Availability
Declared In
Dialogs.h

DisposeModalFilterYDUPP

void DisposeModalFilterYDUPP (
   ModalFilterYDUPP userUPP
);

Parameters
userUPP
Carbon Porting Notes

This function is supported in Carbon because several QuickTime routines require it.

Availability
Declared In
Dialogs.h

DisposeUserItemUPP

void DisposeUserItemUPP (
   UserItemUPP userUPP
);

Parameters
userUPP
Availability
Declared In
Dialogs.h

DrawDialog

Draws the entire contents of a specified dialog box.

void DrawDialog (
   DialogRef theDialog
);

Parameters
theDialog

A pointer to a dialog structure.

Return Value
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.

Availability
Declared In
Dialogs.h

FindDialogItem

Determines the item number of an item at a particular location in a dialog box. 

DialogItemIndexZeroBased FindDialogItem (
   DialogRef theDialog,
   Point thePt
);

Parameters
theDialog

A pointer to a dialog structure.

thePt

The point (in local coordinates) where the mouse-down event occurred.

Return Value

When an embedding hierarchy is established, the FindDialogItem function returns the deepest control selected by the user corresponding to the point specified in the thePt parameter. When an embedding hierarchy does not exist, FindDialogItem performs a linear search of the item list resource and returns a number corresponding to the hit item’s position in the item list resource. For example, it returns 0 for the first item in the item list, 1 for the second, and 2 for the third. If the mouse is not over a dialog item, FindDialogItem returns –1. See the description of the DialogItemIndexZeroBased data type.

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.

Version Notes

This function was changed with Appearance Manager 1.0 to support embedding hierarchies.

Availability
Declared In
Dialogs.h

GetAlertStage

Determines the stage of the last occurrence of an alert. 

SInt16 GetAlertStage (
   void
);

Parameters
Return Value

A number from 0 to 3 as the stage of the last occurrence of an alert.

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.

Carbon Porting Notes
Availability
Declared In
Dialogs.h

GetDialogCancelItem

Returns the item number of the cancel item previously set with SetDialogCancelItem.

SInt16 GetDialogCancelItem (
   DialogRef dialog
);

Parameters
dialog

On input, a pointer to the dialog structure for the dialog box whose cancel item you want to get.

Return Value

The item number of the cancel item previously set with the SetDialogCancelItem function.

Discussion

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

Availability
Declared In
Dialogs.h

GetDialogDefaultItem

Returns the item number of the default item currently set for the standard filter function.

SInt16 GetDialogDefaultItem (
   DialogRef dialog
);

Parameters
dialog

On input, a pointer to the dialog structure for the dialog box whose default item you want to get.

Return Value

The item number of the default item currently set for the standard filter function.

Discussion

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

Availability
Declared In
Dialogs.h

GetDialogFromWindow

DialogRef GetDialogFromWindow (
   WindowRef window
);

Parameters
window
Return Value

See the description of the DialogRef data type.

Availability
Declared In
Dialogs.h

GetDialogItem

Obtains a handle to a dialog item. 

void GetDialogItem (
   DialogRef theDialog,
   DialogItemIndex itemNo,
   DialogItemType *itemType,
   Handle *item,
   Rect *box
);

Parameters
theDialog

A pointer to the dialog box to examine.

itemNo

The position of the item in the dialog box’s item list resource use FindDialogItem to determine this value.

itemType

A pointer to a short value. On return, the value identifies the item type of the dialog item requested in the itemNo parameter.

item

A pointer to an item handle. On return the handle refers to the item specified in the itemNo parameter or, for application-defined draw functions, a pointer (coerced to a handle) to the draw function.

box

A pointer to a rectangle. On return, the rectangle specifies the display rectangle (described in coordinates local to the dialog box), for the item specified in the itemNo parameter.

Return Value
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.

Version Notes

This function was changed with Appearance Manager 1.0 to support retrieving item information from controls.

Availability
Declared In
Dialogs.h

GetDialogItemAsControl

Obtains the control handle for a dialog item in an embedding hierarchy. 

OSErr GetDialogItemAsControl (
   DialogRef inDialog,
   DialogItemIndex inItemNo,
   ControlRef *outControl
);

Parameters
inDialog

A pointer to the dialog box to examine.

inItemNo

The position of an item in the dialog box’s item list.

outControl

A pointer to a control handle that, on return, refers to the embedded control.

Return Value

A result code. See “Dialog Manager Result Codes.” The Control Manager result code errItemNotControl indicates that the specified dialog item is not a control.

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.

Version Notes

This function is available with Appearance Manager 1.0 and later.

Availability
Declared In
Dialogs.h

GetDialogItemText

Obtains the text string contained in an edit text or a static text item. 

void GetDialogItemText (
   Handle item,
   Str255 text
);

Parameters
item

On input, a handle to an edit text or a static text item. To get this handle, call the “Alert Button Constants” function.

text

On output, a string containing the text of the item that is specified by the item parameter.

Discussion

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

Availability
Declared In
Dialogs.h

GetDialogKeyboardFocusItem

Returns the item number of the editable text item in a dialog box that has keyboard focus.

SInt16 GetDialogKeyboardFocusItem (
   DialogRef dialog
);

Parameters
dialog

On input, a pointer to the dialog structure for the dialog box whose currently focused item you want to identify.

Return Value

The number of the editable text item in a dialog box that currently has keyboard focus.

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.

Version Notes

This function is not recommended with Appearance Manager 1.0 and later.

Availability
Declared In
Dialogs.h

GetDialogPort

CGrafPtr GetDialogPort (
   DialogRef dialog
);

Parameters
dialog
Return Value

See the QuickDraw Manager documentation for a description of the CGrafPtr data type.

Discussion
Special Considerations
Version Notes
Carbon Porting Notes
Availability
Declared In
Dialogs.h

GetDialogTextEditHandle

TEHandle GetDialogTextEditHandle (
   DialogRef dialog
);

Parameters
dialog
Return Value

See the TextEdit documentation for a description of the TEHandle data type.

Availability
Declared In
Dialogs.h

GetDialogTimeout

Obtains the original countdown duration, the time remaining, and the item selection to be simulated for a specified modal dialog box.

OSStatus GetDialogTimeout (
   DialogRef inDialog,
   DialogItemIndex *outButtonToPress,
   UInt32 *outSecondsToWait,
   UInt32 *outSecondsRemaining
);

Parameters
inDialog

A pointer to the dialog box to be examined.

outButtonToPress

On input, a pointer to a signed 16-bit integer. On return, a value representing the number within the item list of the item that is to be selected. You may pass NULL for the outButtonToPress parameter if you do not desire this information.

outSecondsToWait

On input, a pointer to an unsigned 32-bit integer. On return, a value specifying the number of seconds that were originally set to elapse before the Dialog Manager simulates an item selection. You may pass NULL for the outSecondsToWait parameter if you do not desire this information.

outSecondsRemaining

On input, a pointer to an unsigned 32-bit integer. On return, a value specifying the number of seconds remaining before the Dialog Manager simulates an item selection. You may pass NULL for the outSecondsRemaining parameter if you do not desire this information.

Return Value

A result code. See “Dialog Manager Result Codes.”

Discussion

Also see the function SetDialogTimeout.

Availability
Declared In
Dialogs.h

GetDialogWindow

WindowRef GetDialogWindow (
   DialogRef dialog
);

Parameters
dialog
Return Value

See the QuickDraw Manager documentation for a description of the WindowRef data type.

Availability
Declared In
Dialogs.h

GetModalDialogEventMask

Obtains the events to be received by the ModalDialog function.

OSStatus GetModalDialogEventMask (
   DialogRef inDialog,
   EventMask *outMask
);

Parameters
inDialog

A pointer to the dialog box for which you wish to obtain the event mask.

outMask

On input, a pointer to a unsigned 16-bit integer of type EventMask. On return, your application may test the bits of this value to determine the event(s) that the dialog box is currently set to receive.

Return Value

A result code. See “Dialog Manager Result Codes.”

Discussion

Also see the function SetModalDialogEventMask.

Version Notes

This function is available with Mac OS 8.5 and later.

Availability
Declared In
Dialogs.h

GetNewDialog

Creates a dialog box from a resource-based description. 

DialogRef GetNewDialog (
   SInt16 dialogID,
   void *dStorage,
   WindowRef behind
);

Parameters
dialogID

The resource ID of a dialog resource and an extended dialog resource. The resource IDs for both resources must be identical. If the dialog resource is missing, the Dialog Manager returns to your application without creating the requested dialog box. See ‘DLOG’ and ‘dlgx’ for a description of the dialog resource and the extended dialog resource, respectively.

dStorage

A pointer to the memory for the dialog structure. If you set this parameter to null, the Dialog Manager automatically allocates a nonrelocatable block in your application heap.

behind

A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1L to bring the dialog box in front of all other windows.

Return Value

Returns a pointer to a dialog box. If none was created, returns null. See the description of the DialogRef data type.

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.

Special Considerations

The GetNewDialog function doesn’t release the memory occupied by the resources. Therefore, your application should mark all resources used for a dialog box as purgeable or you should release the resources yourself.

If either the dialog resource or the item list resource can’t be read, the function result is null; your application should test to ensure that null is not returned before performing any more operations with the dialog box or its items.

As with all other windows, dialogs are created with an update region equal to their port rectangle. However, if the dialog’s 'DLOG' resource specifies that the dialog be made visible upon creation, the Dialog Manager draws the controls immediately and calls ValidRgn for each of their bounding rectangles. Other items are not drawn until the first update event for the dialog box is serviced.

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser

Version Notes

This function was changed with Appearance Manager 1.0 to support the extended dialog ('dlgx') resource and the dialog font table ('dftb') resource.

Availability
Declared In
Dialogs.h

GetParamText

void GetParamText (
   StringPtr param0,
   StringPtr param1,
   StringPtr param2,
   StringPtr param3
);

Parameters
param0
param1
param2
param3
Availability
Declared In
Dialogs.h

GetStandardAlertDefaultParams

Fills out an AlertStdCFStringAlertParamRec with default values: - not movable - no help button - default button with title "OK" - no cancel or other buttons.

OSStatus GetStandardAlertDefaultParams (
   AlertStdCFStringAlertParamPtr param,
   UInt32 version
);

Parameters
param

The parameter block to initialize.

version

The parameter block version; pass kStdCFStringAlertVersionOne.