Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 4 - QuickDraw GX Debugging / About QuickDraw GX Debugging

Validation Functions

The debugging version of QuickDraw GX provides validation for applications using graphics and typographic functions, but does not provide validation for QuickDraw GX printing functions.

The validation functions check function parameters of allocated objects to see if they are valid. If QuickDraw GX finds one or more parameters of a function to be invalid, it posts a validation error. All of the validation errors that may be posted are listed in the chapter "Errors, Warnings, and Notices."

There are two modes of validation that control when validation occurs:

• public validation
• internal validation

Public validation occurs whenever the public validation flag is set and your application uses a public function. A public function is any function that you use in your application. This is the mode of validation developers use most.

Internal validation occurs whenever the internal validation flag is set and your application uses a public function and whenever QuickDraw GX uses one of its internal (private) functions. Application developers do not usually use internal validation. Internal validation performs checking on functions that you have no control over. As a result, you will rarely need to perform this type of validation. However, QuickDraw GX provides internal validation to allow you to distinguish between bugs that appear in public functions and bugs that are present in the QuickDraw GX internal functions, as discussed in the section "Distinguishing Between Application Bugs and QuickDraw GX Bugs" beginning on page 4-22.

There are three levels of validation that control what is checked during validation:

• type validation
• structure validation
• all object validation

The validation these three levels provide is cumulative and progressively more complex. For example, all object validation includes type validation and structure validation.

In addition to these three levels, there are separate object validation functions.

Type validation confirms the validity of references to object types. For example, when you call the GXDrawShape function, type validation confirms that a shape type is passed.

Structure validation confirms the validity of references to object types and the properties of the function, and also checks internal caches. For example, when you call the GXDrawShape function, structure validation confirms not only that the function passes a shape, but also confirms the validity of the properties specified in the shape's style, ink, and transform objects.

All object validation confirms the validity of references to a specific object type, the validity of the properties of all objects, and all internal caches.

Specific object validation functions are used to confirm that all references to a specific object type are valid, that the properties of all objects are valid, and that all internal caches built for the specific object type are valid. Specific object validation functions are provided for shapes, styles, inks, transforms, color sets, color profiles, tags, view devices, view ports, view groups, and graphics clients.

It is important to note that not all parameters of all functions are checked by validation. Validation does not check scalars and structures, such as bitmaps and dash records.

For example, the second parameter of the GXSetShapePen function is the pen size. If you pass a negative value to the second parameter, QuickDraw GX will not post a validation error. Fortunately, QuickDraw GX often provides an overlap in its debugging capabilities, and in this case, the GXSetShapePen function would post an error indicating that the size is invalid.

Validation does check

• objects that are indicated by pointer values, such as shapes
• objects that are indicated by references, such as view devices

Note

You should not make an application dependent on whether an object is referred to by pointer or reference. This is subject to change in future versions of QuickDraw GX.

You can enable validation selectively over the selected problem area of code. Rather than turning validation on at the beginning of your application, you may find it is more useful to concentrate on an area where a problem is suspected and to turn validation on and off selectively in that area or selectively use the specific object validation functions.