Introducing a New Widget Set

In this section, we describe how to take an existing widget set and integrate it into the SXLib library so that it can be used in the same manner as the supplied widget sets. Firstly, we should note that a widget set might contain just a single widget. We do not distinguish between single and multiple component widget sets. Throughout this section we refer to shared libraries. These are important components of Version 4 of S and are a modern replacement for the previous dynamic loading. The basic idea is that functions in the The advantages of shared libraries include Shared libraries do have some disadvantages including

The first requirement to integrating a widget set into SXLib is the code that implements the widget set. This might already be available on your system or obtainable from a URL. After extracting the individual files, read the installation (typically INSTALL) and instruction (README) files. These should indicate how to make the necessary modifications to customize the widget set to your system and may also give details on how to create a share library from the source code. If not, you should find other sources of information for this purpose. (See Installing X widgets for a brief description.)

The S Chapter

Instantiate the Widget Set

A function, usually called,
  create_name_class_table();
where name is the character string giving the name of the directory should be created and invoked from the C routine LibMain() in the chapter's initializing C file (directory name_i.c by default). The purpose of this function is to add this widget set's table of widgets and converters, etc.to the global list when this chapter is attached. It is not essential that you use the same name as the directory name but it makes things both consistent and easy as some of the functions (such as load() and ) use this connection between the database name and hook functions.

The body of this routine looks something like this

s_object *
create_XmTabs_class_table(void)
{
s_object *ans = NEW_INTEGER(1);

 (void)add_widget_set_table("XmTabs", XmTabs_Widget_Classes,
                        XtNumber(XmTabs_Widget_Classes));

 INTEGER_DATA(ans)[0] = XtNumber(XmTabs_Widget_Classes);

return(ans);
}
The routine add_widget_set_table() is provided by the SXLib chapter.

The Widget Set Table

The above function relies on an array of widget entries to create the local widget set components available to the user and govern their use. This table is simple but redious to create. (It could be partially automated, requiring validation and simple editing by the user but this has not been done yet.)

The table looks something like the following example:

S_Widget_Class  XmTabs_Widget_Classes[] = { 
 {"XmTabs", &xmTabsWidgetClass, NULL, NULL, NULL}
};
Each entry in the array is itself an array consisting of 5 elements. These are described in the following table. Note that the last field for each entry should be supplied as NULL. The first field is the name by which you are making the widget available to users of your S chapter. This is at your discretion and name conflicts with other widget sets can be qualified in most functions by specifying the widget set. The second field comes from the widget set implementation and is the address of the widget class structure. (You can use nm on the widget set's shared library to help you find these symbols but they should be easy to find in the documentation that accompanies the widget set.) The third field also comes from the documentation with the widget set and is the convenience function to create a widget, like the ones provided for most of the Motif widget set. This leaves only the fourth field and unfortuntately this is more complicated.

Table 1: The S_Widget_Class Structure
FieldC TypeDescription
name char * character string by which the S user refers to this class (such as in the Widget() function)
widget_class WidgetClass the addess of the C structure that is used in calls to routines such as XtCreateWidget or XtCreateManagedWidget or XtVaCreateManagedWidget() to create the widget. This is used both in widget creation and to probe for information about a widget class, such as the resources it supports, etc.
fn WidgetCreator Widget specific convenience routine used to create the widget other than a call to XtCreateWidget or XtCreateManagedWidget or XtVaCreateManagedWidget().
converters S_Callback_Data [10]1 This is an array of callback converter functions. Each element in this array is a S_Callback_Data object. These are processed to create the more efficient cb_converters table and control how the information from a callback is passed to the S user level. Each data element in the array is a strucuture containing 3 fields. These are described in Table 2
cb_converters s_name_table * This is a private field that you are not responsible for. This should be supplied as NULL and is an internal structured created when the widget set is loaded. This is a table of functions that convert the C data structures passed by the widget in a callback to S objects.
Table 2: The S_Callback_data Structure
data_class_name char * The character name of the S object to be created from this callback's data argument.
name char * This field represents the name of the callback (as would be supplied to the S function callback() or the C routine XtAddCallback()) such as "activeCallback". These are the character versions of the symbols such as XmNaddCallback and XtNcallback with the prefix (XmN or XtN) removed. The routine provided in the field converter is called for callbacks of this type.
converter CBData_Object_Constructor This is the C routine that performs the creation. The first argument is an object of class data_class_name given in the first field. The remaining two arguments are the data argument passed to the C callback routine and the address of the XEvent *. This allow us to modify the event, for what it is worth.
In our example - the XmTabs widget - there is a single callback type. This is documented in the man page that accompanies the source code.
XtNactivateCallback When the user clicks on a tab, a callback function is called. The call_data argument to the callback will be a relative number: 0 if the user clicked on the main tab, -1 if he clicked on the tab immedi- ately to the left, +1 if he clicked on the first right tab, and higher numbers for tabs that are further removed from the main one.
In order to provide this object to the S user/developer during a callback you must write a callback converter function that maps the C object to an S object. We do this in the following code. First, we create an S class to represent this object returned from this converter. In this case, it is simply an integer 4. We shall call the class XmTabsCBData simply to identify it and be consistent with other widget sets already installed. We define this as follows
  setClass("XmTabsCBData",
              representation(id="integer")
          )
The callback data converter receives an object of this class and inserts the relevant values into the objects slots as follows.
s_object *
XmTabs_CBData(s_object *object, XtPointer cb_data, XEvent **ev)
{
static int id_slot = -1;
int val = -100;

  /** The object is an S object of class XmTabsCBData
      Firstly, we intialize the slots identifiers in the object.
      This is done only once by checking the value of a local
      static variable.
   **/
   if(id_slot < 0) {
        /* Make sure this class has seen - this is unecessary as
           this routine has been called from another routine that just
           created the object!
         */
     ENSURE_CLASS_EXISTS(object);
     id_slot = SLOT_NUM(object,"id");
     if(id_slot < 0) {
       PROBLEM "incorrect object passed to XmTabs_CBData - no id slot"
       ERROR;
     }
   }

   val = (int)cb_data;
   object->value.tree[id_slot]->value.Long[0] = val;

return(object);
}

So now we can fill in the fourth element of the widgets table entry. This should be as follows

S_Widget_Class  XmTabs_Widget_Classes[] = { 
 {"XmTabs",      
  &xmTabsWidgetClass,
  NULL,
    { {"XmTabsCBData", "activateCallback", XmTabs_CBData},
      NULL      /* Identify end of list with a NULL */
    },
  NULL}
};

Of course, a simpler alternative to writing a converter function is to supply NULL for the converters field. In this case, the object will not passed to the S level during a callback. This allows for quick testing of the a subset of the functionality of the widget set before all the details have been completed. However, we urge you to map provide the data supplied at the C level to S user. In our example, without this information the user would be forced to cache the different widgets and contrast this with the widget in the event structure available during the callback to determine which tab was selected.

Resource Converters

Converters Native to the Widget

In many cases, the converters from strings to the relevant types used by the widget code will be provided in the widget sets' distribution. In this case, when you create the shared library for this widget set the converters will be contained in that object and will be available to any other object code that links this library. In other cases, however, the converters do not come as part of the widget itself but as part of a separate library. This happens in the case of the XmTabs widget. The converter is provided as part of the FWF's converter library rather than repeated for each widget that requires it. The first case is trivial as the converters are taken care of by the distribution. This latter case however can be handled in either of two ways - the quick and clumsy way or the elegant way that requires performing some searching through the widget set.

The quick and clumsy way is simple and involves determining into which object file or library the converters have been compiled. In the XmTabs example, this is the library ../../lib/libfwf.a. This library can be statically linked into the shared library for this widget set and hence the converter symbols become available to the widget set routines.

The second approach leads to a smaller library for this widget set. Instead of linking the library of all converters and other routines and variables, we suggest that you find the files that contain the source code for the converters of interest. Then compile these files into a separate shared object and finally, link the widget set objects into a shared library with this shared library of specialized converters.

Of course, if you have access to the installed version of SXLib, you can add the converters to its database/table of converters so that these can be shared by other widget sets that might be loaded before or instead of the widget set currently being integrated into SXLib. If you cannot modify the installed version, you might still be able to share converters from one chapter or widget set with another. This depends on the operating system running on the machine.

The S function lookupConverter() can be used to determine what converters are already available. The best way to use this is to realize an X application (X = XApplication("none",realize=T)) and then call lookupConverter(from-type, app=X).

One possible issue that might arise is that another widget set has a converter between two types but that it is not the correct converter. This happens in the XmTabs widget set. There is a conflict between the notion of a StringArray in this widget set and the Xbae widget set. How do we handle this? Well we can make a general converter that calls either one of these based on the type of widget. This requires that the widget be an argument to the converter.

Memory allocation in Converters

Depends on what the widget does with the values passed to it. If it copies them, then we can release them and the objects can be allocated using S routines. Otherwise, memory leaks.

S Functions and Classes

Convenience Routines

Most features of a widget (and hence, by extension, of a widget set) can be controlled through the resources using the C routines XtSetValues() and XtGetValues() or the S functions setResource getResource. and the different callbacks supported by the widget. However, in many cases, the widget set distribution provides C level convenience routines. It is good style to provide S level functions or methods that map onto these convenience routines. Since S is very flexible with its argument handling and due to its object oriented nature in contrast with the typical language used to develop widgets, C, it is likely that one S function will map to several widget routines. This is a matter of style. However, a positive benefit of this one-to-many appoach is that it reduces the overhead of creating numerous functions. Also it immediately centralize aspects of code that handle the interface between S and C so that if it has to be changed to handle different S classes or perform more error checking for example, only one version will require change. Of course, other coding styles will yield the same modularity.

S Class Converters

Converters from strings to the relevant C data type are normally provided by the widget set or are available from the SXLib table of converters. However, it is more convenient in most cases to pass an S object to the setResource() function rather than converting the object to the appropriate string. For example, if we have a vector of character strings, we could paste() them together using "," as the sep argument and indirectly pass this to a converter that creates an array of String objects. Instead, it is more efficient and easier for the user if we provide a converter from an S object to the appropriate data type required by the widget. Similarly, when a user attempts to retrieve resource the value should be returned as an S object. Even if the basic converter exists, for example from an integer to an S object, it is often useful to extend this so that it returns a named vector. For example, in the XmTabs widget, the command getResource(w,"orientation") returns the integer value associated the widget's orientation resource. However, a more convenient return value would be a named vector that identified the value with the string representation of the value as it would be entered in a resource file, such as "LeftTabs" or "UpTabs".

Having created the individual converter routines you need to make these available to the SXLib routines. You do this with the routine RegisterConverters(). This takes an array and the number of entries in the array as its two arguments. Once again, the tedious aspect of providing the converters is creating this array. Each element of the array, a Converter structure, has 5 fields.

Table 3: The Converter structure
Field C type Description
from String the name of the data type the value is being converted from. These are symbols such as XtRString or home-grown values
to String the name of the data type the value is being converterd to. As with the field from, these are symbols or strings listed here
converter XtTypeConverter the routine that performs the actual conversion
args XtConvertArgList an array of values that describe the context in which the conversion is taking place. These values might include the widget structure or the parent of the widget. See [Xt Intrinsics] for more details
num_args Cardinal the number of arguments in the args array.
Given an array of these Converter objects, say converter_table, you arrange for the entries to be registered via the call
  RegisterConverters(converter_table, XtNumber(converter_table));
This should be called from the LibMain() routine that is called when the chapter is created or indirectly from the .First function in the chapter. Note that if the array is declared in this file and not dynamically created, XtNumber can be used to automatically determine the number of elements in the array.

ListTree Widget

To allow the user create a ListTree widget, we need to create an initializer function (on.attach) or a routine that registers the widget set. (See ListTree_i.c and ListTree.web)

Note that no new resource converters are needed since there are no new resource types introduced by this widget, just new resource names. This can be immediately seen from the table provided in the documentation.

Next, we come to a less mechanical aspect of interfacing to a new widget set. This involves creating S functions that access the C convenience routines supported by the widget (set). This particular widget set poses special problems due the nature of the way it handle it handles its entries. Rather than storing simply the string and operating on this, the widget handles non-uniqueness of widgets uisng pointers to C data structures. This is slightly inconvenient from the S point of view, but could be handled with the class "raw". However, one difficulty that arises with the approach of storing the C pointer in an S object is that these objects (and pointers) persists after the memory for the data has been released (in this session or between sessions). Accordingly, we will take a simpler and more cautious approach. We use random "cookies" to connect the S list item with the corresponding C structure. When an entry is created in S, a random value is inserted into the object. When that entry is added to the list, that value is stored in the C structure (in the user data field). Then all operations on the S object that call C functions search the C entries for this cookie to identify the relevant item. This should be done with a hash table and the items should be grouped together at the S level using the STree class or some similar representation. However, for the moment, we describe the interface between the S and C routines using simple mechanisms.

This is the only complicated aspect of the interface between the C and S convenience routines. This is not complicated but does require some initial thought as to how best approach this type of problem. For most widgets, this issue will not arise as values rather pointers are used in the convienence routines and resources.

One does not have to provide an S function for each C utility function. Instead, it often is more sensible to consolidate several related utility functions into a single S function made possible by the more flexible argument handling available in S. Also, some C level utility functions provide esoteric use of the widget and can be added later if required. We have chosen to map the simple and primitive routines to S functions and allow S users build functionality from these rather than directly from the C routines. As with all programming in S that interfaces to C, there is a tradeoff of between simplicity and efficiency. We recommend doing as much of the error and type/class checking at the S level and making the C routines as simple as possible. This helps in the debugging and eliminates C level errors that can cause mysterious problems.

The utility functions are in Utils.S and the C routines (which make extensive use of call patterns) are in Utils.web (postscript).

Finally, we need callback data converters for the two types of callbacks supported by this widget. To do this, we must create S classes that represent the callback data object. These can extend the classes already defined such as those in the Motif or Xbae widget sets. Alternatively we can create them from scratch. The representation of these classes should follow almost immediately from the C structure used as the C level callback data. Since this particular widget set uses C pointers as we discussed in the previous paragraphs, the mapping between the C and S representations is not quite so straightforwad. Instead, the mapping relates to the magic cookies and the names of the entries in the tree.

The purpose of the callback data is provide easy access to data that is commonly needed in callbacks. When creating an S chapter for a widget set, we are at liberty to decide what consitutes useful callback data in the S context. For this widget set, we choose to map the C ListTreeItem structure to objects of S class ListTreeItem. The path field of the ActivateCallback structure is mapped to a named list of the ancestors items' cookies, with the ancestors' names.

setClass("ActivateCBData",
        representation(
               "ListTreeItem",
               reason="character",
               path="named",
       )
)
The routine ListTree_ActivateCBData converts the C ListTreeActivateStruct structure to an S object of class ActivateCBData.

The highlight callback data can be considered a subset of the ActivateCBData from the S point of view. Essentially this is the same structure as the path field in that callback data. So, we map this to a named list with the values being the items cookies and the names being the entry names. The routine ListTree_HighlightCBData converts the C ListTreeActivateStruct structure to an S object of class named.


1
This is hard coded to facilitate the creation of this table. The size of the array is largely irrelevant as long as it exceeds the maximum number of entries ever used.
2 CBData_Object_Constructor
This is a typedef for s_object *(*converter)(s_object *, XtPointer, XEvent **ev)
3 WidgetCreator
This is a typedef for Widget (*WidgetCreator)(Widget, char *, ArgList, Cardinal)
3
Unfortunately we can't specify "integer" as the class for the callback data type in S as we can't easily say
           new("integer")      
and get a single integer. Instead, we have an object of length 0. However, we can use "integer" as the type and set the length in the Callback Data constructor to 1 and then fill it in. Either approach is legitimate. Having a new class may make things clearer, but does incur the (very) small overhead of a new class.

Duncan Temple Lang<duncan@stat.Berkeley.EDU>
Last modified: Sun Mar 30 14:32:18 PST 1997