Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 3 - Errors, Warnings, and Notices / About QuickDraw GX Errors, Warnings, and Notices

Non-Debugging Version

When you install the non-debugging version, QuickDraw GX provides a reduced set of errors and warnings. Since the amount of testing is less, the non-debugging version of QuickDraw GX runs significantly faster than the debugging version. Use the non-debugging version for debugged applications that you have extensively tested using the debugging version of QuickDraw GX.

When the non-debugging version is installed and corrupt data is used, drawings may execute with undesirable results, including crashes, without the posting of errors and warnings. With other execution problems, the application may not crash, but the drawing may not yield the expected result.

In the non-debugging version, typical problem messages indicate that there is insufficient memory, insufficient storage space, or that the required fonts are not installed. If problems persist, you can always install the debugging version to assist in the analysis of the errors that are occurring.

For a complete list of errors, please see the graphics errors.h interface file. The many notices, warnings, and errors defined between #ifdef debugging and #endif in that file are available only with the debugging version.

A debugged application should encounter only errors like

out_of_memory
not_enough_memory_for_graphics_client_heap
graphics_client_too_small
could_not_create_backing_store

A debugged application should encounter warnings like

character_substitution_occurred
map_shape_out_of_range
move_shape_out_of_range
scale_shape_out_of_range
rotate_shape_out_of_range
skew_shape_out_of_range
map_transform_out_of_range
move_transform_out_of_range
scale_transform_out_of_range
rotate_transform_out_of_range
skew_transform_out_of_range

Both the debugging and non-debugging versions of QuickDraw GX provide a debugging utility called GraphicsBug. This versatile utility allows you to examine the details of each graphics object. GraphicsBug is described in the chapter "QuickDraw GX Debugging" in this book.

Errors

This section describes the errors that may be posted by both the debugging and non-debugging versions of QuickDraw GX. These errors can be grouped into the following categories:

• fatal errors
• internal errors
• recoverable errors
• font management errors
• bad parameter errors
• implementation limit errors
• font scaler errors

Each QuickDraw GX error has an error number and an error name. Table 3-1 gives the non-debugging error number ranges.

Table 3-1 Non-debugging error number ranges

Number	Name
-27999	gxFirstSystemError
-27999	gxFirstFatalError
-27951	gxLastFatalError
-27950	gxFirstNonFatalError
-27900	gxFirstFontScalerError
-27851	gxLastFontScalerError
-27850	gxFirstParameterError
-27800	gxFirstImplementationLimitError

QuickDraw GX fatal errors terminate operation and automatically call the GXExitGraphics function. Control returns to the calling application after the error is posted. If the function that caused the error returns a function result, its value is either 0 or nil. Table 3-2 lists fatal errors. They are included in both the debugging and non-debugging versions of QuickDraw GX.

Table 3-2 Fatal errors

Number	Name
-27999	out_of_memory
-27998	internal_fatal_error
-27997	no_outline_font_found
-27996	not_enough_memory_for_graphics_client_heap
-27995	could_not_create_backing_store

QuickDraw GX nonfatal internal errors indicate damaged files, memory problems, or incorrect implementation of QuickDraw GX. Table 3-3 lists the internal errors.

Table 3-3 Internal errors

Number	Name
-27950	internal_error
-27949	internal_font_error
-27948	internal_layout_error

Table 3-4 lists the QuickDraw GX recoverable errors.

Table 3-4 Recoverable errors

Number	Name
-27946	could_not_dispose_backing_store
-27945	unflattening_interrupted_by_client

Table 3-5 lists the QuickDraw GX font management errors.

Table 3-5 Font management errors

Number	Name
-27944	font_cannot_be_changed
-27943	illegal_font_parameter

Table 3-6 lists the QuickDraw GX font scaler errors.

Table 3-6 Font scaler errors

Number	Name
-27900	null_font_scaler_context
-27899	null_font_scaler_input
-27988	invalid_font_scaler_context
-27897	invalid_font_scaler_input
-27896	invalid_font_scaler_font_data
-27895	font_scaler_newblock_failed
-27894	font_scaler_getfonttable_failed
-27893	font_scaler_bitmap_allocation_failed
-27892	font_scaler_outline_allocation_failed
-27891	required_font_scaler_table_missing
-27890	unsupported_font_scaler_outline_format
-27889	unsupported_font_scaler_stream_format
-27888	unsupported_font_scaler_font_format
-27887	font_scaler_hinting_error
-27886	font_scaler_rasterizer_error
-27885	font_scaler_internal_error
-27884	font_scaler_invalid_matrix
-27883	font_scaler_fixed_overflow
-27882	font_scaler_api_version_mismatch
-27881	font_scaler_streaming_aborted
-27880	unknown_font_scaler_error

QuickDraw GX posts bad parameter errors when a required parameter is out of range, invalid, or is passed with the value of nil. Table 3-7 lists bad parameter errors

Table 3-7 Bad parameter errors

Number	Name
-27850	parameter_is_nil
-27849	shape_is_nil
-27848	style_is_nil
-27847	transform_is_nil
-27846	ink_is_nil
-27845	transferMode_is_nil
-27844	color_is_nil
-27843	colorProfile_is_nil
-27842	colorSet_is_nil
-27841	spoolProcedure_is_nil
-27840	tag_is_nil
-27839	type_is_nil
-27838	mapping_is_nil
-27837	invalid_viewDevice_reference
-27836	invalid_viewGroup_reference
-27835	invalid_viewPort_reference

.

QuickDraw GX posts implementation limit errors to indicate that the size or number exceeds the size or number supported by the current version of QuickDraw GX.
Table 3-8 lists the implementation limit errors.

Table 3-8 Implementation limit errors

Number	Name
-27800	number_of_contours_exceeds_implementation_limit
-27799	number_of_points_exceeds_implementation_limit
-27798	size_of_polygon_exceeds_implementation_limit
-27797	size_of_path_exceeds_implementation_limit
-27796	size_of_text_exceeds_implementation_limit
-27795	size_of_bitmap_exceeds_implementation_limit
-27794	number_of_colors_exceeds_implementation_limit
-27793	procedure_not_reentrant

Warnings

This section describes the warnings that the debugging and non-debugging versions of QuickDraw GX may post. These errors can be grouped into the following categories:

• stack, heap, and object warnings
• result is out of range warnings
• parameter is out of range warnings
• font scaler warnings
• unexpected result warnings
• storage warnings

Each QuickDraw GX warning has a unique warning number and warning name.
Table 3-9 gives the non-debugging warning number ranges.

Table 3-9 Non-debugging warning number ranges

Number	Description
-26999	gxFirstSystemWarning
-26950	gxFirstResultOutOfRangeWarning
-26900	gxFirstParameterOutOfRangeWarning
-26850	gxFirstFontScalerWarning

QuickDraw GX overflow warnings occur when the number of warnings that have been added to the warning or notice stack exceeds the current implementation limit. An underflow warning occurs when the GXPopGraphicsNotice or GXPopGraphicsWarning function attempts to remove an error or warning on its ignore stack and there is no error or warning to remove. This topic is discussed in the section "Ignoring Warnings and Notices" beginning on page 3-36.

Table 3-10 lists QuickDraw GX stack, heap, and object warnings.

Table 3-10 Stack, heap, and object warnings

Number	Name
-26999	warning_stack_underflow
-26998	warning_stack_overflow
-26997	notice_stack_underflow
-26996	notice_stack_overflow
-26995	about_to_grow_heap
-26994	about_to_unload_objects

QuickDraw GX result out of range warnings occur when a function result is out of the usable or defined QuickDraw boundaries. Table 3-11 lists result out of range warnings.

Table 3-11 Result out of range warnings

Number	Name
-26950	map_shape_out_of_range
-26949	move_shape_out_of_range
-26948	scale_shape_out_of_range
-26947	rotate_shape_out_of_range
-26946	skew_shape_out_of_range
-26945	map_transform_out_of_range
-26944	move_transform_out_of_range
-26943	scale_transform_out_of_range
-26942	rotate_transform_out_of_range
-26941	skew_transform_out_of_range
-26940	map_points_out_of_range

QuickDraw GX parameter out of range warnings occur when a function parameter is out of the usable range. Table 3-12 lists parameter out of range warnings.

Table 3-12 Parameter out of range warnings

Number	Name
-26900	contour_out_of_range
-26899	index_out_of_range_in_contour
-26898	picture_index_out_of_range
-26897	color_index_requested_not_found
-26896	colorSet_index_out_of_range
-26895	index_out_of_range
-26894	count_out_of_range
-26893	length_out_of_range
-26892	font_table_index_out_of_range
-26891	font_glyph_index_out_of_range
-26890	point_out_of_range
-26889	profile_response_out_of_range

Table 3-13 lists QuickDraw GX font scaler warnings.

Table 3-13 Font scaler warnings

Number	Name
-26850	font_scaler_no_output
-26849	font_scaler_fake_metrics
-26848	font_scaler_fake_linespacing
-26847	font_scaler_glyph_substitution
-26846	font_scaler_no_kerning_applied

Table 3-14 lists QuickDraw GX unexpected result warnings.

Table 3-14 Unexpected result warnings

Warning number	Warning name
-26845	character_substitution_took_place
-26844	unable_to_bounds_on_multiple_devices
-26843	font_language_not_found
-26842	font_not_found_during_unflattening

Table 3-15 lists QuickDraw GX data stream storage warnings.

Table 3-15 Storage warnings

Number	Name
-26841	unrecognized_stream_version
-26840	bad_data_in_stream