PtCreateSurface()

Create a regular control surface within a widget

Synopsis:

PtSurface_t PtCreateSurface(
               PtWidget_t *widget,
               unsigned char surface_id,
               unsigned short flags,
               unsigned short npoints,
               PhPoint_t *points,
               long event_mask,
               PtSurfaceCallback_f event_f,
               PtSurfaceDraw_f draw_f,
               PtSurfaceCalc_f calc_points_f );

Library:

ph

Description:

This function creates a regular control surface within the given widget.

The surface_id argument lets you specify the ID assigned to the surface. If you specify 0 for this argument, the next available surface ID for that widget is assigned to the surface. If you specify a surface ID that already exists within the widget, the function fails and returns 0.

The flags argument gives you additional control over how the surface behaves. The valid bits are:

Pt_SURFACE_RELEASE_POINTS

The array of points specifying the widget's geometry will be freed when the surface is destroyed.

Pt_SURFACE_HIDDEN

Make the surface initially “hidden.” When surfaces are hidden, they don't draw or respond to events. You should manipulate this flag only when creating the surface. To hide the surface after it's created, use PtHideSurface() or PtHideSurfaceByAction().

Pt_SURFACE_CONSUME_EVENTS

The surface always consumes the events it receives. Setting this bit makes a surface opaque to events that it's accepting, regardless of whether or not the surface actually uses the event. This functionality may prove useful if you wish to disable a portion of a widget.

Pt_SURFACE_DISABLED

Prevent a surface from taking any action as a result of an event. If this flag is set, no events are consumed by the surface, unless the Pt_SURFACE_CONSUME_EVENTS flag is set.

Pt_SURFACE_USE_ORIGIN

The surface should use an adjustable origin that allows you to change the position of the surface without having to move the points that define the surface. This feature is useful if the surface is defined by a large number of points.

Pt_SURFACE_PARENT_RELATIVE

By default, all events and drawing of a surface are relative to the upper-left corner of the widget's canvas. Setting this flag adjusts this origin so that the surface uses the same coordinate system as its associated widget.

The npoints argument specifies the number of points that define the surface. Special values for this argument include:

• Pt_SURFACE_RECT for a rectangular surface
• Pt_SURFACE_ELLIPSE for an elliptical surface.

Otherwise the surface is polygonal with npoints vertexes.

The points argument points to an array of PhPoint_t structures that define the vertexes for the surface. For rectangular or elliptical surfaces, this needs to be only two points specifying the bounding box for the surface. For polygonal surfaces, the array must allow two points at the beginning of the array to store the bounding box of the surface, followed by npoints elements to specify the actual vertexes of the polygon. Additionally, if the Pt_SURFACE_USE_ORIGIN flag is set, the array must allow one element (located directly after the bounding box) to specify the origin. Points are stored in this fashion to optimize performance, memory requirements and simplicity of the most common cases.

The event_mask argument specifies the event types that the surface is sensitive to, and event_f specifies the function to call when an event is received that corresponds to one of the specified types. This function has the following prototype:

int event_f( PtWidget_t *widget,
             PtSurface_t *surface,
             PhEvent_t const *event );

The expected return values for event_f are consistent with those of raw callbacks:

Pt_CONSUME

Consume the event and prevent further propagation of it.

Pt_CONTINUE

Allow the event to be passed up to the widget's parent.

The draw_f argument specifies a draw function for the surface, which must be of the following prototype:

void draw_f( PtWidget_t *widget,
             PtSurface_t *surface,
             PhTile_t const *damage );

The damage argument points to a list of PhTile_t structures that specifies the areas of the control surface that were damaged.

If you don't want the surface to draw anything, specify NULL for draw_f.

Similarly, the calc_points_f argument lets you specify a geometry-calculation function for the surface, which must be of the following prototype:

void calc_points_f ( PtWidget_t *widget,
                     PtSurface_t *surface,
                     unsigned char post );

This function's post argument indicates when the function is being called:

Zero

Before the corresponding widget's extent function.

Nonzero

After the widget's extent function has completed.

If the widget's extent depends on the geometry of a surface, you will want to perform the work if post is 0. If the surface's geometry depends on the widget's extent, you will want to perform the work if post is nonzero.

Returns:

A pointer to a PtSurface_t structure that describes the control surface, or NULL if the operation failed due to lack of memory, or incorrect parameters.

Classification:

Photon

See also:

PhEvent_t, PhPoint_t, PhTile_t, PtCreateActionSurface(), PtDestroyAllSurfaces(), PtDestroySurface()

Control Surfaces chapter of the Photon Programmer's Guide