Functions for Use with Stub Widgets

The following functions present a highly simplified interface to the stub widget class that gives the user enough access to IDL widget internals to make the stub widget work while hiding the details of the actual implementation.

IDL_WidgetStubLock()

Syntax:

void IDL_WidgetStubLock(int set); 

IDL event processing occurs asynchronously, so any code that manipulates widgets must execute in a protected region. This function is used to create such a region. Any code that manipulates widgets must be surrounded by two calls to IDL_WidgetStubLock() as follows:

IDL_WidgetStubLock(TRUE); 
   /* Do your widget stuff */ 
IDL_WidgetStubLock(FALSE); 

IDL_WidgetStubLookup()

Syntax:

char *IDL_WidgetStubLookup(IDL_ULONG id); 

When IDL creates a widget, it returns an integer value to the caller of the widget creation function. Internally, however, IDL widgets are represented by a pointer to memory. The IDL_WidgetStubLookup() function is used to translate the user-level integer value to this memory pointer. All the other internal routines use the memory pointer to reference the widget.

Id is the integer returned at the user level. Your call to CALL_EXTERNAL should pass this integer to your C-level code for use with IDL_WidgetStubLookup() which translates the integer to the pointer.

If the specified id does not represent a valid IDL widget, this function returns NULL. This situation can occur if a widget was killed but its integer handle is still lingering somewhere.

IDL_WidgetIssueStubEvent()

Syntax:

void IDL_WidgetIssueStubEvent(char *rec, LONG value); 

Given a handle to the IDL widget, obtained via IDL_WidgetStubLookup(), this function queues an IDL WIDGET_STUB_EVENT. Such an event is a structure that contains the three standard fields (ID, TOP, and HANDLER) as well as an additional field named VALUE that contains the specified value.

VALUE can provide a way to access additional information about the widget, possibly by providing a memory address to the information.

IDL_WidgetSetStubIds()

Syntax:

void IDL_WidgetSetStubIds(char *rec, unsigned long t_id, 
                            unsigned long b_id); 

IDL widgets are built out of one or more actual widgets. Every IDL widget carries two pointers that are used to locate the top and bottom real widget for a given IDL widget. This function allows you to set these top and bottom pointers in the stub widget for later use.

Since the actual pointer type differs from toolkit to toolkit, this function declares t_id (the top real widget) and b_id (the bottom real widget) as unsigned long, an integer data type large enough to safely contain any pointer. Use a C cast operator to handle the difference.

After calling WIDGET_STUB to create an IDL stub widget, you will need to use CALL_EXTERNAL to call additional code that creates the real widgets that represent the stub. Having done that, use IDL_WidgetSetStubIds() to save the top and bottom widget pointers.

IDL_WidgetGetStubIds()

Syntax:

void IDL_WidgetGetStubIds(char *rec, unsigned long *t_id, 
                            unsigned long *b_id); 

This function returns the top (t_id) and bottom (b_id) real widget pointers for any specified widget (not just stub widgets). When using these values for non-stub widgets, it is the caller's responsibility to avoid damaging the IDL-created widgets in any way.

IDL_WidgetStubSetSizeFunc()

Syntax:

void IDL_WidgetStubSetSizeFunc(char *rec, 
                               IDL_WIDGET_STUB_SET_SIZE_FUNC func) 
 
typedef void (* IDL_WIDGET_STUB_SET_SIZE_FUNC); 
              (IDL_ULONG id, int width, int height); 

When IDL needs to set the size of a stub widget, it attempts to set the size of the bottom real widget to the necessary dimensions. Often, this is the desired behavior, but cases can arise where it would be better to handle sizing differently. In such cases, use IDL_WidgetStubSetSizeFunc() to register a function that IDL will call to do the actual sizing.