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.)
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 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.
S_Widget_Class Structure| Field | C Type | Description |
| 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.
|
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.
|
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.
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.
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.
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.
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. |
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.
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.
CBData_Object_Constructor
s_object *(*converter)(s_object *, XtPointer, XEvent **ev)
WidgetCreator
Widget (*WidgetCreator)(Widget, char *, ArgList, Cardinal)
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.