PtSurfaceAddData(), PtSurfaceAddDataById()

Add data to a control surface

Synopsis:

int PtSurfaceAddData( PtWidget_t *widget,
                      PtSurface_t *surface,
                      void *data,
                      long len );

int PtSurfaceAddDataById( PtWidget_t *widget,
                      unsigned char surface_id,
                      void *data,
                      long len );

Library:

ph

Description:

These functions attach data to a control surface belonging to the given widget. They differ in how they identify the control surface:

PtSurfaceAddData(): Uses the surface argument, which points to a PtSurface_t structure that describes the control surface. This pointer must not be NULL.
PtSurfaceAddDataById(): Searches the control surfaces belonging to the widget for the one with an ID of surface_id.

The data arguments points to the data to attach. This data can be anything you need to store with the surface. Any data previously added to this surface is removed and overwritten.

The len argument specifies the length (in bytes) of the data. If len is nonzero, then len bytes of data are copied from the data pointer, and that copy is attached to the surface. This copy is freed when the data is removed. If len is 0, no copying is performed, and no deallocation takes place when the data is removed.

Returns:

0: Success.
-1: The operation failed due to a lack of memory, or the specified surface couldn't be found.

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No

See also:

PtSurfaceGetData(), PtSurfaceGetDataById(), PtSurfaceRemoveData(), PtSurfaceRemoveDataById()

Control Surfaces chapter of the Photon Programmer's Guide