Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Figures, Tables, and Listings
Color PlatesColor plates are immediately preceding the title page.
Color Plate 1 A color window
Color Plate 2 A color alert box
Color Plate 3 An icon family
Color Plate 4 Document icons
Chapter 1 Introduction to the Macintosh Toolbox 1-1
Figure 1-1 The SurfWriter application with multiple windows on the desktop 1-3
Figure 1-2 A typical window 1-6
Figure 1-3 Common controls 1-7
Figure 1-4 An alert box 1-8
Figure 1-5 Modal, movable modal, and modeless dialog boxes 1-9
Figure 2-1 Sources of events sent to your application 2-6
Figure 2-2 Low-level events 2-10
Figure 2-3 Operating-system events 2-11
Figure 2-4 High-level events 2-14
Figure 2-5 The modifiers field of the event record 2-20
Listing 2-1 Using the WaitNextEvent function 2-23
Listing 2-2 An event loop 2-24
Listing 2-3 Processing events 2-26
Figure 2-6 The event mask 2-27
Listing 2-4 The Rez input for a sample 'SIZE' resource 2-31
Listing 2-5 Handling mouse-down events 2-34
Figure 2-7 The message field of the event record for keyboard events 2-40
Figure 2-8 Keyboard translation 2-41
Figure 2-9 Virtual key codes for the Apple Keyboard II, ISO layout 2-42
Figure 2-10 Virtual key codes for the Apple Extended Keyboard II 2-43
Listing 2-6 Handling key-down and auto-key events 2-45
Listing 2-7 Handling key-down events 2-45
Listing 2-8 Scanning for a Command-period event 2-47
Figure 2-11 Responding to an update event for a window 2-50
Listing 2-9 Responding to update events 2-51
Figure 2-12 Responding to activate events for a window 2-53
Listing 2-10 Responding to activate events 2-54
Listing 2-11 Responding to disk-inserted events 2-57
Listing 2-12 Handling null events 2-58
Listing 2-13 Responding to operating-system events 2-60
Listing 2-14 Responding to suspend and resume events 2-62
Figure 2-13 The standard arrow cursor 2-64
Figure 2-14 The I-beam, crosshairs, plus sign, and wristwatch cursors 2-64
Figure 2-15 The arrow region and the I-beam region 2-65
Figure 2-16 Changing the cursor from the I-beam cursor to the arrow cursor 2-66
Listing 2-15 Changing the cursor 2-66
Listing 2-16 Accepting a high-level event 2-71
Listing 2-17 Posting a high-level event by application signature 2-75
Listing 2-18 Using the PPCBrowser function to post a high-level event 2-77
Figure 2-17 Structure of the KeyTranslate function result 2-112
Listing 2-19 A Rez template for a 'SIZE' resource 2-117
Figure 3-1 A pull-down menu, a submenu, and a pop-up menu 3-6
Figure 3-2 The SurfWriter application's menu bar with the Edit menu displayed 3-7
Figure 3-3 The menu bar of the SurfWriter application 3-10
Figure 3-4 The SurfWriter application's menu bar localized for another script system 3-10
Figure 3-5 Two menus with various characteristics 3-13
Figure 3-6 Menu items in a mutually exclusive group 3-15
Figure 3-7 Menu items in an accumulating group 3-15
Figure 3-8 Use of a checkmark and dash in an accumulating group 3-15
Table 3-1 Reserved keyboard equivalents for all systems 3-18
Table 3-2 Reserved keyboard equivalents for worldwide systems 3-19
Table 3-3 Other common keyboard equivalents 3-19
Figure 3-9 The Apple menu for the SurfWriter application 3-21
Figure 3-10 Choosing the About command of the SurfWriter application 3-22
Figure 3-11 The standard File menu for an application 3-22
Table 3-4 Actions for standard File menu commands 3-23
Figure 3-12 The standard Edit menu for an application 3-24
Table 3-5 Actions for standard Edit menu commands 3-25
Figure 3-13 A typical Font menu 3-26
Figure 3-14 A Font menu showing a selection containing more than one font 3-27
Figure 3-15 A typical Size menu 3-28
Figure 3-16 A dialog box to select a new point size for a font 3-28
Figure 3-17 Entering a new point size for a font 3-29
Figure 3-18 The Other command with a font size added to it 3-29
Figure 3-19 The Help menu of the SurfWriter application 3-30
Figure 3-20 Default help balloons for the Apple menu and Application menu 3-31
Figure 3-21 Help balloons for different states of the Cut command 3-31
Figure 3-22 Accessing the Keyboard menu from an application 3-32
Figure 3-23 SurfWriter's Application menu 3-33
Figure 3-24 A pop-up menu 3-34
Figure 3-25 A pop-up menu in its closed and open states 3-34
Figure 3-26 Making a selection from a pop-up menu 3-35
Figure 3-27 Choosing one attribute from a list of many 3-36
Figure 3-28 A dialog box with checkboxes and pop-up menus 3-37
Figure 3-29 A type-in pop-up menu in its closed and open states 3-37
Figure 3-30 A type-in pop-up menu with a user's choice added 3-38
Figure 3-31 A hierarchical menu item and its submenu 3-39
Listing 3-1 Rez input for a 'MENU' resource for the Apple menu 3-43
Table 3-6 Specifying submenus, script codes, reduced icons, small icons, and color icons of a menu item in a menu resource 3-46
Listing 3-2 Rez input for a 'MENU' resource for an Edit menu 3-48
Listing 3-3 Rez input for a 'MENU' resource for a File menu 3-49
Listing 3-4 Rez input for an 'MBAR' resource 3-49
Listing 3-5 Setting up an application's menus and menu bar 3-50
Listing 3-6 Saving and restoring menu color information 3-52
Figure 3-32 A menu item with a submenu 3-53
Listing 3-7 Rez input for a description of a hierarchical menu with a submenu 3-54
Listing 3-8 Creating a hierarchical menu 3-55
Figure 3-33 A pop-up menu in a dialog box 3-56
Listing 3-9 Changing the text of a menu item 3-59
Listing 3-10 Setting the font style of menu items 3-60
Listing 3-11 Adding marks to and removing marks from menu items 3-61
Figure 3-34 Icons in menu items 3-63
Listing 3-12 Specifying icons for menu items 3-63
Listing 3-13 Rez input for text of menu items 3-66
Listing 3-14 Adding an item to the Help menu 3-68
Listing 3-15 Adding menu items to the Apple menu 3-69
Listing 3-16 Adding font names to a menu 3-70
Listing 3-17 Determining whether a mouse-down event occurred 3-72
Listing 3-18 Determining when the cursor is in the menu bar 3-72
Listing 3-19 Adjusting an application's menus 3-74
Listing 3-20 Adjusting the File menu for a document window 3-74
Listing 3-21 Adjusting the Edit menu for a document window 3-75
Listing 3-22 Determining when a key is pressed 3-77
Listing 3-23 Checking a key-down event for a keyboard equivalent 3-78
Listing 3-24 Responding to the user's choice of a menu command 3-79
Listing 3-25 Responding to the user's choice of an item from the Apple menu 3-80
Listing 3-26 Responding to the user's choice of a command from the Help menu 3-81
Figure 3-35 A Size menu with user-specified size added 3-82
Listing 3-27 Handling the Size menu 3-83
Figure 3-36 Menu access from a modal dialog box 3-85
Listing 3-28 A sample menu definition procedure 3-89
Listing 3-29 Calculating the size of a menu 3-90
Listing 3-30 Drawing menu items 3-91
Listing 3-31 Choosing menu items 3-93
Table 3-7 Color information for menu entries 3-100
Table 3-8 Mapping between new and previous names of Menu Manager routines 3-102
Figure 3-37 Structure of a compiled menu ('MENU') resource 3-152
Figure 3-38 The variable-length data that describes menu items as defined by the standard menu definition procedure 3-153
Figure 3-39 Structure of a compiled menu bar ('MBAR') resource 3-155
Figure 3-40 Structure of a compiled menu color information table ('mctb') resource 3-156
Figure 3-41 Structure of a menu color entry in an 'mctb' resource 3-157
Figure 4-1 Multiple windows 4-4
Figure 4-2 A document window 4-5
Figure 4-3 Active and inactive document windows 4-7
Figure 4-4 A window of type zoomDocProc 4-8
Figure 4-5 A window of type zoomDocProc, with size box and inactive scroll bars 4-9
Figure 4-6 Window types for alert boxes and fixed-position modal dialog boxes 4-9
Figure 4-7 A window of type movableDBoxProc 4-10
Figure 4-8 A window of type noGrowDocProc 4-10
Figure 4-9 Seldom-used window types 4-11
Figure 4-10 Window frame, content region, and structure region 4-12
Figure 4-11 Scroll bars 4-14
Figure 4-12 Controls in a dialog box 4-15
Figure 4-13 The QuickDraw global coordinate plane 4-17
Figure 4-14 A window's local and global coordinate systems 4-19
Listing 4-1 Determining the window type 4-25
Listing 4-2 Rez input for a window ('WIND') resource for a document window 4-26
Listing 4-3 Creating a new window 4-28
Figure 4-15 Document window positions on a single screen 4-31
Figure 4-16 "Filling in" an empty document window position 4-31
Figure 4-17 Document window positions on multiple screens 4-33
Listing 4-4 Application-defined data structure for storing a window's state data 4-34
Listing 4-5 Saving a document window's position 4-34
Listing 4-6 Positioning the window when the user opens a saved document 4-36
Listing 4-7 Opening a saved document 4-37
Listing 4-8 Drawing a window 4-39
Figure 4-18 Moving one window and adding to another window's update region 4-40
Listing 4-9 Handling mouse-down events 4-44
Figure 4-19 The close box with and without highlighting 4-46
Figure 4-20 The zoom box with and without highlighting 4-47
Figure 4-21 The effects of BeginUpdate and EndUpdate on the visible region and
update region 4-49Listing 4-10 Handling update events 4-50
Listing 4-11 Handling activate events 4-51
Listing 4-12 Zooming a window 4-55
Listing 4-13 Resizing a window 4-58
Listing 4-14 Adjusting scroll bars and content region when resizing a window 4-59
Listing 4-15 Converting a window region to local coordinates 4-60
Listing 4-16 Handling a close command 4-60
Listing 4-17 Closing a document 4-61
Figure 4-22 The cumulative effects of HideWindow, ShowWindow, and SelectWindow 4-63
Listing 4-18 Showing a hidden dialog box 4-64
Figure 4-23 Limiting rectangle used by DragGrayRgn 4-98
Figure 4-24 Structure of a compiled window ('WIND') resource 4-124
Figure 4-25 Structure of a compiled window color table ('wctb') resource 4-128
Figure 5-1 Standard controls provided by the Control Manager 5-4
Figure 5-2 A default button 5-5
Figure 5-3 A selected checkbox 5-5
Figure 5-4 A vertical scroll bar 5-7
Figure 5-5 Using the scroll box and scroll arrows 5-8
Figure 5-6 Spatial relations between a document and a window, and their representation by a scroll bar 5-10
Figure 5-7 Custom slider controls 5-11
Figure 5-8 Visual feedback for user selection of active controls 5-12
Figure 5-9 Inactive controls 5-13
Figure 5-10 A button in a simple window 5-17
Listing 5-1 Creating a button for a window 5-17
Listing 5-2 Rez input for a control resource 5-18
Figure 5-11 Radio buttons in a simple window 5-20
Listing 5-3 Rez input for the control resources of radio buttons 5-21
Figure 5-12 How a scroll bar should overlap the window frame 5-22
Listing 5-4 Rez input for resources for a window and its scroll bars 5-23
Listing 5-5 Creating a document window with scroll bars 5-24
Figure 5-13 A pop-up menu 5-26
Listing 5-6 Rez input for the control resource of a pop-up menu 5-26
Figure 5-14 Dimensions of a sample pop-up menu 5-26
Listing 5-7 Responding to an update event for a window 5-29
Listing 5-8 Redrawing the controls in the update region 5-30
Listing 5-9 Detecting mouse-down events in a window 5-32
Listing 5-10 Detecting mouse-down events in a pop-up menu and a button 5-33
Figure 5-15 Three controls in a window 5-34
Listing 5-11 Using the TrackControl function with a button 5-36
Listing 5-12 Using TrackControl with a pop-up menu 5-37
Listing 5-13 Responding to a click in a checkbox 5-38
Listing 5-14 Adjusting scroll bar settings and locations 5-39
Listing 5-15 Assigning settings to scroll bars 5-40
Listing 5-16 Adjusting the maximum and current settings for a scroll bar 5-41
Figure 5-16 Moving a document relative to its window 5-46
Listing 5-17 Using ScrollRect to scroll the bits displayed in the window 5-47
Figure 5-17 Updating the contents of a scrolled window 5-49
Figure 5-18 Restoring the window origin to (0,0) 5-50
Figure 5-19 Scrolling to the end of a document 5-51
Figure 5-20 Updating a window's contents and returning the window origin to (0,0) 5-51
Listing 5-18 Responding to mouse events in a scroll bar 5-53
Listing 5-19 Action procedures for scrolling through a text document 5-59
Listing 5-20 Moving the scroll box from the action procedures 5-61
Listing 5-21 An application-defined update routine 5-62
Listing 5-22 Redrawing a window containing graphics objects 5-63
Listing 5-23 Redrawing a window after scrolling a TextEdit edit record 5-65
Figure 5-21 Moving and resizing scroll bars 5-66
Listing 5-24 Changing the size and location of a window's scroll bars 5-67
Figure 5-22 A vertical scroll bar before the application moves it within a resized window 5-69
Figure 5-23 A vertical scroll bar after the application moves its upper-left point 5-69
Figure 5-24 A custom control 5-71
Table 5-1 Mapping between new and previous names of Control Manager routines 5-80
Figure 5-25 Structure of a compiled control ('CNTL') resource 5-118
Figure 5-26 Structure of a compiled control color table ('cctb') resource 5-122
Figure 6-1 An alert box used by the Finder 6-6
Figure 6-2 A typical dialog box 6-7
Figure 6-3 A note alert 6-8
Figure 6-4 A caution alert 6-9
Figure 6-5 A stop alert 6-9
Figure 6-6 A modal dialog box 6-10
Figure 6-7 A movable modal dialog box 6-11
Figure 6-8 A modeless dialog box 6-12
Figure 6-9 Typical items in a dialog box 6-13
Figure 6-10 An alert box to save changes to a document 6-19
Listing 6-1 Rez input for an alert resource 6-19
Figure 6-11 An alert box displayed only during the third and fourth alert stages 6-21
Listing 6-2 Specifying different alert responses according to alert stage 6-21
Listing 6-3 Creating your own sound procedure for alerts 6-22
Figure 6-12 A simple modal dialog box 6-24
Listing 6-4 Rez input for a dialog resource 6-24
Figure 6-13 Relationship of various resources to an alert box 6-27
Listing 6-5 Rez input for providing an alert box with items 6-27
Figure 6-14 A safe default button in an alert box 6-31
Figure 6-15 The consistent spacing of buttons and text in an alert box 6-33
Listing 6-6 Rez input for consistent spacing of display rectangles 6-34
Figure 6-16 Incorrectly and correctly sized display rectangles for alternate script systems 6-35
Figure 6-17 Inactive controls and disabled items 6-37
Figure 6-18 A dialog box with OK and Cancel buttons 6-38
Figure 6-19 A movable modal dialog box with a Stop button 6-39
Figure 6-20 An alert box with a Revert button 6-39
Figure 6-21 An obscure and useless alert message 6-41
Figure 6-22 A less obscure alert message 6-41
Figure 6-23 A clear and helpful alert message 6-41
Figure 6-24 A pop-up menu in a dialog box 6-42
Listing 6-7 Rez input for a dialog resource and an item list resource for a dialog box that includes a pop-up menu 6-43
Listing 6-8 Rez input for a control resource and a menu resource for a pop-up menu 6-43
Figure 6-25 A selected scrolling list 6-45
Figure 6-26 An alert box that displays a document name 6-46
Listing 6-9 Using the ParamText procedure to substitute text strings 6-47
Listing 6-10 Specifying where ParamText should substitute text in an alert box message 6-48
Figure 6-27 Two editable text items in a modeless dialog box 6-48
Listing 6-11 Specifying editable text items in an item list 6-49
Listing 6-12 Getting the text entered by the user in an editable text item 6-49
Figure 6-28 An existing dialog box and items to append 6-51
Figure 6-29 The dialog box after items are overlaid 6-52
Figure 6-30 The dialog box after items are appended to the right 6-52
Figure 6-31 The dialog box after items are appended to the bottom 6-53
Figure 6-32 A dialog box with an item appended relative to an existing item 6-53
Listing 6-13 Appending an item to an existing dialog box 6-54
Listing 6-14 Rez input for a dialog box and the item appended to it 6-55
Listing 6-15 Rez input for an application-defined item in an item list 6-57
Listing 6-16 Installing the draw procedure for an application-defined item 6-58
Listing 6-17 Creating a draw procedure that draws a bold outline around the default button 6-59
Figure 6-33 An alert box in front of a document window 6-63
Figure 6-34 An alert box on the main screen 6-63
Figure 6-35 An alert box in the alert position of the document window screen 6-64
Listing 6-18 Deactivating the front window before displaying an alert box 6-65
Figure 6-36 An alert box displayed only after the third alert stage 6-65
Listing 6-19 Using GetAlertStage to determine when to deactivate the front window 6-66
Figure 6-37 A modeless dialog box for changing text in a document 6-66
Listing 6-20 Ensuring that the modeless dialog box isn't already open before creating it 6-67
Figure 6-38 Menu access when displaying a modal dialog box 6-69
Listing 6-21 Adjusting menus for various windows 6-70
Listing 6-22 Disabling menus for a modal dialog box with editable text items 6-70
Listing 6-23 Adjusting the Edit menu for a modal dialog box 6-72
Listing 6-24 Rez input for a dialog color table resource using the system's default colors 6-75
Listing 6-25 Using DialogSelect during null events 6-79
Figure 6-39 Three buttons for which CautionAlert reports events 6-81
Figure 6-40 Four items for which ModalDialog reports events 6-83
Listing 6-26 Responding to events in a modal dialog box 6-83
Listing 6-27 A typical event filter function for alert and modal dialog boxes 6-88
Figure 6-41 A modeless dialog box for which DialogSelect reports events 6-91
Listing 6-28 Handling mouse-down events for all windows 6-91
Listing 6-29 Using the DialogSelect function for responding to mouse-down events 6-92
Listing 6-30 Hiding a modeless dialog box in response to a Close command 6-94
Listing 6-31 Checking for key-down events involving the Command key 6-95
Listing 6-32 Checking for key-down events in a modeless dialog box 6-95
Listing 6-33 Responding to key-down events in a modeless dialog box 6-96
Listing 6-34 Activating a modeless dialog box 6-98
Listing 6-35 Updating a modeless dialog box 6-99
Table 6-1 Mapping between new and previous names of Dialog Manager routines 6-102
Figure 6-42 Structure of a compiled dialog ('DLOG') resource 6-148
Figure 6-43 Structure of a compiled alert ('ALRT') resource 6-150
Figure 6-44 Structure of a compiled item list ('DITL') resource 6-152
Figure 6-45 Structure of compiled button, checkbox, radio button, static text, and editable
text items 6-153Figure 6-46 Structure of compiled control, icon, and picture items 6-154
Figure 6-47 Structure of a compiled application-defined item 6-155
Figure 6-48 Structure of compiled help items 6-155
Figure 6-49 Structure of a compiled item color table resource 6-159
Figure 6-50 Structure of a compiled control color table 6-161
Figure 6-51 Structure of a compiled text style table 6-162
Chapter 7 Finder Interface 7-1
Figure 7-1 Application and document icons in a window on the desktop 7-4
Figure 7-2 A customized help balloon for an application icon 7-5
Figure 7-3 A Finder message identifying a missing application 7-5
Listing 7-1 Rez input for a signature resource 7-8
Figure 7-4 Large black-and-white application icons for a company's product line 7-12
Figure 7-5 Default large black-and-white icons 7-12
Figure 7-6 A black-and-white icon and its mask for an application 7-13
Figure 7-7 The ResEdit view of an icon 7-14
Listing 7-2 Rez input for an icon list resource 7-14
Listing 7-3 Rez input for file reference resources 7-19
Listing 7-4 Rez input for a bundle resource 7-21
Figure 7-8 Linking icon list resources and file reference resources in a bundle resource 7-23
Figure 7-9 The default application-unavailable alert box 7-27
Listing 7-5 Rez input for a missing-application name string resource 7-28
Listing 7-6 Storing a missing-application name string resource in the resource fork of
a document 7-28Listing 7-7 Copying the missing-application name string resource into the resource fork of
a document 7-29Figure 7-10 The application-unavailable alert box specifying an application's name 7-29
Listing 7-8 Rez input for an application-missing message string resource 7-30
Figure 7-11 The application-unavailable alert box with a customized message 7-30
Figure 7-12 The application-unavailable alert box for 'TEXT' and 'PICT' documents 7-30
Listing 7-9 Rez input for a pair of version resources 7-32
Figure 7-13 The version data in the information window 7-33
Listing 7-10 Rez input for a size resource 7-35
Listing 7-11 Determining whether a document is a stationery pad 7-36
Figure 7-14 Default and customized help balloons for application icons 7-38
Listing 7-12 Rez input for a help balloon resource for an application icon 7-39
Listing 7-13 Using the ResolveAliasFile function to open a file 7-41
Figure 7-15 The System Folder and related folders 7-42
Figure 7-16 Structure of a signature resource compiled as a string ('STR ') resource 7-57
Figure 7-17 Structure of a compiled icon list ('ICN#') resource 7-58
Figure 7-18 Structure of a compiled small icon list ('ics#') resource 7-59
Figure 7-19 Structure of a compiled large 4-bit color icon ('icl4') resource 7-60
Figure 7-20 Structure of a compiled small 4-bit color icon ('ics4') resource 7-61
Figure 7-21 Structure of a compiled large 8-bit color icon ('icl8') resource 7-62
Figure 7-22 Structure of a compiled small 8-bit color icon ('ics8') resource 7-63
Figure 7-23 Structure of a compiled icon ('ICON') resource 7-64
Figure 7-24 Structure of a compiled file reference ('FREF') resource 7-65
Figure 7-25 Structure of a compiled bundle ('BNDL') resource 7-66
Figure 7-26 Mapping local IDs to icon list resource IDs in a bundle resource 7-67
Figure 7-27 Structure of superfluous local ID mapping for file reference resources in a
bundle resource 7-67Figure 7-28 Structure of a compiled missing-application name string resource 7-68
Figure 7-29 Structure of a compiled application-missing message string resource 7-69
Figure 7-30 Format of a compiled version ('vers') resource 7-70