Inside Macintosh: QuickDraw GX Environment and Utilities /

Glossary

all object validation A QuickDraw GX validation level that confirms that all references to all object types are valid, that the properties of the object are valid, and that all internal caches built for all objects are valid. Compare type validation and structure validation.

application heap A region of memory that is allocated by the Macintosh Memory Manager when an application is launched. This is the memory region reserved for application code and data structures.

attribute mask A means of editing the attributes of a collection object.

attributes A property of many QuickDraw GX objects that is a set of flags that control various aspects of that object's behavior.

bad parameter error A nonfatal QuickDraw GX error indicating that one or more function parameters are incorrect.

bad reference error A QuickDraw GX error indicating that an invalid reference to a view or font device, view group, or view port was made.

bias The number of bits to the right of a binary point in a fixed point number. See also gxColorValue, Fixed, fixed-point number, fract, long, and short.

bitmap (1) A QuickDraw GX data structure that describes a pixel map on a physical device. A bitmap structure is a property of a view device object. (2) A type of QuickDraw GX shape.

cache See QuickDraw GX cache.

cache error A QuickDraw GX error indicating that a memory cache problem occurred.

Cartesian coordinate A coordinate system used for view devices in which the positive x direction is to the right and the positive y direction is down with respect to the origin, at the upper-left corner. A point is defined by specifying the x- and y-coordinates in the format (x, y). Compare polar coordinate.

child view port For a given view port, a view port immediately below it in the view port hierarchy.

child view port list A property of a view port object that is an array of references to the child view ports of that view port.

clip A QuickDraw GX shape and a property of a transform object, view port object, and view device.

collection An abstract data type that allows you to store information. Unlike an array, a collection allows you to store variable-sized items.

collection index A means of uniquely identifying each item within a collection.

collection item A part of a collection object.

collection object See collection.

concatenate An operation consisting of two or more sequential mappings.

data stream A highly structured sequence of bytes that contains all of the information required to store, print, or display QuickDraw GX objects.

dead cache A shape cache that is out of date. The object or environment associated with the cache has been changed since the cache was created.

debugging environment The QuickDraw GX application development environment consisting of the debugging version; errors, warnings, and notices; application-defined message handlers; the drawing errors; validation function; and the MacsBug and GraphicsBug utilities. See also error, warning, notice, and message handler.

debugging version The version of QuickDraw GX that provides validation and an extended set of errors, warnings, and notices. This version is intended for use during application development. See also non-debugging version, error, warning, and notice.

default attributes The attributes that determines the initial attribute values assigned to items added to a collection.

default memory size The implementation limit size of the graphic client memory heap that QuickDraw GX will select if the memory size is not specified.

default object A QuickDraw GX object with the properties of a newly created object. Whenever it creates an object, QuickDraw GX assigns it the default properties for that kind of object; an application may then alter those properties through accessor functions.

discontiguous memory One or more non-continuous blocks of memory. For example, a graphics client heaps might be discontiguous.

dispose of To delete a reference to an object. When an application no longer needs an object, it disposes of the object. That action deletes the object from memory if there are no other current references to the object; otherwise, disposing of an object merely decreases its owner count by 1.

drawing error A QuickDraw GX error indicating why your shape did not draw successfully. The GXGetShapeDrawError function posts such a single error.

drawing process sequence The sequence in which QuickDraw processes objects: shape, style, ink, transform, view port, and view device.

error A single descriptive phrase that is posted by QuickDraw GX whenever an application is unable to execute. Execution is terminated at the nonexecutable function. Each error message is assigned a unique number in the range -27999 through -27000. Errors are posted in both the debugging and non-debugging versions of QuickDraw GX.

Fixed number A 32-bit signed integer with 16 bits to the left and 16 bits to the right of the binary decimal point. A fixed-point number with a bias of 16. Fixed numbers range from -32,768 to nearly +32,768. The fixed number for 1.0 is 0x0001000.

fixed-point number A signed 16-bit, 32-bit, or 64-bit quantity containing an integer part in the high-order word and a fractional part in the low- order word. Integers are interpreted as real numbers by the use of bias to define where the decimal point is located. Numbers having the gxColorValue, short, long, fixed, fract, and wide number formats are fixed point numbers. See also bias, long number, fract number, short number, gxColorValue and wide number.

flatten To convert an object created by your application from its original format to a QuickDraw GX stream format.

font management error A QuickDraw GX error that involves the storage, attributes, or parameter of a font.

font scaler error A QuickDraw GX error that involves the conversion of a glyph outline to a bitmap.

font scaler warning A QuickDraw GX warning that involves the conversion of a glyph outline to a bitmap.

forward To invoke the override of the next handler in the chain for the current message.

fract number A 32-bit signed integer with two bits to the left and 30 bits to the right of the binary decimal point. A fixed-point number with a bias of 2. Fract numbers range from -2 to +2. The fract number for 1.0 is 0x40000000.

geometry A property of a QuickDraw GX shape object. A shape's geometry is the specification of the actual size, position, and fill of the shape. For example, for a rectangle shape, the geometry specifies the locations of the rectangle's corners in local coordinates.

global coordinates For QuickDraw GX, the coordinate system used for a view group. For example, a view port's location is described in global coordinates. This coordinate system represents all potential drawing space. The origin, point (0,0), of the global coordinate system is located at the upper-left corner of the main screen. The positive x-axis extends to the right. The positive y-axis extends downward.

GraphicsBug A QuickDraw GX debugging utility that allows detailed analysis of heaps and objects. See also heaps and objects.

graphics client A region of memory where bookkeeping data is stored for a graphics client heap. This includes the memory starting address, the size and location of all of the heap's memory blocks, and the error, warning, and notice state. See also graphics client heap.

graphics client heap A region of memory that contains all of the objects that a QuickDraw GX application creates. A heap that consists of public objects, such as shapes, styles, inks, and transforms, as well as private objects used for heap management. See also graphics client and heap.

graphics device Any graphics hardware attached to the system.

gxColorValue A 16-bit unsigned integer. A fixed-point number that ranges from 0 to 65,535 to represent the numbers 0 to 1. The integer must be divided by 65,535 to obtain the real number represented. The color value number for 1.0 is 0xFFFF.

handler A recipient and processor of messages. It can be a printing extension, a printer driver, QuickDraw GX printing, or an application. For example, an application can supply a handler for errors, warnings, and messages. See also message chain.

heap An area of memory that is dynamically allocated and deallocated on demand. See also application heap and graphics client heap.

hit-testing The conversion of a specific geometric location, such as a pixel position in a view port, to logical location (part, control point, or glyph) in the geometry of a shape object. Hit-testing is used to highlight or activate parts of geometric shapes or to highlight or draw a caret within the displayed text of a typographic shape.

identity matrix A mapping matrix that maps a point to the same point. A mapping matrix with the value 1 for the diagonal matrix elements and the value 0 for all other matrix elements.

ignore notice stack A stack that can contain the implementation limit of notice numbers. Notices on the ignore notice stack are not posted by QuickDraw GX.

ignore warning stack A stack that can contain the implementation limit of warning numbers. Warnings on the ignore warning stack are not posted by QuickDraw GX.

implementation limit error A QuickDraw GX error indicating that the implementation limit of a structure has been exceeded. See also implementation limit.

implementation limit An upper or lower bounds of a size, number, or value. This limit is defined by the current version of QuickDraw GX. See also default memory size.

instance A single copy of a message handler in memory. See also instantiate.

instantiate To create an instance of a message handler separate and unique from all other instances. See also instance.

ink A QuickDraw GX object associated with a shape object. An ink object contains information that affects the color of a shape and the transfer mode with which it is drawn.

internal error A nonfatal QuickDraw GX error indicating a damaged file, memory problem, or incorrect implementation.

internal validation An optional validation mode in which object parameter validation occurs whenever an application uses a public function and whenever QuickDraw GX uses an internal function. Compare public validation.

interrupt programming A type of programming in which QuickDraw GX allows an application to switch tasks, but only when it is not performing critical functions.

invalid data warning A QuickDraw GX warning indicating that an object contains incorrect data or that extra data was passed.

inverse of a mapping The mathematical inverse of the mapping matrix. A mapping concatenated with its inverse results in the identity matrix.

live cache A QuickDraw GX cache that contains current information. The object associated with the cache has not been changed since the cache was created. See also dead cache.

load [an object] To return an unloaded QuickDraw GX object from external storage to memory. QuickDraw GX automatically and transparently loads and unloads objects in the course of managing memory; an application need never know whether an object it accesses is currently loaded or unloaded.

local coordinates For QuickDraw GX, the coordinate space local to each shape. For example, a shape's geometry is described in local coordinates.

lock attribute When set, this attribute prevents an item in a collection from being replaced.

long number A 32-bit signed integer. A fixed- point number with a bias of 0. Long numbers range from -2,147,483,648 to +2,147,483,647. The long number for 1.0 is 0x00000001.

Macintosh interface functions A set of Macintosh-specific functions. Most other QuickDraw GX functions can exist on any platform.

macro A sequence of predefined directives that the C preprocessor interprets at compile time. When the preprocessor encounters the macro name in the source code, the preprocessor substitutes the macro definition for it. QuickDraw GX provides macros for number format conversions.

MacsBug A Macintosh debugging utility.

map See mapping.

mapping A transformation of spatial locations (points) that can be represented by a 3 3 perspective matrix. Synonymous with map and mapping matrix.

mapping matrix See mapping.

memory allocation Specification of the starting address of the graphics client in memory.

memory block An area of contiguous memory within a heap or zone.

memory size The number of bytes of random access memory allocated to the QuickDraw GX graphics client. The default size is 600 KB.

message A notification passed to a message object so that the message object will perform an operation.

message chain One or more handlers that wish to receive and respond to messages. A handler at the top of a message chain always receives a message first. See also message handler.

message class The set of messages and methods defined at run time that are understood by message objects.

message handler A component of a message class that can override messages.

Message Manager A low-level software manager that is part of the QuickDraw GX message-passing printing architecture.

message object The recipient and sender of messages.

message override See override.

non-debugging environment The QuickDraw GX end-user environment consisting of the non-debugging version, errors and warnings, and application-defined message handlers. See also error, warning, and message handler.

non-debugging version The version of QuickDraw GX that provides a limited set of errors and warnings. This version is intended for use with a debugged application. See also debugging version, error, and warning.

normalize To divide a mapping matrix by the absolute value of matrix element w. A mapping is considered normalized whenever the matrix element w has the value 1.

notice A single descriptive phrase that is posted by the debugging version of QuickDraw GX whenever an unnecessary or redundant function has been performed. Execution continues as if the notice had not been posted. Notices are posted only in the debugging version of QuickDraw GX. A notice number is a unique number in the range -25999 through -25500 assigned to each QuickDraw GX notice message. Each notice number has a unique notice name. See also notice name.

notice name A multiple-word phrase that describes the QuickDraw GX notice posted. Each notice name has a unique notice number. See also notice.

notice number See notice.

object A private QuickDraw GX data structure. An object is defined by properties and is accessed by a reference.

omit byte A means of assigning different data compressions to type constants and object properties that immediately follow this byte.

omit byte mask With the omit byte shift, this is a means of interpreting the meaning of each of the bits in an omit byte.

omit byte shift With the omit byte mask, this is a means of interpreting the meaning of each of the bits in an omit byte.

overflow notice A QuickDraw GX notice indicating that a notice could not be added to the ignore notice stack because the implementation limit had been exceeded. See also implementation limit.

overflow warning A QuickDraw GX warning indicating that a warning could not be added to the ignore warning stack because the implementation limit had been exceeded. See also implementation limit.

override A message handler's implementation of a given message. A message handler's override performs the operation requested by the message received by the message object. A partial override forwards the message. A complete override does not forward the message.

owner A variable, structure, or QuickDraw GX object that references an object. Many objects can be referenced by more than one variable and can thus have multiple owners.

owner count A property of some QuickDraw GX objects that indicates the number of current references to the object.

parameter out of range warning A QuickDraw GX warning indicating that a function parameter is out of the valid range.

parent view port A property of a view port object. A view port's parent is that view port immediately above it in the view port hierarchy.

persistence attribute An attribute that causes an item to be included when the Collection Manager flattens a collection. See flatten.

polar coordinate A coordinate system in which a point is specified by the length of the radius vector r from the origin to the point and the direction of the vector is specified by the polar angle a. A point is defined by specifying the coordinates r and a in the format (r, a). The polar origin has the coordinates (0, a), where a is any angle. Compare Cartesian coordinate.

posting The process of generating error, warning, and notice messages by QuickDraw GX. See also debugging version, non-debugging version, error, warning, and notice.

postmultiplied A term that describes the order in which matrices are multiplied. Matrix [A] is postmultiplied by matrix [B] if matrix [A] is replaced by [A] [B]. Compare premultiplied.

premultiplied A term that describes the order in which matrices are multiplied. Matrix [A] is premultiplied by matrix [B] if matrix [A] is replaced by [B] [A]. Compare postmultiplied.

property An item or set of data in a QuickDraw GX object. A property of an object is analogous to a field (or member) of a data structure; however, a field is accessed through its name, whereas a property is accessed through an accessor function.

public validation The process of checking the validity of the parameters passed by an application. See validation.

QuickDraw GX cache Temporary memory that is managed by QuickDraw GX. Each object has a pointer to one or more caches. Each cache is related to only one object. See also dead cache and live cache.

recoverable error A nonfatal QuickDraw GX error indicating fragmented memory, a problem with the backing store, or a problem with the unflattening process.

reference A long word value, neither a pointer nor a handle, through which an application accesses a QuickDraw GX object. References are created by QuickDraw GX and passed to applications.

reflection The symmetrical movement of a mapping with respect to the Cartesian coordinate axes. The movement can be about the x- or y- or both axes.

reserved attributes The attributes of a collection item's 32 attributes that are reserved and cannot be set.

restricted access error A QuickDraw GX error indicating that the object data requested is private and not available.

result out of range warning An application execution warning detected and posted by QuickDraw GX indicating that the function result was out of the valid range.

seed An initialization value used by a random number generator to produce a sequence of values.

shape (1) A graphic or typographic item (such as a geometric shape, bitmap, or a line of text) created and drawn with QuickDraw GX. (2) A set of QuickDraw GX objects that, taken together, describe the type and characteristics of such a graphic or typographic item. A shape consists of a shape object, style object, ink object, and transform object.

shape cache A cache created and maintained by QuickDraw GX for storing the results of intermediate calculations made prior to drawing a shape.

shape fill A property of a shape object. The shape fill specifies whether and how QuickDraw GX fills in the outlines of a shape that is draws.

shape object A QuickDraw GX object that, along with several other objects, describes a QuickDraw GX shape. A shape object specifies the fundamental type and contents of a shape.

shape type A property of a shape object. The shape type specifies the classification (such as point, line, bitmap, or text) of a particular shape.

short number A 16-bit signed integer with 16 bits to the left and 0-bits to the right of the binary decimal point. A fixed point number with a bias of 0. The short number for 1.0 is 0x0001.

specific object validation A QuickDraw GX validation level that confirms that all references to a specific object type are valid.

storage warning A QuickDraw GX warning indicating a data stream problem.

stream format The public format available for describing flattened QuickDraw GX objects. Objects in stream format are compressed or flattened. Flattened objects are unflattened when they are converted back to object format. A flattened object may be interpreted by using QuickDraw GX unflattening functions or reconstructed by parsing with an interpreter that uses the stream format.

structure validation A QuickDraw GX validation level that confirms that references to object types are valid and that the properties of the object are valid. Compare type validation, and all object validation.

tag list A property of some QuickDraw GX objects. The tag list is an array of references to tag objects associated with the object.

tag list position The position of an item in a list of items with the same collection tag.

tag object A QuickDraw GX object whose purpose, structure, and content are entirely controlled by the application creating it. Tag objects exist to allow custom information and behavior to be attached to standard QuickDraw GX objects. Tag objects are classified by tag type; objects reference their tag objects through a tag list.

translation options The use of one or more constants to translate QuickDraw data to QuickDraw GX shapes.

transfer mode A QuickDraw GX data structure, also the property of an ink object, that controls the interaction between the color of a shape and the colors of the background at the location where the shape is drawn.

transform A QuickDraw GX object associated with a shape object. A transform object contains information that affects the visual appearance of a shape when it is drawn.

translator A set of functions that convert QuickDraw data into QuickDraw GX shapes or pictures. The translation approximates the intent of the original QuickDraw images; it does not provide a pixel-by-pixel mapping of the image.

type validation A QuickDraw GX validation level that confirms that references to object types are valid. Compare structure validation and all object validation.

underflow notice A QuickDraw GX notice indicating that a notice could not be removed from the ignore notice stack because no notice was on the stack.

underflow warning A QuickDraw GX warning indicating that a warning could not be removed from the ignore warning stack because no warning was on the stack.

unexpected result warning A QuickDraw GX warning indicating that a character or font substitution took place or that the geometry of an area or new device is probably incorrect.

unflatten To convert the public, stream-based description of an object or set of objects into the private, native QuickDraw GX object-based format. Compare flatten. See also stream format.

unload [an object] To move a QuickDraw GX object from memory to temporary external storage. QuickDraw GX automatically and transparently loads and unloads objects in the course of managing memory; an application need never know whether an object it accesses is currently loaded or unloaded.

user attributes The lower 16 bits of an item's attributes; these bits can be defined for purposes suitable to your application.

validation A set of debugging functions that cause one or more actions to occur whenever a QuickDraw GX function is called or whenever the internal memory manager is called. See also public validation, internal validation.

validation error A QuickDraw GX error detected and posted by the debugging version with validation error checking turned on. The parameters of objects are checked to ensure that the object is valid. See also validation.

view device A QuickDraw GX object associated with a view port object. A view device object describes the characteristics of a given physical display device such as a monitor or printer.

view group A QuickDraw GX object that consists of a grouping of view ports and view devices.

view port A QuickDraw GX object associated with a transform object. A view port describes the characteristics of the drawing environment for individual QuickDraw GX shapes.

view port hierarchy An ordered arrangement of view ports that allows for such features as windows within windows, including multiple windows within a single window.

view port list A property of a transform object. This list is an array of references to the view ports that the shapes associated with that transform can be drawn to.

warning A single descriptive phrase that is posted by QuickDraw GX whenever an application executes a function that may likely not provide the result expected. Execution continues internally, as if the warning had not been posted. A warning number is a unique number in the range -26999 through -26000 assigned to each QuickDraw GX warning message. Each warning has a unique warning name.

warning name See warning.

warning number See warning.

wide number A 64-bit signed integer with unspecified bias.

wrong type error A QuickDraw GX error indicating that an invalid type has been assigned to a shape.