TweetFollow Us on Twitter

MACINTOSH C CARBON
MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
© 2001 K. J. Bricknell
Go to Contents Go to Program Listing

CHAPTER 8

DIALOGS AND ALERTS

Introduction

Your application should present alerts to the user whenever an unexpected or undesirable situation occurs.

Before your application carries out a command, it may present a dialog to solicit additional information from the user or to allow the user to modify settings.

Alert Types, Modalities, and Levels

Alert Types and Modalities

There are three types of alert, namely, the modal alert, the movable modal alert, and, in Mac OS X only, the sheet alert. The three types are shown at Fig 1

Modal Alert

The fixed-position modal alert places the user in the state, or mode, of being able to work only inside the alert box. The only response the user receives when clicking anywhere outside the alert box is the alert sound. The modal alert is thus system-modal, meaning that is denies user interaction with anything but the alert until it is dismissed.

There will be very few, if any, situations where the use of a modal alert in your application is justified.

Movable Modal Alert

Movable modal alerts retain the essentially modal characteristic of their fixed-position counterpart, the main differences being that they allow the user to drag the alert so as to uncover obscured areas of an underlying window and bring another application to the front. Movable modal alerts are thus application-modal.

Window Modal (Sheet) Alert - Mac OS X

Mac OS X introduced a new type of alert called the sheet alert. Sheet alerts, which are invariably attached to an owner window, are window-modal. The information conveyed by the alert, or the alternative actions requested, should pertain only to the document to whose window the alert is attached.

Levels of Alert

An alert can display one of three levels of alert (see Fig 1), depending on the nature of the situation the alert is reporting to the user. The three levels of alert, which are identified by icons supplied automatically by the system, are as follows:

  • Note Level. TThe note level (see Fig 1) is used to inform users of an occurrence that will not have serious consequences. Usually, a note level alert simply offers information, although it may ask a simple question and provide, via the push buttons, a choice of responses.

  • Caution Level. The caution level is used to alert the user to an operation that may have undesirable results if it is allowed to continue. As shown at Fig 1, you should provide the user, via the push buttons, with a choice of whether to continue with, or back out of, the operation.

  • Stop Level. The stop alert is used to inform the user of a situation so serious that the operation cannot proceed.

Note that, at the time of writing, there was no visual distinction between alert levels on Mac OS X, the application icon rather than distinct note, caution, and stop icons being displayed. At the time of writing, it was expected that Carbon would eventually support the "badging" of the application icon with alert level badges similar to the Mac OS 8/9 note, caution, and stop icons.

Dialog Types and Modalities

There are four types of dialog, namely, modal dialogs, movable modal dialogs, modeless dialogs, and, on Mac OS X only, sheet dialogs. The four types are illustrated in the examples at Fig 2.

Modal Dialog

Fixed-position modal dialogs place the user in the state, or mode, of being able to work only inside the dialog. The only response the user receives when clicking outside the dialog is the alert sound. The modal alert is thus system-modal, meaning that is denies user interaction with anything but the dialog until it is dismissed.

There will be very few, if any, situations where the use of a modal dialog in your application is justified.

Movable Modal Dialog

Movable modal dialogs retain the essentially modal characteristic of their fixed-position counterpart, the main differences being that they allow the user to drag the dialog so as to uncover obscured areas of an underlying window and bring another application to the front. Movable modal dialogs are thus application-modal.

The absence of boxes/buttons in the title bar of a movable modal dialog visually indicates to the user that the dialog is modal rather than modeless.

Modeless Dialog

Modeless dialogs look very like document windows, except for their interior colour/pattern and, on Mac OS 8/9, a one-pixel frame just inside the window frame. Unlike document windows, however, modeless dialogs should not contain scroll bars or a size box/resize control.

Modeless dialogs should not require the user to dismiss them before the user is able to do anything else. Thus modeless dialogs should be made to behave much like document windows in that the user should be able to move them, bring other windows in front of them, and close them.

Modeless dialogs should ordinarily not have a Cancel push button, although they may have a Stop push button to halt long operations such as searching.

Window-Modal (Sheet) Dialog - Mac OS X

Mac OS X introduced a new type of dialog called the sheet dialog. Sheet dialogs, which are invariably attached to an owner window, are window-modal. The information or settings solicited by the dialog should pertain only to the document to whose window the dialog is attached.

Window Types For Alerts and Dialogs

Fig 3 shows the seven (eight on Mac OS X) available theme-compliant window types for alerts and dialogs and the constants that represent the window definition IDs for those types. Note that modeless dialogs are a special case in that a normal document window type is used.

The window definition ID is derived by multiplying the resource ID of the WDEF by 16 and adding the variation code to the result, as is shown in the following:

WDEF
Resource ID

Variation
Code

Window Definition ID
(Value)

Window Definition ID
(Constant)

65 0 65 * 16 + 0 = 1040 kWindowPlainDialogProc
65 1 65 * 16 + 1 = 1041 kWindowShadowDialogProc
65 2 65 * 16 + 2 = 1042 kWindowModalDialogProc
65 3 65 * 16 + 3 = 1043 kWindowMovableModalDialogProc
65 4 65 * 16 + 4 = 1044 kWindowAlertProc
65 5 65 * 16 + 5 = 1045 kWindowMovableAlertProc

64 0 64 * 16 + 0 = 1024 kWindowDocumentProc

68 0 68 * 16 + 0 = 1088 kWindowSheetProc

Content of Alerts and Dialogs

Alerts should usually contain only informative text and push button controls. Dialogs may contain informative or instructional text and controls.

Default Push Buttons

The default push button, visually identified by a default ring drawn around it (Mac OS 8/9) or pulsing blue (Mac OS X), should be the one the user is more likely to click in most circumstances. If the most likely choice is at all destructive (for example, erasing a disk or deleting a file), you should consider defining the Cancel button as the default. (See the caution alert at Fig 1.)

Removing Dialogs

Your application should remove and dispose of a modal dialog or movable modal dialog only when the user clicks one of its push buttons.

Your application should not remove a modeless dialog unless the user clicks its close box/button or chooses Close from the File menu when the modeless dialog is the active window. . (Typically, a modeless dialog is simply hidden, not disposed of, when the user clicks the close box/button or chooses Close from the File menu.)

Creating and Removing Alerts

Alerts may be created from resources using the functions Alert, NoteAlert, CautionAlert and StopAlert, which take descriptive information about the alert from alert ('ALRT') and extended alert ('alrx') resources. However, the preferred (and considerably simpler) method is to create alerts programmatically using the functions StandardAlert and, on Mac OS X only, CreateStandardAlert.

Fig 4 shows an alert created by functions StandardAlert or CreateStandardAlert.

The StandardAlert Function

When an alert is created using the function StandardAlert, the alert is automatically sized based on the amount of text passed in to it, and push buttons are automatically sized and located.

     OSErr  StandardAlert(AlertType inAlertType,ConstStr255Param  inError,
                          ConstStr255Param  inExplanation,
                          const AlertStdAlertParamRec *inAlertParam,
                          SInt16 *outItemHit);

inAlertType

The level of alert. Relevant constants are kAlertStopAlert, kAlertNoteAlert, kAlertCautionAlert, and kAlertPlainAlert.

inError

The label text (Mac OS 8/9) or message text (Mac OS X).

inExplanation

The narrative text (Mac OS 8/9) or informative text (Mac OS X). NULL indicates no narrative/informative text.

inAlertParam

A pointer to a standard alert parameter structure (see below). NULL indicates that none of the features provided by the standard alert structure are required.

outItemHit

On output, contains the item number of the push button that the user hit.

Standard Alert Parameter Structure

The standard alert parameter structure is as follows:

     struct AlertStdAlertParamRec 
     {
       Boolean         movable;
       Boolean         helpButton;
       ModalFilterUPP  filterProc;
       ConstStringPtr  defaultText;
       ConstStringPtr  cancelText;
       ConstStringPtr  otherText;
       SInt16          defaultButton;
       SInt16          cancelButton;
       UInt16          position;
     };
     typedef struct AlertStdAlertParamRec AlertStdAlertParamRec;
     typedef AlertStdAlertParamRec *AlertStdAlertParamPtr;

Field Descriptions

movable

Specifies whether the alert is modal or movable modal.

helpButton

Specifies whether the alert should include the Help button.

filterProc

Optionally, a universal procedure pointer to an application-defined event filter (callback) function. If NULL is assigned, the Dialog Manager uses the standard event filter (callback) function. (See Event Filter Functions For Modal and Movable Modal Alerts and Dialogs, below)

defaultText

Optionally, text for the push button in the OK push button position. (See Alert Default Text Constants, below). The push button is automatically sized and positioned to accommodate the text. Pass NULL to specify that no push button should be displayed.

The push button in the OK button position is not necessarily named OK. Human Interface Guidelines require that, wherever possible, buttons be named with a verb that describes the action that they perform. (As an example, see the buttons at Fig 1.)

cancelText

Optionally, text for the push button in the Cancel push button position. (See Alert Default Text Constants, below.) The push button is automatically sized and positioned to accommodate the text. Pass NULL to specify that no push button should be displayed.

otherText

Optionally, text for the push button in leftmost position. (See Alert Default Text Constants, below.) The push button is automatically sized and positioned to accommodate the text. Pass NULL to specify that no push button should be displayed.

defaultButton

Specifies which push button is to act as the default push button. (See Alert Button Constants, below.)

cancelButton

Specifies which push button is to act as the Cancel push button. Can be 0. (See Alert Button Constants, below.)

position

The alert position. (See Positioning Specification, below, and note that, when these constants are used to specify alert position in an alert created programmatically using StandardAlert, the constant kWindowDefaultPosition has the same effect as kWindowAlertPositionParentWindowScreen.)

Alert Default Text Constants

To specify the default text for the push buttons in the Right, Middle, and Leftmost push button positions, use these constants in the defaultText, cancelText, and otherText fields of the standard alert structure.

Constant

Value

Button Position

Default Text

Where Used

kAlertDefaultOKText -1 Right OK

defaultText field

kAlertDefaultCancelText -1 Middle Cancel

cancelText field

kAlertDefaultOtherText -1 Leftmost Don't Save

otherText field

Alert Push Button Constants

To specify which push buttons act as the default and Cancel push buttons, use these constants in the defaultButton and cancelButton fields in the standard alert structure. These constants are also returned in the itemHit parameter of StandardAlert.

Constant

Value

Meaning

kAlertStdAlertOKButton 1

The OK push button.

kAlertStdAlertCancelButton 2

The Cancel push button.

kAlertStdAlertOtherButton 3

A third push button.

kAlertStdAlertHelpButton 4

The Help push button.

Positioning Specification

The main constants for the positioning specification field are as follows:

Constant

Value

Meaning

kWindowDefaultPosition 0x0000

Alert position on screen where user is currently working.

kWindowAlertPositionMainScreen 0x300A

Alert position on main screen. (The main screen in a multi-monitor system is the screen on which the menu bar is located.)

kWindowAlertPositionParentWindow 0xB00A

Alert position on frontmost window.

kWindowAlertPositionParentWindowScreen 0x700A

Alert position on screen where user is currently working.

kWindowCenterMainScreen 0xA80A

Centre on main screen.

kWindowCenterParentWindow 0xA80A

Centre on frontmost window.

kWindowCenterParentWindowScreen 0x680A

Centre on screen where user is currently working.

The CreateStandardAlert Function

On Mac OS X only, you may also use the function CreateStandardAlert to create an alert:

     
OSStatus  CreateStandardAlert(AlertType inAlertType, CFStringRef inError,
                              CFStringRef inExplanation,
                              const AlertStdCFStringAlertParamRec *param,
                              DialogRef *outAlert);

The main differences between the CreateStandardAlert and StandardAlert functions are as follows:

  • The inError and inExplanation fields take a CFStringRef.

  • A pointer to a standard CFString alert parameter structure is passed in the param parameter. This structure is basically similar to the standard alert parameter structure except that:

    • It has no field for a universal procedure pointer to an event filter (callback) function.

    • The defaultText, cancelText, and otherText fields are of type CFStringRef.

    • It has an additional field (flags) in which bits can be set to specify options for the behaviour of the dialog. Setting the kStdAlertDoNotDisposeSheet bit in this field when the dialog is a sheet causes the sheet not to be disposed of after it is hidden.

    A call to the function GetStandardAlertDefaultParams initialises a standard CFString alert parameter structure with default values. (The defaults are: not movable; no Help button; no Cancel button; no Other button; alert position on parent window screen.)

  • On return, a pointer to a dialog reference is received in the outAlert parameter. This must be passed in a call to the function RunStandardAlert, which displays the alert and handles user interaction. A universal procedure pointer to an event filter (callback) function may be passed in the filterProc parameter of this function. On output, the item number of the push button that the user hit is received in the outItemHit parameter of RunStandardAlert.

Removal of Alerts

The Dialog Manager automatically removes and disposes of an alert when the user clicks a push button.

Creating Dialogs

Dialogs may be created in one of two ways, as follows:

  • You can create dialogs from resources using the function GetNewDialog, which takes descriptive information about the dialog from dialog ('DLOG') and extended dialog ('dlgx') resources. The resource ID of the 'DLOG' and 'dlgx' resources must be the same, and is passed in the first parameter of this function.

  • You can create dialogs programmatically using the function NewFeaturesDialog. NewFeaturesDialog has a flags parameter containing the same flags you would set in an extended dialog resource when creating the dialog from resources.

The Dialog Object

Dialog objects are opaque data structures in which the Dialog Manager stores information about individual dialogs. The data type DialogRef is defined as a pointer to a dialog object:

     typedef struct OpaqueDialogPtr *DialogPtr;
     typedef DialogPtr DialogRef;

Accessor Functions

The following accessor functions are provided to access the information in dialog objects.

Function

Description

GetDialogWindow

Gets a reference to the dialog's window object.

GetDialogTextEditHandle

Gets a handle to the TERec structure (which is re-used for all edit text items).

GetDialogKeyboardFocusItem

Gets item number of the item with keyboard focus.

GetDialogDefaultItem
SetDialogDefaultItem

Gets the item number of the default push button.
Tells the Dialog Manager the item number of the default push button.

GetDialogCancelItem
SetDialogCancelItem

Gets the item number of the default Cancel push button.
Tells the Dialog Manager the item number of the default Cancel button.

AppendDITL
AppendDialogItemList
ShortenDITL
InsertDialogItem
RemoveDialogItem

Add items to, and remove items from, a dialog.

'DLOG' and 'dlgx' Resources

Structure of a Compiled 'DLOG' Resource

Fig 5 shows the structure of a compiled 'DLOG' resource and how it "feeds" the dialog object.

The following describes the main fields of the 'DLOG' resource:

Field

Description

RECTANGLE

The dialog's dimensions and, if a positioning specification (see below) is not specified, its location.

WINDOW DEFINITION ID

The window definition ID. (See Window Types For Alerts and Dialogs, above.)

VISIBILITY

If set to 1, the Dialog Manager displays the dialog as soon as GetNewDialog is called. If set to 0, the dialog is not displayed until ShowWindow is called..

CLOSE BOX SPECIFICATION

Specifies whether to draw a close box/button. Ordinarily, a close box/button is specified only for modeless dialogs.

REFERENCE CONSTANT

Applications can store any value here. For example, an application might store a number that represents the dialog type. SetWRefCon and GetWRefCon tmay be used to set and get this value.

ITEM LIST ID

Resource ID of the item list resource.

WINDOW TITLE

The title displayed in the dialog's title bar (modeless and movable modal dialogs only).

POSITIONING SPECIFICATION

Specifies the position of the dialog on the screen. If a positioning constant is not provided, the Dialog Manager places the dialog at the global coordinates specified for the dialog's rectangle (see above). The same positioning constants as apply in the case of an alert box apply. (See Positioning Specification, above, but note that, in the case of 'DLOG' resources, kWindowDefaultPosition means that the window will be positioned according to the RECTANGLE field.)

Structure of a Compiled 'dlgx' Resource

Fig 6 shows the structure of a compiled 'dlgx' resource. This resource allows you to provide additional features for your dialog, including movable modal behaviour, background colour/pattern, and embedding hierarchies.

The following describes the main field of the 'dlgx' resource:

Field

Description

DIALOG FLAGS

Constants that specify the dialog's Appearance features. (See Dialog Feature Flag Constants, below.)

Dialog Feature Flag Constants

You can set the following bits in the dialog flags field of a 'dlgx' resource to specify the dialog's theme-compliant features:

Constant

Bit

Meaning

kDialogFlagsUseThemeBackground 0

The Dialog Manager sets the correct dialog background colour/pattern.

kDialogFlagsUseControlHierarchy 1

A root control is created and an embedding hierarchy is established.
Note: All items in a dialog automatically become controls when embedding hierarchy is established.

kDialogFlagsHandleMovableModal 2

The dialog will be movable modal (in which case you must use kWindowMovableModalDialogProc window definition ID). (The Dialog Manager handles movable modal behaviour.)

kDialogFlagsUseThemeControls 3

All controls created by the Dialog Manager will be compliant with the Platinum appearance.

Creating 'dlgx ' and 'DLOG' Resources Using Resorcerer

Creating 'dlgx' Resources

Fig 7 shows a 'dlgx' resource being created with Resorcerer.

Creating 'DLOG' Resources

Fig 8 shows a 'DLOG' resource being created with Resorcerer.

The NewFeaturesDialog Function

The function NewFeaturesDialog creates a dialog from the information passed in its parameters.

     DialogRef  NewFeaturesDialog(void *      inStorage,
                                  const Rect *     inBoundsRect,
                                  ConstStr255Param inTitle,
                                  Boolean          inIsVisible,
                                  SInt16           inProcID,
                                  WindowRef        inBehind,
                                  Boolean          inGoAwayFlag,
                                  SInt32           inRefCon,
                                  Handle           inItemListHandle,
                                  UInt32           inFlags);

     Returns: A pointer to the new dialog, or NULL if the dialog 
               is not created

inStorage

A pointer to the memory for the dialog object. In Carbon, this should always be set to NULL, which causes the Dialog Manager to automatically allocate memory for the dialog object.

inBoundsRect

A rectangle which specifies the size and position of the dialog in global coordinates.

inTitle

The title of a modeless or movable modal dialog. You can specify an empty string (not NULL) if the dialog is to have no title. (In C, you specify an empty string by two double quotation marks ("").)

inIsVisible

Specifies whether the dialog should be drawn immediately after NewFeatureDialog is called. If this parameter is set to false, ShowWindow must be called to display the dialog.

inProcID

The window definition ID for the type of dialog. Pass kWindowModalDialogProc in this parameter to specify modal dialogs, kWindowMovableModalDialogProc to specify movable modal dialogs, and kWindowDocumentProc to specify modeless dialogs.

inBehind

A reference to the window behind which the dialog is to be opened. Pass (WindowRef)-1 in this parameter to open the dialog in front of all other windows.

inGoAwayFlag

Passing true in this parameter causes a close box to be drawn in the title bar. true should only be passed when a modeless dialog is being created.

inRefCon

A reference constant that the Dialog Manager stores in the dialogÕs window object. Applications can store any value here. For example, an application might store a number that represents the dialog type. GetWRefCon may be used to retrieve this value.

inItemListHandle

A handle to the item list resource, which you can get by calling GetResource to read the item list resource into memory.

inFlags

The dialogÕs feature flags. (See Dialog Feature Flag Constants, above.)

Although the inItemListHandle parameter specifies an item list ('DITL') resource for the dialog, the corresponding dialog font table ('dftb') resource (see below) is not automatically accessed. You must explicitly set the dialog's control font styles individually.

Items in Dialogs

Preamble - Dialog Manager Primitives

Dialogs contain items, such as push buttons, radio buttons, and checkboxes. Prior to the introduction of Mac OS 8 and the Appearance Manager, an actual control could be an item; however, items such as push buttons and radio buttons were not controls as such but rather Dialog Manager primitives.

These primitives may still be specified in item list resources (see below). However, when a root control has been created for the dialog window, thus creating an embedding hierarchy for controls, the Dialog Manager replaces any primitives in the dialog with their control counterparts (except for the primitive called a user item).

The situation where all items in a dialog are controls has many advantages. For example, all controls within the dialog can be activated and deactivated by simply activating and deactivating the root control.

The primitives, and their control equivalents, are as follows:

Dialog Manager Primitive

Control Equivalent

Button.

Push button.

Radio Button.

Radio button.

Checkbox.

Checkbox.

Edit Text.

Edit text control.

Static Text.

Static text control.

Icon. (An icon whose black and white resource was stored in an 'ICON' resource and whose colour version is stored in a 'cicn' resource with the same ID.)

Icon control (no track variant).

Picture. (Picture stored in a 'PICT' resource.)

Picture control (no track variant).

User Item. (An application-defined item. For example, an application-defined drawing function could be installed in a user item.)

(No control equivalent.)

The 'DITL' Resource

A ('DITL') resource is used to store information about all the items in a dialog. The 'DITL' resource ID is specified in the associated 'DLOG' resource, or a handle to the 'DITL' resource is passed in the inItemListHandle parameter of the NewFeaturesDialog function. 'DITL' resources should be marked as purgeable.

Items are usually referred to by their position in the item list, that is, by their item number.

Several independent dialogs may use the same 'DITL' resource. AppendDITL, AppendDialogItemList, and ShortenDITL may be used to modify or customise copies of shared item list resources for use in individual dialogs.

Fig 9 shows the structure of a compiled 'DITL' resource and one of its constituent items, in this case a control item.

The following describes the fields of the 'DITL' resource and the control item:

Field

Description

ITEM COUNT MINUS 1

A value equal to one less than the number of items.

FIRST ITEM ... LAST ITEM

(The format of each item depends on its type.)

DISPLAY RECTANGLE

The size and location, in local coordinates, of the item within the dialog. (See Display Rectangles, below.)

ENABLE FLAG

Specifies whether the item is enabled or disabled. If this bit is set (item is enabled) the Dialog Manager reports all mouse-down events in the item to your application.

ITEM TYPE

The item type.

RESOURCE ID

For a control item, the resource ID of the 'CNTL' resource.

Display Rectangles

The enclosing rectangle you specify in a control's 'CNTL' resource should be identical to the display rectangle specified in the 'DITL' resource.

Resorcerer has a Preferences setting which forces conformity between the display rectangle specified in the 'DITL' resource and the display rectangle specified in the 'CNTL' resource.

Note that, for items that are controls, the rectangle added to the update region is the rectangle defined in the 'CNTL' resource, not the display rectangle specified in the 'DITL' resource. Other important aspects of display rectangles are as follows:

  • Edit Text Items. In edit text items, the display rectangle is the TextEdit destination rectangle and view rectangle (see Chapter 21 - Text and TextEdit). For display rectangles that are large enough to contain more than one line of text, word wrapping occurs within the rectangle. The text is clipped if it overflows the rectangle.

  • Static Text Item. Static text items are drawn within the display rectangle in the same manner as edit text items except that a frame is not drawn around the text.

  • Icon and Picture Items. Icons and pictures larger than the display rectangle are scaled so as to fit the display rectangle.

  • The Dialog Manager considers a click anywhere in the display rectangle to be a click in that item. In the case of a click in the overlap area of overlapping display rectangles, the Dialog Manager reports the click as occurring in the item that appears first in the item list.

Creating a 'DITL' Resource Using Resorcerer

Fig 10 shows a 'DITL' resource being created with Resorcerer. Two items are being edited (Item 1 and Item 2). Item 1 is a Dialog Manager primitive. Item 2 is a control.

Layout Guidelines For dialogs

Layout guidelines for items in dialogs are contained in the Apple publications Mac OS 8 Human Interface Guidelines (Mac OS 8/9) and Aqua Human Interface Guidelines (Mac OS X). These guidelines are not consistent on matters such as the required sizes of certain items and, more particularly, the required spacing between items. For Carbon applications, it is best to observe the Aqua interface guidelines when laying out dialog items.

Default Push Buttons

You should give every dialog a default push button, except for those that contain edit text items that accept Return key presses. If you do not provide an event filter (callback) function (see Event Filter Functions For Modal and Movable Modal Alerts and Dialogs, below) which specifies otherwise, the Dialog Manager treats the first item in the item list resource as the default push button for the purpose of responding to Return and Enter key presses.

Enabling and Disabling Items

You should not necessarily enable all items. For example, you typically disable static text items and edit text items because your application does not need to respond to clicks in those items.

Note that disabled is not the same thing as a deactivated. The Dialog Manager makes no visual distinction between a disabled and enabled item; it simply does not inform your application when the user clicks a disabled item. On the other hand, when a control is deactivated, the Control Manager dims it to show that it is deactivated.

Keyboard Focus

Edit text and clock items accept input from the keyboard, and list box items respond to certain key presses. The Dialog Manager automatically responds to mouse-down events and Tab key-down events intended to shift the keyboard focus between such items, indicating the current target by drawing a keyboard focus frame around that item. For edit text items, the Dialog Manager also automatically displays the insertion point caret in the current target. For clock items, the Dialog Manager, in addition to drawing the keyboard focus frame, also moves the keyboard target within the clock by highlighting the individual parts.

The Tab key moves the keyboard focus between such items in a sequence determined by their order in the item list. Accordingly, you should ensure that the item numbers of these items in the 'DITL' resource reflect the sequence in which you require them to be selected by successive Tab key presses.

Manipulating Items

Functions for Manipulating Items

Dialog Manager functions for manipulating items are as follows:

Function

Description

GetDialogItemAsControl

Returns the control reference for an item in an embedding hierarchy. Should be used instead of GetDialogItem (see below) when an embedding hierarchy is established.

GetDialogItem

Returns the the control reference, item type, and display rectangle of a given item. When an embedding hierarchy is present, you should generally use GetDialogItemAsControl instead of GetDialogItem to get a reference to the control.

When called on a static text item, GetDialogItem returns a handle to the text, not a reference to the control, and thus may be used to get a handle to the text of static text fields. (When called on a static text field item, GetDialogItemAsControl returns a reference to the control, not a handle to the text.)

SetDialogItem

When an embedding hierarchy does not exist, sets the item type, reference, and display rectangle of an item. (When an embedding hierarchy exists, you cannot change the type or reference of an item.)

HideDialogItem

Hides the given item.

ShowDialogItem

Re-displays a hidden item.

GetDialogItemText

Returns the text of an edit or static text field item.

SelectDialogItemText

Selects the text of an edit text field item. When embedding is on, you should pass in the control reference produced by a call to GetDialogItemAsControl. When embedding is not on, you should pass in the reference produced by a call to GetDialogItem.

FindDialogItem

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

MoveDialogItem

Moves a dialog item to a specified location in a window. 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.

SizeDialogItem

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.

CountDITL
AppendDialogItemList

Counts items in a dialog.

AppendDITL

Adds items to a dialog. (See Append Method Constants, below.)

ShortenDITL

Removes items from a dialog.

ParamText

Substitutes up to four different text strings in static text field items.

Append Method Constants

The AppendDITL, AppendDialogItemList, and ShortenDITL functions are particularly useful in the situation where more than one dialogs share the same 'DITL' resource and you want to tailor the 'DITL' for each dialog. When calling AppendDITL or AppendDialogItemList, you specify a new 'DITL' resource to append to the dialog's existing 'DITL' resource. You also specify where the Dialog Manager should display the new items by using one of the following constants in the AppendDITL or AppendDialogItemList call:

Constant

Value

Description

overlay 0

Overlay existing items. Coordinates of the display rectangle are interpreted as local coordinates within the dialog.

AppendDITLRight 1

Append at right. Display rectangles are interpreted as relative to the upper-right coordinate of the dialog.

appendDITLBottom 2

Append at bottom. Display rectangles are interpreted as relative to the lower-left coordinate of the dialog.

As an alternative to passing these constants, you can append items relative to an existing item by passing a negative number to AppendDITL or AppendDialogItemList. The absolute value of this number represents the item relative to which the new items are to be positioned. For example, -3 would cause the display rectangles of the appended items to be offset from the upper-left corner of item number 3 in the dialog.

To use, at a later time, the unmodified version of a dialog whose contents and (possibly) size have been modified by AppendDITL or AppendDialogItemList, you should call ReleaseResource to release the memory occupied by the appended item list.

Getting and Setting The Text in Edit Text and Static Text Items

Dialog Manager functions for getting text from, and setting the text of, edit text and static text items are as follows:

Function

Description

GetDialogItemText

Gets a copy of the text in static text and edit text items. Pass in the reference produced by a call to GetDialogItem, which gets a handle the text in this instance, not a reference to the control.

SetDialogItemText

Sets the text string for static text and edit text items. When embedding is on, you should pass in the control reference produced by a call to GetDialogItemAsControl. If embedding is not on, pass in the reference produced by GetDialogItem.

The function ParamText may also be used to set the text string in a static text item in a dialog. A common example is the inclusion of the window title in static text such as "Save changes to the document ... before closing?". In this case, the window's title could be retrieved using GetWTitle and inserted by ParamText at the appropriate text replacement variable (^0, ^1, ^2 or ^3) specified in the static text item in the 'DITL' resource.

Since there are four text replacement variables, ParamText can supply up to four text strings for a single alert or dialog.

Setting the Font For Controls in a Dialog - 'dftb' Resources

When an embedding hierarchy is established in a dialog, you can specify the initial font settings for all controls in a dialog by creating a dialog font table resource (resource type 'dftb') with the same resource ID as the alert or dialog's 'DITL' resource. When a 'dftb' resource is read in, the control font styles are set, and the resource is marked purgeable.

The 'dftb' resource is the resource-based equivalent of the programmatic method of setting a control's font using the function SetControlFontStyle described at Chapter 7.

Structure of a Compiled 'dftb' Resource

Fig 11 shows the structure of a compiled 'dftb' resource and of a constituent dialog font table entry.

The following describes the main fields of the 'dftb' resource and the dialog control font entry:

Field

Description

NUMBER OF ENTRIES

Specifies the number of entries in the resource. Each entry is a dialog control font structure.

FIRST DIALOG CONTROL FONT ENTRY... LASTDIALOG CONTROL FONT ENTRY

Dialog control font structures. Each comprises type, dialog font flags, font ID, font size, font style, text mode, justification, text color, background color, and font name.

TYPE

Specifies whether there is font information for the dialog or alert item in the 'DITL'. 0 means that there is no font information for the item, that no data follows, and that the entry is to be skipped. 1 means that there is font information for the item, and that the rest of the structure is read.

DIALOG FONT FLAGS

Specifies which other fields in the dialog font table should be used. (See Dialog Font Flag Constants, below.)

FONT ID

The ID of the font family to use. (See Meta Font Constants, below, for more information about the constants that you can specify.) If this bit is set to 0, the system default font is used.

FONT SIZE

If the kDialogFontUseSizeMask bit in the dialog font flags field is set, the point size of the text. If the kDialogFontAddSizeMask bit is set, the size to add to the current point size of the text.

If a constant representing the system font, small system font, or small emphasized system font is specified in the Font ID field, this field is ignored.

STYLE

The text style (normal, bold, italic,underlined, outline, shadow, condensed, or extended.)

TEXT MODE

Specifies how characters are drawn. (See Chapter 12 for a discussion of transfer modes.)

JUSTIFICATION

Justification (left, right, centered, or system-justified).

TEXT COLOR

Colour to use when drawing the text.

BACKGROUND COLOR

Colour to use when drawing the background behind the text. In certain text modes, background colour is ignored.

FONT NAME

The font name to be used. This overrides the font ID.

Dialog Font Flag Constants

You can set the following bits in the dialog font flags field of a dialog control font entry to specify the fields in the entry that should be used

Constant

Value

Meaning

kDialogFontNoFontStyle 0x0000

No font style information is applied.

kDialogFontUseFontMask 0x0001

The specified font ID is applied.

kDialogFontUseFaceMask 0x0002

The specified font style is applied.

kDialogFontUseSizeMask 0x0004

The specified font size is applied.

kDialogFontUseForeColorMask 0x0008

The specified text color is applied. This flag only applies to static text controls.

kDialogFontUseBackColorMask 0x0010

The specified background color is applied. This flag only applies to static text controls.

kDialogFontUseModeMask 0x0020

The specified text mode is applied.

kDialogFontUseJustMask 0x0040

The specified text justification is applied.

kDialogFontUseAllMask 0x00FF

All flags in this mask will be set except kDialogFontAddFontSizeMask and kDialogFontUseFontNameMask.

kDialogFontAddFontSizeMask 0x0100

The specified font size will be added to the existing font size specified in the Font Size field of the dialog font table resource.

kDialogFontUseFontNameMask 0x0200

The string in the Font Name field will be used for the font name instead of the specified font ID.

Meta Font Constants

You can use the following meta font constants in the font ID field of a dialog control font entry to specify the style, size, and font family of a control's font. You should use these meta font constants whenever possible because the system font can be changed by the user in Mac OS 8/9. If none of these constants are specified, the control uses the system font unless a control with a variant that uses the window font has been specified.

Constant

Value

Meaning In Roman Script System

kControlFontBigSystemFont -1

Use the system font.

kControlFontSmallSystemFont -2

Use the small system font.

kControlFontSmallBoldSystemFont -3

Use the small boldsystem font.

kControlFontSmallBoldSystemFont -4

Use the small emphasized system font.

Another advantage of using these meta font constants is that you can be sure of getting the correct font on a Macintosh using a different script system, such as kanji.

Creating a 'dftb' Resource Using Resorcerer

Fig 12 shows a dialog control font entry in a 'dftb' resource being edited with Resorcerer.

Displaying Alerts and Dialogs

As previously stated:

  • StandardAlert, CreateStandardAlert and RunStandardAlert are used to create and display alerts.

  • GetNewDialog is used to create dialogs using descriptive information supplied by 'DLOG' and 'dlgx' resources, and NewFeaturesDialog is used to create dialogs programmatically. Both creation methods allow you to specify whether the dialog is to be initially visible, and both allow you to specify whether or not the dialog is to be brought to the front of all other windows when it is opened.

To display a dialog which is specified to be invisible on creation, you must call ShowWindow following the GetNewDialog or NewFeaturesDialog call to display the dialog. In addition, you should invariably pass (WindowRef) -1 in the behind and inBehind and parameters of, respectively, GetNewDialog and NewFeaturesDialog call so as to display a dialog as the active (frontmost) window.

Window Deactivation and Menu Adjustment

When an alert or dialog is displayed:

  • The frontmost window (assuming one exists) must be deactivated.

  • The application's menus must be adjusted to reflect the differing levels of permitted menu access which apply in the presence of the various types of alert and dialog. (As will be seen, the system software automatically performs some of this menu adjustment for you.)

Prior to the introduction of Mac OS 8 and the Appearance Manager, window deactivation when a movable modal dialog was displayed was handled in the same way as applies in the case of a modeless dialog, that is, within the application's main event loop. However, with the introduction of the Appearance Manager, when the kDialogFlagsHandleMovableModal bit is set in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, ModalDialog is used to handle all user interaction within the dialog. (Previously, this user interaction was handled within the main event loop.) This has implications for the way your application deactivates the front window when a movable modal dialog is displayed.

Prior to the introduction of Mac OS 8 and the Appearance Manager, menu adjustment when a movable modal dialog was displayed was performed by the application. However, when a movable modal dialog is created by setting the kDialogFlagsHandleMovableModal bit in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, menu adjusment is performed by the Dialog Manager and Menu Manager.

All that follows assumes that the kDialogFlagsHandleMovableModal bit is set in the 'dlgx' resource, or in the inFlags parameter of NewFeaturesDialog, and that, as a consequence:

1

Your application calls ModalDialog to handle all user interaction within movable modal dialogs (as is the case with modal dialogs).

2

Menu adjustment will be performed automatically by the Dialog Manager and Menu Manager when a movable modal dialog is displayed (as is the case with modal dialogs).

Window Deactivation - Modeless Dialogs

You do not have to deactivate the front window explicitly when displaying a modeless dialog. The Event Manager continues sending your application activate events for your windows as needed, which you typically handle in your main event loop.

Window Deactivation - Modal and Movable Modal Alerts and Dialogs

When a modal or movable modal dialog is created and displayed, your application (dialogs) or StandardAlert and RunStandardAlert (alerts) calls ModalDialog to handle all user interaction within the alert or dialog until the alert or dialog is dismissed. Events, which are ordinarily handled within your application's main event loop, will then be trapped and handled by ModalDialog. This means that your window activation/deactivation function will not now be called as it normally would following the opening of a new window. Accordingly, if one of your application's windows is active, you must explicitly deactivate it before displaying a modal or movable modal alert or dialog.

Menu Adjustment - Modeless Dialogs

When your application displays a modeless dialog, it is responsible for all menu disabling and enabling. Your application should thus perform the following tasks:

  • Disable those menus whose items are not relevant to the modeless dialog.

  • For modeless dialogs that contain edit text controls, enable the Edit menu and support the Cut, Copy, Paste, and Clear items using the Dialog Manager functions DialogCut, DialogCopy, DialogPaste and DialogDelete.

Your application is also responsible for all menu enabling when a modeless dialog is dismissed.

Menu Adjustment - Modal Alerts and Dialogs

When your application displays a modal alert or dialog, the Dialog Manager and Menu Manager interact to provide varying degrees of access to the menus in your menu bar, as follows:

  • On Mac OS 8/9, the Mac OS 8/9 Application menu, and all items in the Help menu except the Show Balloons/Hide Balloons item are disabled. On Mac OS X, all but the Apple and Application menus are disabled.

  • Your application's menus are disabled.

  • If the modal dialog contains a visible and active edit text item, the Edit menu and its Cut, Copy and Paste items are enabled.

When the user dismisses the modal alert or dialog, the Menu Manager restores all menus to their previous state.

Menu Adjustment - Movable Modal Alerts and Dialogs

When your application displays a movable modal alert or dialog, the Dialog Manager and Menu Manager interact to provide the same access to the menus in your menu bar as applies in the case of modal alerts and dialogs except that, in this case, the Help and Mac OS 8/9 Process menus are left enabled.

When the user dismisses the movable modal alert or dialog, the Menu Manager restores all menus to their previous state.

Displaying Multiple Alerts and Dialogs

The user should never see more than one modal dialog and one modal alert on the screen simultaneously. However, you can present multiple simultaneous modeless dialogs just as you can present multiple document windows.

Resizing a Dialog

You can use the function AutoSizeDialog to automatically resize static text items and their dialogs to accommodate changed static text. For each static text item found, AutoSizeDialog adjusts the static text control and the bottom of the dialog window. Any items below a static text control are moved down.

Handling Events in Alerts and Dialogs

Overview

Modal and Movable Modal Alerts and Dialogs

When StandardAlert, CreateStandardAlert, and RunStandardAlert are used to create and display alerts, the Dialog Manager handles all of the events generated by the user until the user clicks a push button. When the user clicks a push button, these functions highlight the push button briefly, close the alert and report the user's selection to the application.

As previously stated, ModalDialog handles all user interaction within modal and movable modal dialogs. When the user selects an enabled item, ModalDialog reports that the user selected the item and then exits. Your application is then responsible for performing the appropriate action in relation to that item. Your application typically calls ModalDialog repeatedly until the user dismisses the dialog.

The filterProc field of the standard alert structure associated with the StandardAlert function, the filterProc parameter of the RunStandardAlert function, and the modalFilter parameter of the ModalDialog function take a universal procedure pointer to a callback function known as an event filter function. The Dialog Manager provides a standard event filter (callback) function, which is used if NULL is passed in the filterProc or modalFilter parameters or assigned to the filterProc field; however, you should supply an application-defined event filter (callback) function for modal and movable modal alerts and dialogs so as to avoid a basic limitation of the standard event filter (callback) function. (See Event Filter Functions For Modal and Movable Modal Alerts and Dialogs, below.)

Modeless dialogs

For modeless dialogs, you can use the function IsDialogEvent to determine whether the event occurred while a modeless dialog was the frontmost window and then, optionally, use the function DialogSelect to handle the event if it belongs to a modeless dialog. DialogSelect is similar to ModalDialog except that it returns control after every event, not just events relating to an enabled item. Also, DialogSelect does not pass events to an event filter (callback) function.

Responding to Events in Controls

Controls and Control Values

For clicks in those types of controls for which you need to determine or change the control's value, your application should use the Control Manager functions GetControlValue and SetControlValue to get and set the value. When the user clicks on the OK push button, your application should perform whatever action is necessary to reflect the values returned by the controls.

Controls That Accept Keyboard Input

Edit text controls and clock controls, which both accept keyboard input, are typically disabled because you generally do not need to be informed every time the user clicks on one of them or types a character. Instead, you simply need to retrieve the text in the edit text control, or the clock's date/time value, when the user clicks the OK push button.

When you use ModalDialog (key-down events in edit text controls and clock controls in modal or movable modal dialogs) or DialogSelect (key-down events in edit text controls and clock controls in modeless dialogs), keystrokes and mouse actions within those controls are handled automatically. In the case of an edit text control, this means that:

  • A blinking vertical bar, called the insertion point caret, appears when the user clicks the item.

  • When the user drags over text or double-clicks a word, that text is highlighted and replaced by whatever the user types.

  • Highlighting of text is extended or shortened when the user holds down the Shift key while clicking or dragging.

  • Highlighted text, or the character preceding the insertion point caret, is deleted when the user presses the backspace key.

  • Highlighted text, or the character following the insertion point caret, is deleted when the user presses the delete key.

  • When the user presses the Tab key, the cursor and keyboard focus frame automatically advance to the next edit text control, clock control, or list box (if any) in the item list, wrapping around to the first one if there are no more items.

Caret Blinking in Edit Text Controls

ModalDialog will cause the the insertion point caret to blink in edit text controls in modal and movable modal dialogs. On Mac OS 8/9, for edit text controls in a modeless dialog, you should call IdleControls in your main event loop's idle processing function. (This is not necessary on Mac OS X because controls on Mac OS X have their own built-in timers.) IdleControls calls the edit text control with an idle event so that the control can call TEIdle to make the insertion point caret blink. You should ensure that, when caret blinking is required, the sleep parameter in the WaitNextEvent call is set to a value no greater that that returned by GetCaretTime.

Responding to Events in Modal and Movable Modal Alerts

StandardAlert and RunStandardAlert handle events automatically, calling ModalDialog internally.

If the event is a mouse-down anywhere outside the content region of a modal alert, ModalDialog emits the system alert sound and gets the next event.

If the event is a mouse-down outside the content region of a movable modal alert and within a window belonging to the application, ModalDialog emits the system alert sound and gets the next event. If the mouse-down is not within the content region or a window belonging to the application, ModalDialog performs alert dragging (if the mouse-down is within the title bar) or sends the application to the background (if the mouse-down is not within the title bar).

ModalDialog is continually called until the user clicks an enabled control, at which time StandardAlert and RunStandardAlert remove the alert from the screen and return the item number of the selected control. Your application then should then respond appropriately.

The standard event filter (callback) function allows users to use the Return or Enter key to achieve the same effect as a click on the default push button. When you write your own event filter (callback) function, you should ensure that that function retains this behaviour. ModalDialog passes events inside the alert to your event filter (callback) function before handling the event. Your event filter (callback) function thus provides a means to:

  • Handle events which ModalDialog does not handle.

  • Override events ModalDialog would otherwise handle.

If your event filter (callback) function does not handle an event inside an alert in its own way, ModalDialog handles the event as follows:

  • For activate or update events,, ModalDialog activates or updates the alert window.

  • For mouse-down events in a trackable control, TrackControl is called to track the mouse. If the user releases the mouse button while the cursor is still in the control, the alert is removed and the control's item number is returned.

  • For a mouse-down event in a disabled item, or in no item, or if any other event occurs, nothing happens.

Responding To Events in Modal and Movable Modal dialogs

Your application should call ModalDialog immediately after displaying a modal or movable modal dialog. ModalDialog repeatedly handles events inside the dialog until an event involving an enabled item occurs, at which time ModalDialog exits, returning the item number. Your application should then respond appropriately. ModalDialog should be continually called until the user clicks on the OK, Cancel or Don't Save push button, at which time your application should close the dialog.

If the event is a mouse-down anywhere outside the content region of a modal dialog, ModalDialog emits the system alert sound and gets the next event.

If the event is a mouse-down outside the content region of a movable modal dialog and within a window belonging to the application, ModalDialog emits the system alert sound and gets the next event. If the mouse down is not within the content region or a window belonging to the application, ModalDialog performs dialog dragging (if the mouse-down is within the title bar) or sends the application to the background (if the mouse-down is not within the title bar).

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

  • For activate or update events, ModalDialog activates or updates the dialog window.

  • If the event is a mouse-down while the cursor is in a control that accepts keyboard input (that is, an edit text control or a clock control), ModalDialog responds to the mouse activity by either displaying an insertion point or by selecting text in an edit text control or by highlighting the appropriate part of the clock control. Where there is more than one control that accepts keyboard input, ModalDialog moves the keyboard focus to that control. If a key-down event occurs and there is an edit text control in the dialog, ModalDialog uses TextEdit to handle text entry and editing automatically. For an enabled edit text control, ModalDialog returns its item number after it receives either the mouse-down or key-down event. (Normally, edit text controls should be disabled.)

  • For mouse-down events in a trackable control, TrackControl is called to track the mouse. If the user releases the mouse button while the cursor is still in the control, the control's item number is returned.

  • If the event is a Tab key key-down event and there is more than one control that accepts keyboard input, ModalDialog moves the keyboard focus to the next such item in the item list.

  • For a mouse-down event in a disabled item, or in no item, or if any other event occurs, nothing happens.

Specifying the Events To Be Received by ModalDialog

The function SetModalDialogEventMask may be used to specify the events to be received by the ModalDialog function for a given modal or movable modal dialog. This allows your application to specify additional events that are not by default received by ModalDialog, such as operating system events. If you us this function to change the ModalDialog function's event mask, you must pass ModalDialog a universal procedure pointer to your own event filter (callback) function to handle the added events.

You can ascertain the events to be received by ModalDialog by calling GetModalDialogEventMask.

Simulating Item Selection

You can cause the Dialog Manager to simulate item selection in a modal or movable modal dialog using the function SetDialogTimeout. You can use this function in circumstances where you wish to start a countdown for a specified duration for a specified dialog. When the specified time elapses, the Dialog Manager simulates a click on the specified button. The Dialog Manager will not simulate item selection until ModalDialog processes an event.

You can ascertain the original countdown duration, the time remaining, and the item selection to be simulated by calling GetDialogTimeout.

Event Filter (Callback) Functions For Modal and Movable Modal Alerts and Dialogs

The standard event filter (callback) function dates from the early days of the Macintosh, when a single application controlled the computer. With the introduction of multitasking, however, the standard event filter (callback) proved to be somewhat inadequate, its main deficiency being that it does not cater for the updating of either the parent application's windows or those belonging to background applications. (This deficiency is only relevant on Mac OS 8/9.) Your application should therefore provide an application-defined event filter (callback) function which compensates for this inadequacy and handles other events you wish the function to handle.

The standard event filter (callback) function performs the following checks and actions:

  • Checks whether the user has pressed the Return or Enter key and, if so, highlights the default push button for eight ticks (Mac OS 8/9 only) and returns the item number of that push button. (Unless informed otherwise, the Dialog Manager assumes that the first item in the item list is the default push button.)

  • For dialogs only, and only if the application has previously called certain Dialog Manager functions (see below):

    • Checks whether the user has pressed the Escape key or Command-period and, if so, highlights the Cancel push button for eight ticks (Mac OS 8/9 only) and returns the item number of that button.

    • Check whether the cursor is over an edit text item and, if so, changes the cursor shape to the I-Beam cursor.

As a minimum, your application-defined event filter (callback) function should ensure that these checks and actions are performed and should also:

  • For Mac OS 8/9 only, handle update events not belonging to the alert or dialog so as to allow the application to update its own windows, and return false. (Note that, by responding to update events in the application's own windows in this way, you also allow ModalDialog to perform a minor switch when necessary so that background applications can update their windows as well.)

  • Return false for all events that your event filter (callback) function does not handle.

Defining an Event Filter Function

Part of the recommended approach to defining a basic event filter (callback) function is to continue to use the standard event filter (callback) function to perform its checks and actions as described above. This requires certain preliminary action which, for dialogs, requires calls similar to the following examples after the dialog is created and before the call to ModalDialog:

     // Tell the Dialog Manager which is the default push button item, alias the Return and 
     // Enter keys to that item, and draw the default ring around that item (Mac OS 8/9) or
     // make it pulsing blue (Mac OS X).

 
     SetDialogDefaultItem(myDialogRef,iOK);

     // Tell the Dialog Manager which is the Cancel push button item, and alias 
     // the escape key and Command-period key presses to that item.

     SetDialogCancelItem(myDialogRef,iCancel);

     // Tell the Dialog Manager to track the cursor and change it to the I-Beam
     // cursor shape whenever it is over an edit text item.

     SetDialogTracksCursor(myDialogRef,true);

Note that, for all this to work, it is essential that the default and Cancel push buttons, and edit text items, be specified as primitives, not as actual controls, in the 'DLOG' resource.

With those preparations made, you would define your basic event filter (callback) (callback) function as in the following example:

     Boolean  myEventFilterFunction(DialogRef dialogRef,EventRecord *eventFuncPtr,
                                    SInt16 *itemHit)
     {
       Boolean  handledEvent;
       GrafPtr  oldPort;
  
       handledEvent = false;
  
       if((eventStrucPtr->what == updateEvt) && 
          ((WindowRef) eventStrucPtr->message != dialogRef))
       {
         // If the event is an update event, and if it is not for the dialog or alert, call 
         // your application's window updating function, and return false.

         if(!gRunningOnX)
           doUpdate(eventStrucPtr);
       }
       else
       {
         // If the event was not an update, first save the current graphics port 
         // and set the alert or dialog's graphics port as the current 
         // graphics port.  This is necessary when you have called 
         // SetDialogTrackCursor to cause the Dialog Manager to track cursor 
         // position.

         GetPort(&oldPort);
         SetPortDialogPort(dialogRef);
    
         // Pass the event to the standard event filter function for handling. 
         // If the function handles the event, it will return true and, in the 
         // itemHit parameter, the number of the item that it handled. ModalDialog, 
         // StandardAlert, and RunStandardAlert then return this item number in their
         // own itemHit parameter.

         handledEvent = StdFilterProc(dialogRef,eventFuncPtr,itemHit);

         // Make the saved graphics port the current graphics port again.
    
         SetPort(oldPort);
       }

       // Return true or false, as appropriate.

       return(handledEvent);
}

StandardAlert, RunStandardAlert, and ModalDialog pass events to your event filter (callback) function before handling each event, and will handle the event if your event filter (callback) function returns false.

A major difference between modal Alerts and Dialogs and movable modal Alerts and Dialogs is that, in the case of the latter, all events are passed to your event filter (callback) function for handling. This allows you to, for example, handle suspend and resume events when your application is either moved to the background or brought to the front, as well as other events you might want to handle.

You can also use your event filter (callback) function to handle events that ModalDialog does not handle, such as keyboard equivalents and mouse-down events.

Responding to Events in Modeless dialogs

As previously stated, you can use the function IsDialogEvent to determine whether an event occurred in a modeless dialog or a document window and then call DialogSelect to handle the event if it occurred in a modeless dialog. DialogSelect handles the event as follows:

  • For activate or update events, DialogSelect activates or updates the modeless dialog and returns false.

  • If the event is a key-down or auto-key event, and there is an edit text item in the modeless dialog, DialogSelect uses TextEdit to handle text entry and editing and returns true and the item number. If there is no edit-text item, DialogSelect returns false.

  • For mouse-downs in an edit text item, DialogSelect displays the insertion point caret or selects text as appropriate. DialogSelect returns false if the edit text item is disabled, and true and the item number if it is enabled. (Normally, edit text items should be disabled.)

  • For mouse-downs in an enabled trackable control, DialogSelect calls TrackControl and, if the user releases the mouse button while the cursor is still within the control, returns true and the item number.

  • For mouse-downs on a disabled item, or in no item, or if any other event occurs DialogSelect does nothing.

In the case of a key-down or auto-key event in an edit text item, you will ordinarily need to filter out Return and Enter key presses and certain Command-key equivalents so that they are not passed to DialogSelect. In the case of Return and Enter key presses, you should also highlight the associated push button for eight ticks (for Mac OS 8/9) before calling the function which responds to hits on the OK button. In the case of Command-key presses, you should only allow Command-X, Command-C, and Command-V to be passed to DialogSelect (so that DialogSelect can support cut, copy, and paste actions within the edit text control) and pass any other Command-key equivalents to your application's menu handling function.

Closing and Disposing of Dialogs

CloseDialog closes the dialog's window and removes it from the screen, and frees up the memory occupied by most types of items in the item list and related data structures. It does not release the memory occupied by the dialog object or item list.

DisposeDialog closes the dialog's window and deletes it from the window list, and releases the memory occupied by the dialog object, item list, and most types of items. (Handles leading to icons and pictures are not released.)

For modeless dialogs, you might find it more efficient to hide the dialog with HideWindow rather than dispose of the dialog. In that way, the dialog will remain available, and in the same location and with the same settings as when it was last used.

Creating Displaying and Handling Window-Modal (Sheet) Alerts and Dialogs

Window-Modal (Sheet) Alerts

Window-modal (sheet) alerts are created using the function CreateStandardSheet:

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

alertType

The level of the alert. Relevant constants are kAlertStopAlert, kAlertNoteAlert, kAlertCautionAlert, and kAlertPlainAlert.

error

The message text.

explanation

The informative text.

param

A pointer to a standard CFString alert parameter structure (see above). NULL indicates that none of the features provided by the standard alert structure are required.

notifyTarget

The event target to be notified when the sheet is closed.

outSheet

On return, the sheet's dialog reference.

The sheet will be invisible when created. A call to ShowSheetWindow displays the sheet.

If the sheet has more than one button, your application will need to determine which button was hit by the user. This requires the use of the Carbon event model (see Chapter 17) and the installation of an event handler on the event target. The event target is ordinarily the owner window, in which case you pass a reference to that window in a call to GetWindowEventTarget and pass the returned event target reference in the notifyTarget parameter of CreateStandardSheet. The Carbon event handler you install should respond to the kEventProcessCommand Carbon event type and should test for the command IDs kHICommandOK, kHICommandCancel, and kHICommandOther in order to determine which button was hit.

If the sheet has only one button (an OK button), you can simply pass the returned event target reference in the notifyTarget parameter (so that the CreateStandardSheet call will not fail) and not install a handler. The sheet will be dismissed when the button is hit.

Window-Modal (Sheet) Dialogs

Window-modal (sheet) dialogs, like other dialogs, may be created using GetNewDialog or NewFeaturesDialog. The window definition ID should be kWindowSheetProc (1088) and the dialog should be created invisible.

A call to ShowSheetWindow displays the sheet. Your application should ensure that only one sheet is displayed in a window at one time.

Events in window-modal (sheet) dialogs may be handled in the same way as for modeless dialogs.

Balloon Help For Dialogs - Mac OS 8/9

Two basic options are available for adding help balloons to Dialogs for Mac OS 8/9:

  • Adding a balloon help item to the item list ('DITL') resource, which will associate either a rectangle help ('hrct') resource or a dialog help ('hdlg') resource with that 'DITL' resource. Each hot rectangle component in the 'hrct' resource, and each dialog item component in the 'hdlg' resource, corresponds to an item number in the 'DITL' resource.

  • Supplying a window help ('hwin') resource, which will associate help balloons defined in either 'hrct' resources or 'hdlg' resources with the dialog's window.

    'hrct' and 'hwin' resources are described at Chapter 4.

The option of using a balloon help item (usually referred to as simply a "help item") overcomes the major limitation of the 'hwin' resource methodology, which is the inability to adequately differentiate between dialogs with no titles (see Chaper 4 - Windows, Fig 14). On the other hand, adopting the help item methodology means that you can only associate help balloons with items in the 'DITL' resource; you cannot provide a single help balloon for a group of related items (unless, of course, they are grouped within a primary or secondary group box).

Help items are invisible. In Resorcerer, the presence of a balloon help item in a 'DITL' resource is indicated only by a checkmark in the Balloon Help... item in the Item menu. A help item's presence in the 'DITL' resource is completely ignored by the Dialog Manager.

When the help item methodolgy is used, the Help Manager automatically tracks the cursor and displays help balloons when the following conditions are met: the dialog has a help item in its 'DITL' resource; your application calls the Dialog Manager functions ModalDialog orIsDialogEvent; balloon help is enabled.

Figs 13 and 14 at Chapter 4 show 'hrct' and 'hwin' resources being created using Resorcerer.

Figs 13 and 14 below show a help item and a 'hdlg' (dialog help) resource being created using Resorcerer.

Help Tags For Dialogs - Mac OS X

Balloon help is not available on Mac OS X. On Mac OS X, you should use help tags instead. Help tag creation is addressed at Chapter 25.

Main Dialog Manager Constants, Data Types and Functions

Constants

Dialog Item Types
kControlDialogItem              = 4
kButtonDialogItem               = kControlDialogItem | 0
kCheckBoxDialogItem             = kControlDialogItem | 1
kRadioButtonDialogItem          = kControlDialogItem | 2
kResourceControlDialogItem      = kControlDialogItem | 3
kStaticTextDialogItem           = 8
kEditTextDialogItem             = 16
kIconDialogItem                 = 32
kPictureDialogItem              = 64
kUserDialogItem                 = 0
kItemDisableBit                 = 128

Standard Item Numbers for OK and Cancel Push Buttons

KStdOKItemIndex                 = 1
KStdCancelItemIndex             = 2

Resource IDs of Alert Icons

kStopIcon                       = 0
kNoteIcon                       = 1
kCautionIcon                    = 2

Dialog Item List Manipulation

overlayDITL                     = 0
appendDITLRight                 = 1
appendDITLBottom                = 2

Alert Types

kAlertStopAlert                 = 0
kAlertNoteAlert                 = 1
kAlertCautionAlert              = 2
kAlertPlainAlert                = 3

Standard Alert Push Button Numbers

kAlertStdAlertOKButton          = 1
kAlertStdAlertCancelButton      = 2
kAlertStdAlertOtherButton       = 3
kAlertStdAlertHelpButton        = 4

Alert Default Text

kAlertDefaultOKText             = -1
kAlertDefaultCancelText         = -1
kAlertDefaultOtherText          = -1

Dialog Feature Flags

kDialogFlagsUseThemeBackground  = (1 << 0)
kDialogFlagsUseControlHierarchy = (1 << 1)
kDialogFlagsHandleMovableModal  = (1 << 2)
kDialogFlagsUseThemeControls    = (1 << 3)

Dialog Font Flags

kDialogFontNoFontStyle          = 0
kDialogFontUseFontMask          = 0x0001
kDialogFontUseFaceMask          = 0x0002
kDialogFontUseSizeMask          = 0x0004
kDialogFontUseForeColorMask     = 0x0008
kDialogFontUseBackColorMask     = 0x0010
kDialogFontUseModeMask          = 0x0020
kDialogFontUseJustMask          = 0x0040
kDialogFontUseAllMask           = 0x00FF
kDialogFontAddFontSizeMask      = 0x0100
kDialogFontUseFontNameMask      = 0x0200

Constants Used for in NewFeaturesDialog inProcID Parameter

kWindowDocumentProc             = 1024  Modeless dialog
kWindowPlainDialogProc          = 1040  Modal dialog
kWindowShadowDialogProc         = 1041  Modal dialog
kWindowModalDialogProc          = 1042  Modal dialog
kWindowMovableModalDialogProc   = 1043  Movable modal dialog
kWindowAlertProc                = 1044  Modal alert
kWindowMovableAlertProc         = 1045  Movable modal alert

Data Types

typedef struct OpaqueDialogPtr *DialogPtr;
typedef DialogPtr DialogRef;

Standard Alert Parameter Structure

struct AlertStdAlertParamRec 
{
  Boolean        movable;
  Boolean        helpButton;
  ModalFilterUPP filterProc;
  ConstStringPtr defaultText;
  ConstStringPtr cancelText;
  ConstStringPtr otherText;
  SInt16         defaultButton;
  SInt16         cancelButton;
  UInt16         position;
};
typedef struct AlertStdAlertParamRec AlertStdAlertParamRec;
typedef AlertStdAlertParamRec *AlertStdAlertParamPtr;

Standard CFStringAlert Alert Paramater Structure

struct AlertStdCFStringAlertParamRec
{
  UInt32      version;
  Boolean     movable;
  Boolean     helpButton;
  CFStringRef defaultText;
  CFStringRef cancelText;
  CFStringRef otherText;
  SInt16      defaultButton;
  SInt16      cancelButton;
  UInt16      position;
  OptionBits  flags;
};
typedef struct AlertStdCFStringAlertParamRec AlertStdCFStringAlertParamRec;
typedef AlertStdCFStringAlertParamRec *AlertStdCFStringAlertParamPtr;

Functions

Creating Alerts

OSErr      StandardAlert(AlertType inAlertType, ConstStr255Param inError,
           ConstStr255Param inExplanation,const AlertStdAlertParamPtr inAlertParam,
           SInt16 *outItemHit);
OSStatus   CreateStandardAlert(AlertType alertType,CFStringRef error,CFStringRef explanation,
           const AlertStdCFStringAlertParamRec *param,DialogRef outAlert);
OSStatus   RunStandardAlert(DialogRef inAlert,ModalFilterUPP filterProc,
           DialogItemIndex *outItemHit);
OSStatus   CreateStandardSheet(AlertType alertType,CFStringRef  error,CFStringRef explanation,
           const AlertStdCFStringAlertParamRec *param,EventTargetRef notifyTarget,
           DialogRef *outSheet);
OSStatus   GetStandardAlertDefaultParams(AlertStdCFStringAlertParamPtr param,UInt32 version);

Creating, Closing, and Disposing of Dialogs

DialogRef  GetNewDialog(short dialogID,void *dStorage,WindowRef behind);
DialogRef  NewFeaturesDialog(void *inStorage, const Rect *inBoundsRect,
           ConstStr255Param inTitle, Boolean inIsVisible,SInt16 inProcID,WindowRef inBehind,
           Boolean inGoAwayFlag,SInt32 inRefCon,Handle inItemListHandle,UInt32 inFlags);
OSErr      AutoSizeDialog(DialogRef inDialog);
void       CloseDialog(DialogRef theDialog);
void       DisposeDialog(DialogRef theDialog);

Creating Sheets (Mac OS X Only)

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

Dialog Object Accessor Functions

WindowRef  GetDialogWindow(DialogRef dialog);
TEHandle   GetDialogTextEditHandle(DialogRef dialog);
SInt16     GetDialogKeyboardFocusItem(DialogRef dialog);
SInt16     GetDialogDefaultItem(DialogRef dialog);
OSErr      SetDialogDefaultItem(DialogRef theDialog,DialogItemIndex newItem);
SInt16     GetDialogCancelItem(DialogRef dialog);
OSErr      SetDialogCancelItem(DialogRef theDialog,DialogItemIndex newItem);

Utility and Casting Functions

void       SetPortDialogPort(DialogRef dialog);
CGrafPtr   GetDialogPort(DialogRef dialog);
DialogRef  GetDialogFromWindow(WindowRef window);

Manipulating Items in Alerts and Dialogs

void       GetDialogItem(DialogRef theDialog,short itemNo,short *itemType,Handle *item,
           Rect *box);
void       SetDialogItem(DialogRef theDialog,short itemNo,short itemType,Handle item,
           const Rect *box);
OSErr      GetDialogItemAsControl(DialogRef inDialog,SInt16 inItemNo,
           ControlHandle *outControl);
OSErr      MoveDialogItem(DialogRef inDialog,SInt16 inItemNo,SInt16 inHoriz,SInt16 inVert);
OSErr      SizeDialogItem(DialogRef inDialog,SInt16 inItemNo,SInt16 inHeight,SInt16 inWidth);
void       HideDialogItem(DialogRef theDialog,short itemNo);
void       ShowDialogItem(DialogRef theDialog,short itemNo);
short      FindDialogItem(DialogRef theDialog,Point thePt);
void       AppendDITL(DialogRef theDialog,Handle theHandle,DITLMethod theMethod);
void       ShortenDITL(DialogRef theDialog,short numberItems);
OSErr      AppendDialogItemList(DialogRef 	dialog,SInt16 ditlID,DITLMethod method);
short      CountDITL(DialogRef the Dialog);
OSStatus   InsertDialogItem (DialogRef theDialog,DialogItemIndex afterItem,
           DialogItemType itemType,Handle itemHandle,const Rect *box);
OSStatus   RemoveDialogItems(DialogRef theDialog,DialogItemIndex itemNo,
           DialogItemIndex amountToRemove,Boolean disposeItemData);

Handling Text in Alerts and Dialogs

void       ParamText(ConstStr255Param param0,ConstStr255Param param1,ConstStr255Param param2,
           ConstStr255Param param3);
void       GetParamText(StringPtr param0,StringPtr param1,StringPtr param2,StringPtr param3);
void       GetDialogItemText(Handle item,Str255 text)
void       SetDialogItemText(Handle item,ConstStr255Param text);
void       SelectDialogItemText(DialogRef theDialog,short itemNo,short strtSel,short endSel);
void       SetDialogFont(short value);
void       DialogCut(DialogRef theDialog); 
void       DialogPaste(DialogRef theDialog); 
void       DialogCopy(DialogRef theDialog); 
void       DialogDelete(DialogRef theDialog); 

Handling Events in Dialogs

void       ModalDialog(ModalFilterUPP modalFilter,short *itemHit);
Boolean    IsDialogEvent(const EventRecord *theEvent);
Boolean    DialogSelect(const EventRecord *theEvent,DialogRef *theDialog,short *itemHit);
void       UpdateDialog(DialogRef theDialog,RgnHandle updateRgn);
void       DrawDialog(DialogRef theDialog);
OSStatus   SetModalDialogEventMask(DialogRef inDialog,EventMask inMask);
OSStatus   GetModalDialogEventMask(DialogRef inDialog,EventMask *outMask);
OSStatus   SetDialogTimeout(DialogRef inDialog,SInt16 inButtonToPress,UInt32 inSecondsToWait);
OSStatus   GetDialogTimeout(DialogRef inDialog,SInt16 *outButtonToPress,
           UInt32 *outSecondsToWait,UInt32 *outSecondsRemaining);
Boolean    StdFilterProc(DialogRef theDialog,EventRecord *event,DialogItemIndex *itemHit);
OSErr      GetStdFilterProc(ModalFilterUPP *theProc);
OSErr      SetDialogDefaultItem(DialogRef theDialog,DialogItemIndex newItem);
OSErr      SetDialogCancelItem(DialogRef theDialog,DialogItemIndex newItem);
OSErr      SetDialogTracksCursor(DialogRef theDialog,Boolean tracks);

Creating and Disposing of Universal Procedure Pointers for Event Filter (Callback) Functions

ModalFilterUPP  NewModalFilterUPP(ModalFilterProcPtr userRoutine);
void       DisposeModalFilterUPP(ModalFilterUPP userUPP);

Application-Defined (Callback) Function

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

Relevant Window Manager Functions (Mac OS X Only)

Showing and Hiding Sheets

OSStatus   ShowSheetWindow(WindowRef inSheet,WindowRef inParentWindow);
OSStatus   HideSheetWindow(WindowRef inSheet);
OSStatus   GetSheetWindowParent(WindowRef inSheet,WindowRef *outParentWindow);

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.