Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 3 - Errors, Warnings, and Notices / Using Errors, Warnings, and Notices

Ignoring Warnings and Notices

You can use the GXIgnoreGraphicsWarning and GXIgnoreGraphicsNotice functions to selectively ignore, and thereby suppress, the posting of specific QuickDraw GX warnings and notices in parts of your application. There is no analogous function to ignore errors.

Note

Notices are posted only in the debugging version of QuickDraw GX.

The GXIgnoreGraphicsWarning function places the warning to be ignored on the ignore warning stack. The posting of all QuickDraw GX warnings that are on the ignore warning stack is suppressed, just as if the problem that resulted in the warning message never occurred.

When a QuickDraw GX warning is about to be posted, QuickDraw GX determines if the specific warning is on the ignore warning stack. If the warning to be posted is on the stack, QuickDraw GX does not post this warning. If the warning to be posted is not on the ignore warning stack, QuickDraw GX does post the warning. QuickDraw GX does not change the stack when it checks for the presence or absence of a warning.

The GXPopGraphicsWarning function removes warnings from the ignore warning stack in the reverse order that they are placed on the stack by the GXIgnoreGraphicsWarning function. You don't need to specify which warning to remove. You remove one ignored warning code from the top of the ignore warning stack each time that you call the GXPopGraphicsWarning function.

Note

There is an implementation limit on the number of times that you can use the GXIgnoreGraphicsWarning and GXPopGraphicsWarning functions. When the implementation limit is exceeded, QuickDraw GX posts a warning_stack_overflow warning message. If there are no warnings on the ignore warning stack and the GXPopGraphicsWarning function is called, QuickDraw GX posts a warning_stack_underflow warning message.

Since there is an implementation limit on the number of warnings and notices that you can ignore, you should use the GXIgnoreGraphicsWarning and GXPopGraphicsWarning functions only when you need to debug specific parts of your application code.

The GXIgnoreGraphicsNotice function provides the same feature for notices that the GXIgnoreGraphicsWarning function provides for warnings.

The GXIgnoreGraphicsNotice function places the notice to be ignored on the ignore notice stack. The posting of all QuickDraw GX notices on the ignore notice stack is suppressed, just as if the problem that resulted in the notice message never occurred.

When a QuickDraw GX notice is about to be posted, QuickDraw GX determines if the specific notice is on the ignore notice stack. If the notice to be posted is on the stack, QuickDraw GX does not post this notice. If the notice to be posted is not on the ignore notice stack, QuickDraw GX does post it. QuickDraw GX does not change the stack when it checks for the presence or absence of a notice.

The GXPopGraphicsNotice function removes notices from the ignore notice stack in the reverse order that they are placed on the stack by the GXIgnoreGraphicsNotice function. You don't need to specify which notice to remove. You remove one ignored notice code from the top of the ignore notice stack each time you call the GXPopGraphicsNotice function.

Note

There is an implementation limit on the number of times that you can use the GXIgnoreGraphicsNotice and GXPopGraphicsNotice functions. When the implementation limit is exceeded, QuickDraw GX will post a notice_stack_overflow warning message. If there are no notices on the notice warning stack and the GXPopGraphicsNotice function is called, QuickDraw GX posts a notice_stack_underflow warning message.

For example, if you wanted to suppress the attributes_already_set notice posted by QuickDraw GX, you could use the GXIgnoreGraphicsNotice function to push its notice number, -25998, onto the ignore notice stack. When QuickDraw GX is about to post a notice, it looks on the ignore notice stack to determine if its notice number is on the ignore notice stack. If the notice to be posted is attributes_already_set, then the notice is not posted. QuickDraw GX posts any notice that is not on the ignore notice stack.

If you also wanted to ignore the color_already_set notice, then you could use the GXIgnoreGraphicsNotice function to push its notice number, -25995, onto the ignore notice stack. QuickDraw GX would then ignore, and therefore not post, the attributes_already_set and color_already_set notices. Since you added the notices to the ignore notice stack in the order attributes_already_set and then color_already_set, the color_already_set notice would be on top of the ignore notice stack. When you use the GXPopGraphicsNotice function to remove a notice from the stack, the first notice to be removed is color_already_set, the one on top of the ignore notice stack. To remove the attributes_already_set notice, you need to call the GXPopGraphicsNotice function a second time. After the second call to the GXPopGraphicsNotice function, no notices are on the ignore notice stack. As a result, QuickDraw GX resumes posting all notices.

Figure 3-4 illustrates how warnings and notices are added to and removed from the ignore warning stack and the ignore notice stack.

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

You should ignore warnings and notices only if you are confident that you understand why they are being issued and the consequences of ignoring these warnings and notices.

For example, if your program asks for 100 points in a polygon and there are fewer points available, QuickDraw GX posts a warning and returns all of the points that are available. You can add the GXIgnoreGraphicsNotice function to your code to suppress this warning, but your application needs to be smart enough to accommodate the fact that less than the requested number of points may be returned.

The GXIgnoreGraphicsWarning function is discussed on page 3-62. The GXPopGraphicsWarning function is discussed on page 3-63. The QuickDraw warning names and numbers that may be ignored are listed in the section "Warnings" beginning on page 3-10.

The GXIgnoreGraphicsNotice function is discussed on page 3-68. The GXPopGraphicsNotice function is discussed on page 3-69. The QuickDraw GX warning names and numbers that can be ignored are listed in the section "Notices" beginning on page 3-27.