Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 1 - QuickDraw GX and the Macintosh Environment / QuickDraw GX and the Macintosh Environment Reference

Macintosh Interface Functions / Installing a View Port Filter

GXSetViewPortFilter

You can use the GXSetViewPortFilter function to intercept a shape being sent to a specified view port. Instead of drawing the shape, you can use an application-defined filter function to manipulate the shape.

void GXSetViewPortFilter(gxViewPort portOrder, 
                        gxUserViewPortFilter filter,long refCon);

portOrder

A reference to the view port to be filtered.

filter

A pointer to an application-defined callback function that acts on the filtered shape. If you pass nil for this parameter, any installed filter function is removed.

refCon

A long value to be passed to the callback filter function. Your filter function can use the value in any manner.

DESCRIPTION

The GXSetViewPortFilter function allows you to install a filter function that intercepts shapes sent to a specified view port and manipulates them in any manner you wish. You must specify a valid view port reference in the portOrder parameter.

The filter parameter is a pointer to an application-defined callback function of type gxUserViewPortFilter:

typedef void (*gxUserViewPortFilterProcPtr)(gxShape toFilter, 
                              gxViewPort portOrder, long refCon);
typedef gxUserViewPortFilterProcPtr gxUserViewPortFilter;

You must provide the callback filter function; its prototype is described in the section "Filtering Drawing Calls to a View Port" beginning on page 1-40.

When you call GXSetViewPortFilter, you can pass it any useful long value in the refCon parameter. That value will be passed to the filter function each time it is called.

To remove a filter function from a view port, call GXSetViewPortFilter with a nil value for the filter parameter.

SPECIAL CONSIDERATIONS

If you assign a filter function to a view port, it affects drawing to that specific view port only. Drawing to its child view ports or its parent view port (or any other view ports within its hierarchy) is unaffected.

ERRORS, WARNINGS, AND NOTICES

Errors

out_of_memory

invalid_viewPort_reference

SEE ALSO

To obtain a pointer to the filter function currently installed in a given view port, use the GXGetViewPortFilter function, described next.

For a description of the application-defined view port filter function, see page 1-40.