Previous Book Contents Book Index Next

Inside Macintosh: Macintosh Toolbox Essentials /

Figures, Tables, and Listings

Color Plates

Color 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

Chapter 2 Event Manager 2-1

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

Chapter 3 Menu Manager 3-1

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

Chapter 4 Window Manager 4-1

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-49

Listing 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

Chapter 5 Control Manager 5-1

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

Chapter 6 Dialog Manager 6-1

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-153

Figure 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-28

Listing 7-7 Copying the missing-application name string resource into the resource fork of
a document 7-29

Figure 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-67

Figure 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

Previous Book Contents Book Index Next

© Apple Computer, Inc.
11 JUL 1996