Inside Macintosh: QuickDraw GX Environment and Utilities /

Figures, Tables, and Listings

Preface About This Book xix

Figure P-1 Roadmap to the QuickDraw GX suite of books xx

Chapter 1 QuickDraw GX and the Macintosh Environment 1-1

Listing 1-1 Determining the presence and features of QuickDraw GX 1-5

Figure 1-1 Converting from QuickDraw global to QuickDraw GX local and global coordinates 1-8

Table 1-1 Translation scaling factors 1-11

Table 1-2 Translation options settings 1-12

Listing 1-2 QuickDraw commands to draw a simple line 1-14

Figure 1-2 A QuickDraw line 1-14

Figure 1-3 Translation of the QuickDraw line using gxDefaultOptionsTranslation 1-15

Figure 1-4 Translation of the QuickDraw line using gxSimpleGeometryTranslation 1-15

Figure 1-5 Translation of the QuickDraw line using gxReplaceLineWidthTranslation 1-16

Figure 1-6 Conversion of standard QuickDraw fill patterns to QuickDraw GX shape fills 1-17

Listing 1-3 QuickDraw picture data that includes a picComment 1-18

Figure 1-7 Translating QuickDraw data containing a rotation picComment 1-19

Listing 1-4 Translating QuickDraw picture data with GXConvertPICTToShape 1-20

Table 1-3 Translation statistics options 1-20

Listing 1-5 Installing and removing the translator 1-21

Listing 1-6 Sample application-defined shape-spooling function 1-22

Chapter 2 QuickDraw GX Memory Management 2-1

Listing 2-1 Creating a 'gasz' resource 2-6

Listing 2-2 Explicitly creating a graphics client and its heap 2-7

Listing 2-3 Disposing of graphics clients and graphics client heaps 2-10

Table 2-1 QuickDraw GX functions that do not require a graphics client or heap 2-14

Listing 2-4 Specifying the starting location and size for a graphics client and its heap 2-15

Figure 2-1 Creating a graphics client by specifying the memory starting location 2-16

Chapter 3 Errors, Warnings, and Notices 3-1

Figure 3-1 QuickDraw GX and application-defined error, warning, and notice management 3-4

Table 3-1 Non-debugging error number ranges 3-6

Table 3-2 Fatal errors 3-7

Table 3-3 Internal errors 3-7

Table 3-4 Recoverable errors 3-7

Table 3-5 Font management errors 3-8

Table 3-6 Font scaler errors 3-8

Table 3-7 Bad parameter errors 3-9

Table 3-8 Implementation limit errors 3-10

Table 3-9 Non-debugging warning number ranges 3-10

Table 3-10 Stack, heap, and object warnings 3-11

Table 3-11 Result out of range warnings 3-11

Table 3-12 Parameter out of range warnings 3-12

Table 3-13 Font scaler warnings 3-12

Table 3-14 Unexpected result warnings 3-13

Table 3-15 Storage warnings 3-13

Table 3-16 Debugging error number range 3-14

Table 3-17 Internal debugging errors 3-14

Table 3-18 Font parameter debugging errors 3-14

Table 3-19 Bad parameter debugging errors 3-15

Table 3-20 Restricted access debugging errors 3-16

Table 3-21 Wrong type and bad reference debugging errors 3-17

Table 3-22 Type validation debugging errors 3-18

Table 3-23 Cache validation debugging errors 3-18

Table 3-24 Shape cache validation shape debugging errors 3-19

Table 3-25 Memory block validation debugging errors 3-19

Table 3-26 Object validation debugging errors 3-20

Table 3-27 Path and polygon validation debugging errors 3-20

Table 3-28 Bitmap validation debugging errors 3-20

Table 3-29 Bitmap image validation debugging errors 3-21

Table 3-30 Text validation debugging errors 3-21

Table 3-31 Glyph validation debugging errors 3-21

Table 3-32 Layout validation debugging errors 3-22

Table 3-33 Picture validation debugging errors 3-22

Table 3-34 Text face validation debugging errors 3-22

Table 3-35 Transform validation debugging errors 3-23

Table 3-36 Font cache validation debugging errors 3-23

Table 3-37 View device validation debugging errors 3-24

Table 3-38 Color set validation debugging errors 3-24

Table 3-39 Color profile validation debugging errors 3-24

Table 3-40 Internal backing store validation debugging errors 3-25

Table 3-41 Debugging warning number range 3-25

Table 3-42 Invalid data debugging warnings 3-26

Table 3-43 Can't find debugging warnings 3-26

Table 3-44 Other debugging warnings 3-27

Table 3-45 Debugging version notice number summary 3-27

Table 3-46 Debugging notices 3-27

Figure 3-2 Polling for errors, warnings, and notices 3-31

Figure 3-3 Obtaining the first and last posted QuickDraw GX error 3-32

Listing 3-1 Obtaining the first posted error 3-33

Listing 3-2 Obtaining the first and last QuickDraw GX warning 3-34

Listing 3-3 Obtaining the first and last posted notices 3-34

Listing 3-4 Changing the error posted 3-36

Figure 3-4 Adding and removing warnings and notices from the ignore warning and ignore notice stacks 3-39

Figure 3-5 Enabling and disabling an error handler 3-41

Chapter 4 QuickDraw GX Debugging 4-1

Figure 4-1 The QuickDraw GX debugging environment 4-4

Table 4-1 QuickDraw GX drawing process sequence 4-9

Table 4-2 Shape type drawing errors 4-10

Table 4-3 Style drawing errors 4-11

Table 4-4 Ink drawing errors 4-12

Table 4-5 Transform drawing errors 4-13

Table 4-6 View port drawing errors 4-14

Table 4-7 View device drawing errors 4-15

Table 4-8 Validation modes 4-16

Table 4-9 Validation levels 4-16

Table 4-10 Memory validation options 4-19

Listing 4-1 Determining the function and parameter that caused the last validation error 4-22

Table 4-11 GraphicsBug commands and responses 4-23

Listing 4-2 Totaling the graphics client and its heap 4-25

Listing 4-3 Determining the memory locations of the shapes in the picture 4-26

Listing 4-4 Analyzing the rectangle shape in the picture 4-27

Listing 4-5 Analyzing the ink in the rectangle shape 4-28

Chapter 5 Collection Manager 5-1

Figure 5-1 The collection object 5-7

Figure 5-2 The collection item 5-8

Figure 5-3 Editing attributes in a collection item 5-10

Figure 5-4 Items in a collection 5-12

Listing 5-1 Determining whether the Collection Manager is available 5-13

Listing 5-2 Changing the default attributes of a collection 5-16

Listing 5-3 Adding items to a collection 5-17

Listing 5-4 Adding items with variable-length data to a collection 5-18

Listing 5-5 Determining the index of an item 5-20

Listing 5-6 Determining the tag and ID of an item given the item's index 5-21

Listing 5-7 Determining the size of an item's variable-length data 5-23

Listing 5-8 Examining the attributes of an item 5-25

Listing 5-9 Setting the lock and persistence bit attribute of an item 5-26

Listing 5-10 Replacing an item in a collection 5-28

Listing 5-11 Replacing an item using the item's index 5-29

Listing 5-12 Removing an item in a collection 5-30

Listing 5-13 Removing an item using the item's index 5-31

Listing 5-14 Removing multiple items with specific attributes 5-31

Listing 5-15 Retrieving the variable-length data from an item 5-33

Listing 5-16 Retrieving the variable-length data from an item using the item's index 5-34

Listing 5-17 Retrieving the variable-length data from an item using the tag and tag list position 5-35

Listing 5-18 Counting tags in a collection 5-36

Listing 5-19 Flattening procedure 5-38

Listing 5-20 The FlattenCollectionToHdl function 5-39

Listing 5-21 A possible implementation of the UnflattenCollectionFromHdl function 5-40

Listing 5-22 Flattening a collection to a disk file as a resource 5-42

Listing 5-23 Flattening a collection to a data fork of a disk file 5-42

Listing 5-24 Unflattening a collection from a disk file as a resource 5-43

Listing 5-25 Unflattening a collection from the data fork of a disk file 5-43

Listing 5-26 Reading a collection from a collection resource 5-44

Listing 5-27 A sample exception procedure 5-46

Listing 5-28 A Rez template for a 'cltn' resource 5-102

Chapter 6 Message Manager 6-1

Figure 6-1 Printing with the Macintosh Printing Manager 6-4

Figure 6-2 Printing with QuickDraw GX 6-5

Listing 6-1 Creating an A5 world for global data 6-9

Listing 6-2 Disposing of global data and deallocating memory 6-10

Listing 6-3 Storing global data for a single message handler instance 6-11

Listing 6-4 Getting and disposing of global data 6-12

Listing 6-5 Storing global data for multiple handler instances 6-13

Listing 6-6 Retrieving a message handler's class context 6-14

Chapter 7 QuickDraw GX Stream Format 7-1

Figure 7-1 A typical flattened shape data stream sequence 7-8

Figure 7-2 Basic components of a stream header or object 7-9

Figure 7-3 The format of the operation opcode byte 7-10

Table 7-1 Operation opcodes 7-10

Figure 7-4 Data format of the record size 7-12

Figure 7-5 The format of the data type opcode byte 7-13

Table 7-2 Compression values 7-13

Figure 7-6 Relationship of stream format components 7-14

Table 7-3 Data type opcodes for a new object 7-15

Table 7-4 Data type opcodes to modify a shape object 7-17

Table 7-5 Data type opcodes to modify a style object 7-18

Table 7-6 Data type opcodes to modify an ink object 7-20

Table 7-7 Data type opcodes to modify a color set object 7-20

Table 7-8 Data type opcodes to modify a color profile object 7-21

Table 7-9 Data type opcodes to modify a transform object 7-21

Figure 7-7 Omit byte relationship with the data that follows 7-23

Figure 7-8 Select the bits from the omit byte 7-24

Table 7-10 Constants from the gxOmitTextMask and the gxOmitTextShift enumerations 7-24

Figure 7-9 Compare the bits selected and shifted with the compression enumeration 7-25

Table 7-11 Correlation between gxOmitTextMask and the GXNewText function 7-26

Listing 7-1 Determining if position(x) is byte compressed 7-27

Figure 7-10 Mapping matrix elements 7-40

Table 7-12 Color space and words read 7-44

Table 7-13 Bit image compression opcodes 7-50

Figure 7-11 Print file format 7-52

Listing 7-2 A GraphicsBug annotation of the data stream of a flattened shape 7-55

Listing 7-3 A picture with seven shapes 7-56

Figure 7-12 A picture with seven shapes 7-59

Figure 7-13 The line shape drawn 7-60

Listing 7-4 GraphicsBug analysis of a flattened line 7-60

Table 7-14 Analysis of the data stream of a flattened line shape 7-61

Figure 7-14 The rectangle shape drawn 7-64

Listing 7-5 GraphicsBug analysis of a flattened rectangle shape 7-64

Table 7-15 Analysis of the data stream of a flattened rectangle shape 7-65

Figure 7-15 The curve shape drawn 7-67

Listing 7-6 GraphicsBug analysis of a flattened curve shape 7-67

Table 7-16 Analysis of the data stream of a flattened curve shape 7-68

Figure 7-16 The path shape drawn 7-69

Listing 7-7 GraphicsBug analysis of a flattened path shape 7-69

Table 7-17 Analysis of the data stream of a flattened path shape 7-70

Figure 7-17 The text shape drawn 7-72

Listing 7-8 GraphicsBug analysis of a flattened text shape 7-73

Table 7-18 Analysis of the data stream of a flattened text shape 7-74

Figure 7-18 The polygon shape drawn 7-79

Listing 7-9 GraphicsBug analysis of a flattened polygon shape 7-79

Table 7-19 Analysis of the data stream of a flattened polygon shape 7-80

Figure 7-19 The bitmap shape drawn 7-81

Listing 7-10 GraphicsBug analysis of a flattened bitmap shape 7-82

Table 7-20 Analysis of the data stream of a bitmap shape 7-83

Listing 7-11 Obtaining the page count from a portable digital document print file 7-89

Chapter 8 QuickDraw GX Mathematics 8-1

Table 8-1 Macro number-format conversions 8-8

Figure 8-1 Cartesian and polar coordinates 8-11

Figure 8-2 Transformation operations with a mapping matrix 8-14

Figure 8-3 Mapping matrix elements 8-15

Figure 8-4 Applying a mapping matrix to a point 8-15

Figure 8-5 The point (x, y) as transformed by the mapping matrix 8-16

Figure 8-6 The identity matrix 8-17

Figure 8-7 Changing the translation specified by a mapping 8-17

Figure 8-8 Translation by a relative amount with MoveMapping 8-18

Figure 8-9 Setting the origin specified by a mapping 8-19

Figure 8-10 Translation to a specific origin location 8-19

Figure 8-11 Changing the amount of scaling specified by a mapping 8-20

Figure 8-12 Scaling horizontally and vertically 8-21

Figure 8-13 Changing the degree of rotation specified by a mapping 8-22

Figure 8-14 Rotating about different center points 8-23

Figure 8-15 Changing the amount of skew specified by a mapping 8-24

Figure 8-16 Skewing a shape both horizontally and vertically 8-25

Figure 8-17 Changing the perspective specified by a mapping 8-26

Table 8-2 QuickDraw GX and Macintosh Toolbox fixed-point functions 8-27

Figure 8-18 Determining the length of a line with the Magnitude function 8-28

Figure 8-19 Converting between Cartesian and polar coordinates 8-29

Listing 8-1 Calculating a cross-product with VectorMultiply 8-30

Listing 8-2 Applying a mapping to one point 8-30

Listing 8-3 Using the WideShift function to create a fixed-point VectorMultiply function 8-31

Listing 8-4 Using the WideShift function in a fixed-point multiplication function 8-31

Listing 8-5 Using the WideShift function to create a fixed-point division function 8-31

Listing 8-6 Using the WideShift function to create a second fixed-point division function 8-32

Listing 8-7 Using the WideScale function to create a pseudo-floating-point function 8-32

Listing 8-8 A random number generator 8-33

Listing 8-9 Determining the lowest bit of a number 8-34

Table 8-3 FixedMultiply product bias 8-43

Table 8-4 FixedDivide quotient bias 8-44

Table 8-5 FractMultiply result bias 8-48

Table 8-6 FractDivide result bias 8-49