Create a regular control surface within a widget
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 );
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:
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 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:
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:
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.
PhEvent_t, PhPoint_t, PhTile_t, PtCreateActionSurface(), PtDestroyAllSurfaces(), PtDestroySurface()
Control Surfaces chapter of the Photon Programmer's Guide