EZwgl (5.5 Setting and Extracting Client Data)

## 5.5 Setting and Extracting Client Data

The `EZ_Widget` data structure provides two special fields for applications to hook in application data to a widget. One is of type `int` and the other is of type `void *`. To set these fields, use

    void   EZ_SetWidgetIntData(EZ_Widget *widget, int  i);
    void   EZ_SetWidgetPtrData(EZ_Widget *widget, void *ptr);
    void   EZ_SetWidgetClientData(EZ_Widget *widget, int i, void *ptr);

To extract client data from a widget, use

    int    EZ_GetWidgetIntData(EZ_Widget *widget);
    void  *EZ_GetWidgetPtrData(EZ_Widget *widget);
    void   EZ_GetWidgetClientData(EZ_Widget *widget, int *i, void **ptr);

EZ widgets are also capable of allocating and managing dynamic storage. This feature provides a convenient way for an application to attach more complex client data to a widget without worrying about memory management. It is particularly convenient for situations when one needs to attach more than one pointers to a widget and doesn't want to introduce a new data structure for it.

The `EZ_Widget` data structure contains a pointer to `EZ_UnknownDataType` which serves as the hook for dynamically allocated storage.

    typedef  union {
      char            c;
      short           s;
      int             i;
      long            l;
      unsigned char   uc;
      unsigned short  us;
      unsigned int    ui;
      unsigned long   ul;
      float           f;
      void            *p;
    }  EZ_UnknownDataType;

Here are the relevent interface functions.

    void EZ_SetWidgetUnknownData(EZ_Widget *widget, int idx,
                                 EZ_UnknownDataType value);

(re)allocate (if needed) and set the the `idx`th element to `value`.

    int EZ_GetWidgetUnknownData(EZ_Widget *widget, int idx,
                                EZ_UnknownDataType  *ret);

retrieve the `idx`th element. Return 1 if succesful, return 0 otherwise.

    EZ_UnknownDataType   *EZ_GetWidgetUnknownDataPtr(EZ_Widget *widget);

return the dynamically allocated array.

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`