PtCreateActionSurface()

Create a control surface within a widget, bound to a widget action

Synopsis:

PtSurface_t *PtCreateActionSurface(
              PtWidget_t *widget,
              unsigned char surface_id,
              PtWidgetClassRef_t const *cref,
              unsigned short compound_action_id,
              unsigned short flags,
              unsigned short npoints,
              PhPoint_t *points,
              PtSurfaceDraw_f draw_f,
              PtSurfaceCalc_f calc_points_f );

Library:

ph

Description:

The function creates an action control surface within the given widget. The control surface is bound to a widget action.

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 cref argument specifies the widget class that owns the action to which you're binding the surface. If you specify NULL for this argument, PtCreateActionSurface() assumes that the action belongs to the same class as widget.

The compound_action_id argument specifies the action to bind to the surface. Refer to the widget documentation for a list of actions that each widget supports.

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 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 );

The 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:

PhPoint_t, PhTile_t, PtCreateSurface(), PtDestroyAllSurfaces(), PtDestroySurface()

Control Surfaces chapter of the Photon Programmer's Guide