Create a control surface within a widget, bound to a widget action
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 );
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:
The npoints argument specifies the number of points that define the surface. Special values for this argument include:
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:
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.
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.
PhPoint_t, PhTile_t, PtCreateSurface(), PtDestroyAllSurfaces(), PtDestroySurface()
Control Surfaces chapter of the Photon Programmer's Guide