Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /: Chapter 6 - Dialog Manager

Summary of the Dialog Manager

Pascal Summary

Constants

CONST
{checking for AppendDITL, ShortenDITL, CountDITL using Gestalt function}
   gestaltDITLExtAttr = 'ditl';  {Gestalt selector for AppendDITL, etc.}
   gestaltDITLExtPresent = 0;    {if this bit's set, then AppendDITL, }
                                 { ShortenDITL, & CountDITL are available}

{item types for GetDialogItem, SetDialogItem}
   ctrlItem       = 4;     {add this constant to the next four constants}
   btnCtrl        = 0;     {standard button control}
   chkCtrl        = 1;     {standard checkbox control}
   radCtrl        = 2;     {standard radio button}
   resCtrl        = 3;     {control defined in a control resource}
   helpItem       = 1;     {help balloons}
   statText       = 8;     {static text}
   editText       = 16;    {editable text}
   iconItem       = 32;    {icon}
   picItem        = 64;    {QuickDraw picture}
   userItem       = 0;     {application-defined item}
   itemDisable    = 128;   {add to any of the above to disable it}

{item numbers of OK and Cancel buttons in alert boxes}
   ok       = 1;  {first button is OK button}
   cancel   = 2;  {second button is Cancel button}

{resource IDs of alert box icons}
   stopIcon    = 0;
   noteIcon    = 1;
   cautionIcon = 2;

{constants used for theMethod parameter in AppendDITL}
   overlayDITL       = 0;  {overlay existing items}
   appendDITLRight   = 1;  {append at right}
   appendDITLBottom  = 2;  {append at bottom}
{constants for procID parameter of NewDialog, NewColorDialog}
   dBoxProc          = 1;  {modal dialog box}
   noGrowDocProc     = 4;  {modeless dialog box}
   movableDBoxProc   = 5;  {movable modal dialog box}

Data Types

TYPE  DialogPtr      =  WindowPtr;
ResumeProcPtr        =  ProcPtr;
SoundProcPtr         =  ProcPtr;
ModalFilterProcPtr   =  ProcPtr;
DialogPeek           =  ^DialogRecord;
DialogRecord         =
RECORD
   window:     WindowRecord;  {dialog window}
   items:      Handle;        {item list resource}
   textH:      TEHandle;      {current editable text item}
   editField:  Integer;       {editable text item number minus 1}
   editOpen:   Integer;       {used internally}
   aDefItem:   Integer;       {default button item number}
END;

DITLMethod = Integer;

Dialog Manager Routines

Initializing the Dialog Manager

PROCEDURE InitDialogs(resumeProc: ResumeProcPtr);
PROCEDURE ErrorSound(soundProc: SoundProcPtr);
PROCEDURE SetDialogFont(fontNum: Integer); {also spelled SetDAFont}

Creating Alerts

{some routines have 2 spellings--see Table 6-1 for the alternate spellings}
FUNCTION Alert(alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer;
FUNCTION StopAlert(alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer;
FUNCTION NoteAlert(alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer;
FUNCTION CautionAlert(alertID: Integer; filterProc: 
ModalFilterProcPtr): Integer;
FUNCTION GetAlertStage: Integer;
PROCEDURE ResetAlertStage;

Creating and Disposing of Dialog Boxes

{some routines have 2 spellings--see Table 6-1 for the alternate spellings}
FUNCTION GetNewDialog(dialogID: Integer; dStorage: Ptr; 
behind:  WindowPtr): DialogPtr;
FUNCTION NewColorDialog(dStorage: Ptr; boundsRect: Rect; title: 
Str255; visible: Boolean; procID: Integer; 
behind: WindowPtr; goAwayFlag: Boolean; 
refCon: LongInt; items: Handle): DialogPtr;
FUNCTION NewDialog(dStorage:  Ptr; boundsRect: Rect; title: 
Str255; visible: Boolean; procID: Integer; 
behind: WindowPtr; goAwayFlag: Boolean; 
refCon: LongInt; items: Handle):  DialogPtr;
PROCEDURE CloseDialog(theDialog: DialogPtr);
PROCEDURE DisposeDialog(theDialog: DialogPtr);

Manipulating Items in Alert and Dialog Boxes

{some routines have 2 spellings--see Table 6-1 for the alternate spellings}
PROCEDURE GetDialogItem(theDialog: DialogPtr; itemNo: Integer; 
VAR itemType: Integer; VAR item: Handle; 
VAR box: Rect);
PROCEDURE SetDialogItem(theDialog: DialogPtr; itemNo: Integer; 
itemType: Integer; item: Handle; box: Rect);
PROCEDURE HideDialogItem (theDialog: DialogPtr; itemNo: Integer);
PROCEDURE ShowDialogItem(theDialog: DialogPtr; itemNo: Integer);
FUNCTION FindDialogItem(theDialog: DialogPtr; thePt: Point): Integer;
PROCEDURE AppendDITL(theDialog: DialogPtr; theDITL: Handle; 
theMethod: DITLMethod);
PROCEDURE ShortenDITL(theDialog: DialogPtr; numberItems: Integer);
FUNCTION CountDITL(theDialog: DialogPtr): Integer;

Handling Text in Alert and Dialog Boxes

{some routines have 2 spellings--see Table 6-1 for the alternate spellings}
PROCEDURE ParamText(param0: Str255; param1: Str255; 
param2: Str255; param3: Str255);
PROCEDURE GetDialogItemText(item: Handle; VAR text: Str255);
PROCEDURE SetDialogItemText(item: Handle; text: Str255);
PROCEDURE SelectDialogItemText
   (theDialog: DialogPtr; itemNo: Integer; 
strtSel: Integer; endSel: Integer);
PROCEDURE DialogCut(theDialog: DialogPtr);
PROCEDURE DialogCopy(theDialog: DialogPtr);
PROCEDURE DialogPaste(theDialog: DialogPtr);
PROCEDURE DialogDelete(theDialog: DialogPtr);

Handling Events in Dialog Boxes

{some routines have 2 spellings--see Table 6-1 for the alternate spellings}
PROCEDURE ModalDialog(filterProc: ModalFilterProcPtr; VAR itemHit: 
Integer);
FUNCTION IsDialogEvent(theEvent: EventRecord): Boolean;
FUNCTION DialogSelect(theEvent: EventRecord; VAR theDialog: 
DialogPtr; VAR itemHit: Integer): Boolean;
PROCEDURE DrawDialog(theDialog: DialogPtr);
PROCEDURE UpdateDialog(theDialog: DialogPtr; updateRgn: RgnHandle);

Application-Defined Routines

PROCEDURE MyItem(theWindow: WindowPtr; itemNo: Integer);
PROCEDURE MyAlertSound(soundNo: Integer);
FUNCTION MyEventFilter(theDialog: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: Integer): Boolean;

C Summary

Constants

enum {
/*checking for AppendDITL, ShortenDITL, CountDITL using Gestalt function*/
   #define gestaltDITLExtAttr 'ditl' /*Gestalt selector*/
   gestaltDITLExtPresent = 0     /*if this bit's set, then AppendDITL, */
                                 /* ShortenDITL, & CountDITL are available*/
};

enum {
/*item types for GetDItem, SetDItem*/
   ctrlItem       = 4,  /*add this constant to the next four constants*/
   btnCtrl        = 0,  /*standard button control*/
   chkCtrl        = 1,  /*standard checkbox control*/
   radCtrl        = 2,  /*standard radio button*/
   resCtrl        = 3,  /*control defined in a control resource*/
   statText       = 8,  /*static text*/
   editText       = 16, /*editable text*/
   iconItem       = 32, /*icon*/
   picItem        = 64, /*QuickDraw picture*/
   userItem       = 0,  /*application-defined item*/
   helpItem       = 1,  /*help balloons*/
   itemDisable    = 128,/*add to any of the above to disable it*/

/*item numbers of OK and Cancel buttons in alert boxes*/
   ok       = 1,  /*first button is OK button*/
   cancel   = 2,  /*second button is Cancel button*/

/*resource IDs of alert box icons*/
   stopIcon    = 0,
   noteIcon    = 1,
   cautionIcon = 2
};

enum {
/*constants used for theMethod parameter in AppendDITL*/
   overlayDITL       = 0,  /*overlay existing items*/
   appendDITLRight   = 1,  /*append at right*/
   appendDITLBottom  = 2   /*append at bottom*/
}; 

enum {
/*constants for procID parameter of NewDialog, NewColorDialog*/
   dBoxProc          = 1,  /*modal dialog box*/
   noGrowDocProc     = 4,  /*modeless dialog box*/
   movableDBoxProc   = 5   /*movable modal dialog box*/
};

Data Types

typedef WindowPtr DialogPtr;

typedef struct DialogRecord DialogRecord;
typedef struct DialogRecord *DialogPeek;

struct DialogRecord{
      WindowRecord   window;     /*dialog window*/
      Handle         items;      /*item list resource*/
      TEHandle       textH;      /*current editable text item*/
      short          editField;  /*editable text item number minus 1*/
      short          editOpen;   /*used internally*/
      short          aDefItem;   /*default button item number*/
};
typedef pascal void (*ResumeProcPtr)(void);
typedef pascal void (*SoundProcPtr)(void);
typedef pascal Boolean (*ModalFilterProcPtr)(DialogPtr theDialog, 
                                    EventRecord *theEvent, short *itemHit);
typedef short DITLMethod;

Dialog Manager Routines

Initializing the Dialog Manager

pascal void InitDialogs(ResumeProcPtr resumeProc);
pascal void ErrorSound(SoundProcPtr soundProc);
pascal void SetDialogFont(short fontNum); /*also spelled SetDAFont*/

Creating Alerts

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/
pascal short Alert(short alertID, ModalFilterProcPtr filterProc);
pascal short StopAlert(short alertID, ModalFilterProcPtr filterProc);
pascal short NoteAlert(short alertID, ModalFilterProcPtr filterProc);
pascal short CautionAlert(short alertID, ModalFilterProcPtr filterProc);
#define GetAlertStage() (* (short*) 0x0A9A);
pascal void ResetAlertStage(void);

Creating and Disposing of Dialog Boxes

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/
pascal DialogPtr GetNewDialog 
   (short dialogID, void *dStorage, 
WindowPtr behind);
pascal DialogPtr NewColorDialog 
   (void *dStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible,
short procID, WindowPtr behind, 
Boolean goAwayFlag, long refCon, Handle items);
pascal DialogPtr NewDialog
   (void *dStorage, const Rect *boundsRect, 
ConstStr255Param title, Boolean visible, 
short procID, WindowPtr behind, 
Boolean goAwayFlag, long refCon, 
Handle items);
pascal void CloseDialog(DialogPtr theDialog);
pascal void DisposeDialog(DialogPtr theDialog);

Manipulating Items in Alert and Dialog Boxes

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/
pascal void GetDialogItem(DialogPtr theDialog, short itemNo,
short *itemType, Handle *item, Rect *box);
pascal void SetDialogItem(DialogPtr theDialog, short itemNo, short 
itemType, Handle item, const Rect *box);
pascal void HideDialogItem(DialogPtr theDialog, short itemNo);
pascal void ShowDialogItem(DialogPtr theDialog, short itemNo);
pascal short FindDialogItem(DialogPtr theDialog, Point thePt);
pascal void AppendDITL(DialogPtr theDialog, Handle theDITL, 
DITLMethod theMethod);
pascal void ShortenDITL(DialogPtr theDialog, short numberItems);
pascal short CountDITL(DialogPtr theDialog);

Handling Text in Alert and Dialog Boxes

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/
pascal void ParamText(ConstStr255Param param0, 
ConstStr255Param param1,
ConstStr255Param param2, 
ConstStr255Param param3);
pascal void GetDialogItemText
   (Handle item, Str255 text);
pascal void SetDialogItemText
   (Handle item, ConstStr255Param text);
pascal void SelectDialogItemText
   (DialogPtr theDialog, short itemNo,
short strtSel, short endSel);
pascal void DialogCut(DialogPtr theDialog);
pascal void DialogCopy(DialogPtr theDialog);
pascal void DialogPaste(DialogPtr theDialog);
pascal void DialogDelete(DialogPtr theDialog);

Handling Events in Dialog Boxes

/*some routines have 2 spellings--see Table 6-1 for the alternate spellings*/
pascal void ModalDialog(ModalFilterProcPtr filterProc, short *itemHit);
pascal Boolean IsDialogEvent(const EventRecord *theEvent);
pascal Boolean DialogSelect(const EventRecord *theEvent, 
DialogPtr *theDialog, short *itemHit);
pascal void DrawDialog(DialogPtr theDialog);
pascal void UpdateDialog(DialogPtr theDialog, RgnHandle updateRgn);

Application-Defined Routines

pascal void MyItem(WindowPtr theWindow, short itemNo);
pascal void MyAlertSound(short soundNo);
pascal Boolean MyEventFilter(DialogPtr theDialog, *EventRecord theEvent,
*short itemHit);

Assembly-Language Summary

Data Structures

DialogRecord Data Structure
0 dWindow 156 bytes window record for the alert box or dialog box
156 items long handle to the item list resource for the alert box or dialog box
160 teHandle long handle to the current editable text item
164 editField word current editable text item
166 editOpen word used internally
168 aDefItem word item number of the default button

Global Variables
DAStrings Handles to text strings specified with the `ParamText` procedure
DABeeper Address of current sound procedure
DlgFont Font number for text in dialog boxes and alert boxes
ACount Alert stage number (0 through 3) of the last alert
ANumber Resource ID of last alert
ResumeProc Address of resume procedure (should not be used in System 7)

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

0	dWindow	156 bytes	window record for the alert box or dialog box
156	items	long	handle to the item list resource for the alert box or dialog box
160	teHandle	long	handle to the current editable text item
164	editField	word	current editable text item
166	editOpen	word	used internally
168	aDefItem	word	item number of the default button

DAStrings	Handles to text strings specified with the `ParamText` procedure
DABeeper	Address of current sound procedure
DlgFont	Font number for text in dialog boxes and alert boxes
ACount	Alert stage number (0 through 3) of the last alert
ANumber	Resource ID of last alert
ResumeProc	Address of resume procedure (should not be used in System 7)