Compound Strings in UIL

Text strings in UIL may be specified as simple string literals or as compound strings. Compound strings are created with the COMPOUND_STRING or the COMPOUND_STRING_COMPONENT functions. String literals are simply quoted text, and are stored either as NULL-terminated strings or as compound strings, depending on the complexity of the specified string. The UIL concatenation operator (&) concatenates both string literals and compound strings.

UIL also supports wide-character strings, which are documented in Chapter 11.

Simple Text Strings

A simple text string, or string literal, consists of text, a character set, and a layout direction. The character set may be explicitly specified, or a default value will be used. UIL infers the layout direction from the character set.

Some string literals will actually be stored by UIL as compound strings. This happens when

'[
character_string]'
[#
char_set]"[
character_string]"

Specifying Compound Strings

A programmer may create a compound string with the COMPOUND_STRING or the COMPOUND_STRING_COMPONENT functions. The COMPOUND_STRING function takes as arguments a string expression and optional specifications of a character set, direction, and whether or not to append a separator to the string. If no character set or direction is specified, UIL derives it from the string expression, in the same manner as for string literals, described in the previous section.

In order to create a complex compound string in UIL, it is necessary to use the COMPOUND_STRING_COMPONENT function. Use it to create compound strings in UIL consisting of single components, in a manner analogous to XmStringComponentCreate. This function lets you create simple compound strings containing components such as XmSTRING_COMPONENT_TAB and XmSTRING_COMPONENT_RENDITION_BEGIN that are not produced by the COMPOUND_STRING function. These components can then be concatenated to other compound strings to build more complex compound strings. (Use the UIL & operator to concatenate compound strings.)

The first argument of the COMPOUND_STRING_COMPONENT function must be an XmStringComponentType enumerated constant. The type and interpretation of the second argument depends on the first argument. For example, if you specify any of the following enumerated constants for the first argument, then you should not specify a second argument:

Render Tables and Tab Lists

Render tables, renditions, tab lists, and tab stops are implemented as a special class of objects, in a form analogous to the widget class. Though a render table is not itself a widget, its specification lists resemble one, and a widget that wants to use a render table must specify the render table in its controls list, not just with the XmNrenderTable resource.

In the same manner, a render table controls list contains the names of the renditions that make it up, a rendition controls list contains the names of the tab lists it uses, and the tab list controls list contains the names of the tab stops it uses. Although none of these objects are actual widgets, the format reads exactly as if the render table were a widget controlling a rendition widget, which in turn controlled a tab list widget, which in turn controlled a tab stop widget.

The following sample of UIL code shows a scrolled list widget that uses a render table.

object
  Scrolled_List:  XmScrolledList {
     arguments {
        XmNlistSpacing =  10;
        XmNlistMarginWidth =  10;
        XmNlistMarginHeight =  10;
        XmNitems =  string_table
                ("item1", "item2", "item3", "item4",
                "item5", "item6", "item7");
        XmNitemCount =  7;
        XmNvisibleItemCount =  4;
        XmNselectionPolicy = XmSINGLE_SELECT;
        XmNrenderTable = rt1;
     };
     callbacks {
        XmNsingleSelectionCallback = procedure Report_Callback
                        ('singleSelectionCallback');
     };
     controls {
        XmRenderTable rt1;
     };
   };
 
object
  rt1: XmRenderTable {
     controls {
        XmRendition rend;
     };
  };
 
object
  rend: XmRendition {
     arguments {
        XmNtag = XmFONTLIST_DEFAULT_TAG;
        XmNfontName = '9x15';
        XmNfontType = XmFONT_IS_FONT;
     };
     controls {
        XmTabList tabl;
     };
  };
 
object
  tabl: XmTabList {
     controls {
        XmTab tabstop;
     };
  };
 
object
  tabstop: XmTab {
     arguments {
        XmNtabValue = 1.0;
        XmNunitType = XmCENTIMETERS;
        XmNoffsetModel = XmABSOLUTE;
     };
  };

The render table (rt1) in this sample only contains one rendition, with the tag XmFONTLIST_DEFAULT_TAG. If the tag were not explicitly specified, its value would default to the name of the rendition object, in this case rend. The rendition in question uses resources to specify a font, and names a tab list ( tabl), which in turn names its only member tab stop ( tabstop). The tab stop again uses resources in its arguments list to specify its properties.