Control Surfaces #1 - API
By David W. LeBlanc
Surface Functions and Macros
| PtSurface_t* PtCreateSurface ( | PtWidget_t * PtSurfaceId_t ushort_t ushort_t PhPoint_t * long PtSurfaceCallback_f PtSurfaceDraw_f PtSurfaceCalc_f |
widget, surface_id, flags, npoints, points, event_mask, event_f, draw_f, calc_f |
|
)
|
Create a regular control surface within a widget.
Returns:
PtSurface_t*This function returns a pointer to the surface structure for the newly created surface on success, or NULL if the operation failed due to lack of memory or incorrect parameters.
Parameters:
widgetThe widget argument specifies the widget for which the surface will be created. surface_idEvery control surface has a numeric surface_id which uniquely identifies that surface within its associated widget. Valid values for surface_id are in the range of 1 through 255, inclusive. The surface_id argument allows you to specify the id that the surface will receive. If you specify 0 for this argument, the next available surface_id for that widget will be assigned to the surface. If you specify a surface_id that already exists within the widget, the function will fail and return 0. flags
The flags argument allows you additional control over how the surface will behave. Valid fields for this argument are:
| Pt_SURFACE_RELEASE_POINTS | If this bit is on, the array of points specifying the widget's geometry will be free'd when the surface is destroyed. | |
| Pt_SURFACE_HIDDEN | This values makes the surface initially "hidden". When surfaces are hidden, they do not draw or respond to events. You should only manipulate this flag at surface creation time. If you wish to hide the surface at a later time, you should use PtHideSurface() or PtHideSurfaceByAction(). | |
| Pt_SURFACE_CONSUME_EVENTS | This flag indicates that the surface should always consume events which it receives. Setting this bit makes a surface opaque to events that it is 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 | This flag prevents a surface from taking any action as a result of an event. If this flag is set, no events will be consumed by the surface, unless the Pt_SURFACE_CONSUME_EVENTS flag is set. | |
| Pt_SURFACE_USE_ORIGIN | This flag indicates that 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. |
npointsThe npoints argument specifies the number of points that define the surface. Special values for this argument include Pt_SURFACE_RECT (for a rectangular surface) or Pt_SURFACE_ELLIPSE (for an elliptical surface). Otherwise the surface will be polygonal with npoints vertices. pointsThe points argument points to an array of PhPoint_t type structures that define the vertices for the surface. For rectangular or elliptical surfaces, this only needs to be 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 array, as well as an addition npoints elements to specify the actual vertices 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. event_mask
event_fThe event_mask argument specifies the event types which the surface is sensitive to, and event_f specifies the function to call when an event is received which corresponds to one of the specified types. This event_f function should have the following prototype:
| int PtDestroySurfaceByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id, |
|
)
|
Destroys a control surface.
All surfaces of a widget are automatically destroyed when that widget is destroyed.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the surface to destroy. surface_idThe surface_id argument specifies the id of the surface to destroy.
| int PtDestroyAllSurfaces ( | PtWidget_t * | widget |
|
)
|
Destroys all control surfaces of a widget.
Generally this function is only used internally by the widget library, however you may call it if you wish.
All surfaces of a widget are automatically destroyed when that widget is destroyed.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget with surfaces to be destroyed.
| PtSurface_t *PtFindSurfaceByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Locate a control surface, using its numeric id as a search key.
Returns:
PtSurface_t *This function returns a pointer to the structure representing the desired control surface on success, or NULL if the specified surface could not be found.
|
Since control surfaces are maintained internally as an array, it's not uncommon for them to shift around in memory as surfaces are added and removed, thereby possibly invalidating a pointer returned by this function. As such, all surface pointers should be regarded as transient, and you should retrieve an updated copy whenever there is a chance that the widget's surface configuration might have changed. |
widgetThe widget argument specifies the widget to search. surface_idThe surface_id argument specifies the id of the surface to find.
| int PtInsertSurface ( | PtWidget_t * PtSurface_t *, PtSurfaceId_t, int |
widget, surface, surface_id, behind |
|
)
|
Changes a surface's z-coordinate by inserting in front or in behind another surface.
Returns:
intReturns 0 on success, or -1 if one or both of the specified surfaces could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surfaceThe surface argument specifies a pointer to the surface to be inserted. surface_idThe surface_id argument specifies the numeric id of a surface which the new surface is placed above or behind. behindThe behind argument specifies how to position the surface. If this value is 0, the surface will be position in front its new brother, otherwise it will be positioned behind.
| int PtSurfaceToFrontByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Moves a surface to the front of all other surfaces.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to move.
| int PtSurfaceToBackByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Moves a surface behind all other surfaces.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to move.
| int PtDamageSurfaceByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Flags a surface to be damaged, causing it to be redrawn.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to damage.
| int PtCalcSurfaceByID( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Force a surface to calculate its geometry.
This function is useful if the geometry of one surface depends on the geometry of another.
This function call amounts to a no-op if the geometry for the specified surface has already been calculated for this pre/post-extent cycle.
Returns:
intReturns a pointer to the specified surface on success, or NULL if the surface could not be found.
|
Since control surfaces are maintained internally as an array, it's not uncommon for them to shift around in memory as surfaces are added and removed, thereby possibly invalidating a pointer returned by this function. As such, all surface pointers should be regarded as transient, and you should retrieve an updated copy whenever there is a chance that the widget's surface configuration might have changed. |
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to calculate.
| PhRect_t *PtSurfaceExtent ( | PtWidget_t * PtSurface_t const PhRect_t * |
widget, surface, extent |
|
)
|
Force a surface to calculate its geometry.
This function is useful if the geometry of one surface depends on the geometry of another.
This function call amounts to a no-op if the geometry for the specified surface has already been calculated for this pre/post-extent cycle.
Returns:
PhRect_t *Returns a pointer to extent.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surfaceSurface is a pointer to the surface whose extent is computed. extentThe extent argument points to a structure to store the result.
| int PtHideSurfaceByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Hide a control surface.
Hidden surfaces do not draw and are not included in event processing.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to hide.
| int PtShowSurfaceByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Show a control surface, restoring it from a hidden state.
Hidden surfaces do not draw and are not included in event processing.
Returns:
intReturns 0 on success, or -1 if the specified surface could not be found, or wasn't hidden.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface to show.
| int PtSurfaceAddDataByID ( | PtWidget_t * PtSurfaceId_t void * long |
widget, surface_id, data, len |
|
)
|
Attaches data to a surface.
Any data previously added to this surface is removed and overwritten.
Returns:
intReturns 0 on success or -1 if the operation failed due to lack of memory, or if the specified surface could not be found.Parameters:
widgetThe widget argument specifies the widget owning the specified surfaces. surface_idThe surface_id argument specifies the id of the surface to receive new data. dataThe data argument points to the data to attach to the surface. lenThe len specifies the length (in bytes) of the data. If len is non-zero, then len bytes of data are copied from the data pointer, and that copy is attached to the surface. This copy will be freed when the data is removed. If len is 0, no copying is performed, and no de-allocation takes place when the data is removed.
| int PtSurfaceRemoveDataByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Removes data from a surface.
Any data previously added to this surface is removed and overwritten. If, when the data was added, the len argument was non-zero, then the copy of the data that was made is automatically freed, otherwise no de-allocation takes place.
Data is automatically removed when a surface is destroyed.
Returns:
intReturns 0 on success or -1 if the operation failed either because the specified surface could not be found, or if that surface did not have any data attached.Parameters:
widgetThe widget argument specifies the widget owning the specified surface. surface_idThe surface_id argument specifies the id of the surface with data to remove.
| void *PtSurfaceGetDataByID ( | PtWidget_t * PtSurfaceId_t |
widget, surface_id |
|
)
|
Retrieves a surface's data.
Returns:
void*Returns a pointer to the data on success, or NULL if either the specified surface could not be found, or if that surface did not have any data attached.Parameters:
widgetThe widget argument specifies the widget owning the specified surfaces. surface_idThe surface_id argument specifies the id of the surface with data.
| int PtDisableSurfaceByID ( | PtWidget_t * PtSurfaceId_t ulong_t |
widget, surface_id, flags |
|
)
|
Disable a control surface.
Disabled surfaces are drawn, but they do not respond to events. They will or will not consume events that they are sensitive to depending on the setting of their Pt_SURFACE_CONSUME_EVENTSflag. If this bit is set, the surface effectively blocks events to which it is sensitive.
Returns:
intReturns 0 on success or -1 if the specified surface could not be found, or was already disabled.Parameters:
widgetThe widget argument specifies the widget owning the specified surfaces. surface_idThe surface_id argument specifies the id of the surface to disable. flagsThe flags arugment specifies additional action to take, and may include the following values:
| Pt_DAMAGE_SURFACE | Damage the surface is its state changes. This is useful if a surface draws differently depending on its enabled/disabled state. |
| int PtEnableSurfaceByID ( | PtWidget_t * PtSurfaceId_t ulong_t |
widget, surface_id, flags |
|
)
|
Enable a control surface, restoring it from a disabled state.
Returns:
intReturns 0 on success or -1 if the specified surface could not be found, or was already enabled.Parameters:
widgetThe widget argument specifies the widget owning the specified surfaces. surface_idThe surface_id argument specifies the id of the surface to disable. flagsThe flags arugment specifies additional action to take, and may include the following values:
| Pt_DAMAGE_SURFACE | Damage the surface is its state changes. This is useful if a surface draws differently depending on its enabled/disabled state. |
| PtSurfaceId_t PtSurfaceId ( | PtSurface_t * | surface ) |
This macro retrieves the numeric id from a control surface structure.
| int PtSurfaceIsHidden ( | PtSurface_t * | surface ) |
This macro evaluates to non-zero if the provided surface is hidden. Otherwise, it evaluates to 0.
| int PtSurfaceIsShown ( | PtSurface_t * | surface ) |
This macro evaluates to non-zero if the provided surface is being shown. Otherwise, it evaluates to 0.
| int PtSurfaceIsDisabled ( | PtSurface_t * | surface ) |
This macro evaluates to non-zero if the provided surface is currently disabled. Otherwise, it evaluates to 0.
| int PtSurfaceIsEnabled ( | PtSurface_t * | surface ) |
This macro evaluates to non-zero if the provided surface is currently enabled. Otherwise, it evaluates to 0.
| PhRect_t *PtSurfaceRect ( | PtSurface_t * | surface, |
| PhRect_t* | rect | |
|
)
|
This macro retrieves the bounding box of a control surface. If rect is non-NULL, the result will be copied there and the macro will return rect. Otherwise, a pointer to the surface's internal data is returned.
| PtSurfaceId_t PtWidgetActiveSurface ( | PtWidget_t * | widget ) |
This macro retrieves the provided widget's currently "active" surface. The active surface is the last surface which consumed an event of type Ph_EV_BUT_PRESS.