There are several different functions available to create a compound string.

The most basic such function is XmStringGenerate, which accepts as arguments the text to be encoded, and a rendition tag to use to display it. It also accepts information about the locale or charset to use in rendering the text. The function returns an encoded XmString.

The XmStringComponentCreate function is used to create individual components of a compound string, such as the text, the tag, the direction, or the separator, which can then be concatenated into a single longer string.

There are a few functions that create a compound string which are obsolete, but are included for compatibility with earlier releases of Motif.

XmStringCreate may also be used to create a compound string of charset type with a specified font tag, with no rendition specified. The XmStringCreate function has been superseded, but is included for backward compatibility. Its function can be easily duplicated by calling XmStringGenerate with the text type XmCHARSET_TEXT, a charset tag, and a NULL rendition tag. XmStringSegmentCreate functions in the same manner to XmStringCreate, but allows the programmer to specify the string direction, and whether a separator should be appended to the returned XmString.

Earlier releases of Motif also included the functions XmStringCreateLtoR and XmStringCreate. These are still available, but again only for purposes of backward compatibility with existing code. Use XmStringGenerate instead.

The XmStringSeparatorCreate function may also be used instead of XmStringSegmentCreate to create a separator component for a compound string. In display, the separator would typically be mapped to a line break. Note that this function will not do anything more than XmStringSegmentCreate would if called with an empty text string.

The application that calls the compound string creation functions is responsible for performing its own memory management. The creation functions all must allocate space in which to return the strings.

When an application is finished with a compound string, the XmStringFree function should be used to free the memory that had been used for that string, and to make it available for some other purpose.

The following code sample demonstrates the use of XmStringGenerate and XmStringFree to create and display a compound string in a PushButton gadget.

void RendCB(Widget, XtPointer, XtPointer);
XmString        rend_label1, rend_label2;
widget  rend_button1, rend_button2;
XmRenderTable RenderTable;
...

/* RenderTable created with two renditions:
 * Rendition1 and Rendition2 */

...
RendPullDown = (Widget)XmCreatePulldownMenu(menubar, "RendPullDown",
                                            NULL, 0);

rend_label1=XmStringGenerate("render1", NULL, XmCHARSET_TEXT,
                             "Rendition1");
rend_label2=XmStringGenerate("render2", NULL, XmCHARSET_TEXT,
                             "Rendition2");

rend_button1 = XtVaCreateManagedWidget("rend1", xmPushButtonGadgetClass,
                                RendPullDown,
                                XmNrenderTable, RenderTable,
                                XmNlabelString, rend_label1,
                                NULL);
rend_button2 = XtVaCreateManagedWidget("rend2", xmPushButtonGadgetClass,
                                RendPullDown,
                                XmNrenderTable, RenderTable,
                                XmNlabelString, rend_label2,
                                NULL);
XtAddCallback(rend_button1, XmNactivateCallback, RendCB, (XtPointer) 0);
XtAddCallback(rend_button2, XmNactivateCallback, RendCB, (XtPointer) 1);

XmStringFree(rend_label1);
XmStringFree(rend_label2);

Note that the description of Rendition1 and Rendition2 must be explicitly sent to the widgets by using the XmNrenderTable resource to specify the render table containing these renditions. See section 9.2 about renditions and render tables. Also note that rend1 and rend2 are the names of the PushButton widgets; they are not the labels that will appear on those widget.

*RendPullDown.rend_button1.labelString:  render1
*RendPullDown.rend_button2.labelString:  render2

*RendPullDown.rend_button1.renderTable.rendition1:  render1
*RendPullDown.rend_button2.renderTable.rendition2:  render2

To make working with compound strings as simple as using regular character strings, Motif contains a number of functions analogous to the basic string manipulation functions generally available with C.

Use XmStringCompare to determine whether its two input compound strings are identical. XmStringConcat creates a third string by concatenating its two input strings. XmStringConcatAndFree does the same thing, except that it also deletes the two input strings and frees the memory occupied by them. XmStringCopy allocates enough memory to hold a copy of its input string, and returns a copy there. The XmStringEmpty function returns a Boolean value of True if there is no printable text in the input compound string. The XmStringIsVoid function is the same as the XmStringEmpty function except that it will only return True if there is no text at all in the string, printable or unprintable.

The following example takes an existing compound string called string, and sandwiches it with a new rendition, called rendition. This may also be accomplished with the XmStringPutRendition function (see section 9.2.3.1).

XmString  string;
XmString  tmp1, tmp2;
...

tmp1 = XmStringComponentCreate(
             XmSTRING_COMPONENT_RENDITION_BEGIN, "rendition");
tmp2 = XmStringComponentCreate(
             XmSTRING_COMPONENT_RENDITION_END, "rendition");

string = XmStringConcat(tmp1, string);
XmStringFree(tmp1);
string = XmStringConcat(string, tmp2);
XmStringFree(tmp2);

Display of the new string will use a composite rendition formed through a merge of the pre-existing rendition with the rendition rendition. See section 9.2.3 on render tables for the rules of merging renditions.

Motif provides two different functions to read the contents of a compound string.

The XmStringGetNextTriple function is the most basic of the compound string readers. Given an initialized "compound string context," the function returns successive of the nominated compound string on successive calls. Use XmStringPeekNextTriple to determine the type of the next component without reading it, and without advancing the counter. A subsequent call to XmStringGetNextTriple would return the value of the component just peeked at.

In order to read a compound string with XmStringGetNextTriple, or to peek forward with XmStringPeekNextTriple, a program must first establish a "compound string context" to use. This is just a state structure used to keep track of how far into a compound string the program has read.

Motif provides the XmStringInitContext function to read a compound string and allocate a buffer long enough to handle any of its components. As with all of the other Motif calls that allocate memory, the calling application is responsible for doing its own memory management. Motif provides a function, XmStringFreeContext, to free the memory associated with the context.

Two convenient functions are also provided to do two commonly needed tasks: searching for a substring and counting the lines of text.

The XmStringHasSubString function takes two compound strings, the target string and the search string, as its arguments. The function returns True if the search string (which can only have one text component) is found in the target string.

The XmStringLineCount function simply returns the number of separators found in the input compound string, plus one. Since the separators usually map to a line terminator, this would be the number of lines in the displayed compound string.

In most cases, a programmer need not worry about displaying a compound string. If the string is submitted to a widget, that widget is responsible for figuring out how to draw its own labels and text. Therefore, the functions described in this section are not used by most Motif applications. However, if a programmer chooses to write a widget, these functions will be quite useful.

The XmStringDraw function draws a compound string in a specified window, in a specified display. The XmStringDrawImage function is nearly identical, except that, when drawing the string, it uses both the foreground and background bits of each character, where XmStringDraw only uses the specified foreground color.

XmStringDrawUnderline is the same as XmStringDraw, with the addition of one more argument, also a compound string. If this compound string matches any pattern in the compound string to be drawn, that part of the drawn string will be underlined.

In order to draw a string properly, it may be necessary to predict the drawn string's dimensions.

The XmStringExtent function returns the height and width of the smallest rectangle that could enclose the given compound string. The XmStringHeight and XmStringWidth functions return only the height or width of the string. Use XmStringBaseLine to find the number of pixels between the tallest possible letter and the baseline of the first line of text in the input compound string.

Motif now provides support for a table of compound strings. This is simply an array of compound strings, typically to be used to display or accept tabular information. Motif provides functions for creating and manipulating such arrays.

The XmStringToXmStringTable function takes a single compound string as its input, along with a compound string component, break_component. Upon return, the string is broken up, wherever the specified break_component appears, and the function returns an array (table) of the resulting compound strings. The component marking the breaks will not appear in the output table.

Use XmStringTableToXmString to convert a table of compound strings back into a single compound string. This function also uses a break_component argument, which it inserts into the resulting compound string between each of the elements of the input table.

The following two functions convert regular text to a table of compound strings and back again. They both use the parsing capabilities of Motif, which are described in section 9.4.

The XmStringTableParseStringArray function accepts an array of simple text strings, calls XmStringParseString on each one with the given parse table, and puts the result into a table of compound strings. The XmStringTableUnparse function also uses an input parse table, to convert the elements of the input compound string table back into regular text strings. See section 9.4 for more information about parsing and parse tables.

A rendition is neither a widget nor a gadget. However, the style used to specify resources for widgets and gadgets is a simple and familiar way to set data values, and it has been implemented for renditions well. To change the foreground color for a rendition, the application programmer must set a "resource" called XmNrenditionForeground for that rendition, in a manner identical to that of a programmer changing a color resource for some widget. For a complete description of the XmRendition resource set, see the XmRendition page in the Motif Programmer's Reference.

XmRenditionCreate takes an argument list (use XtSetArg to create the list) of resource name and value pairs as input, and returns a rendition, which can then be entered into the render table.

The following code fragment establishes a rendition that would display a compound string in the 8x16 font, in blue, and underlined with a single line.

int n;
XmRendition Rendition;
XmStringTag RenditionTag;

   XtVaGetValues(parent, XmNcolormap, &cmap, NULL);
   if ( XAllocNamedColor(XtDisplay(parent), cmap, "blue", &color, &unused))
    {
      pixel_color = color.pixel;
    } else {
      pixel_color = XmUNSPECIFIED_PIXEL;
    }

   n = 0;
   XtSetArg( args[n], XmNrenditionForeground, pixel_color); n++;
   XtSetArg( args[n], XmNfontName, "8x16" ); n++;
   XtSetArg( args[n], XmNfontType, XmFONT_IS_FONT ); n++;
   XtSetArg( args[n], XmNunderlineType, XmSINGLE_LINE );  n++;
   RenditionTag = (XmStringTag) "Rendition1";
   Rendition = XmRenditionCreate( parent, RenditionTag, args, n );

These functions are used to read and modify a rendition.

The XmRenditionUpdate function works in a similar way to XmRenditionCreate, merging the given argument list into the definition of the rendition. Resources in the input ArgList that were XmAS_IS will be set to the given values, and resources in the input ArgList that were already set will be reset to the new value. Resources not in the input ArgList will remain unchanged. The XmRenditionRetrieve function also uses an ArgList, but the user must specify the address (instead of the value) of each resource value to be returned.

The following code retrieves a rendition. If the rendition was underlined, the underline is removed. If the rendition was not underlined, the underline is inserted.

int n;
unsigned char underline;

n = 0;
XtSetArg( args[n], XmNunderlineType, &underline ); n++;
XmRenditionRetrieve( Rendition, args, n );

if (( underline == XmAS_IS) || ( underline == XmNO_LINE ))
     underline = XmSINGLE_LINE;

else if ( underline == XmSINGLE_LINE)
      underline = XmNO_LINE;

n = 0;
XtSetArg( args[n], XmNunderlineType, underline ); n++;
XmRenditionUpdate( Rendition, args, n );

The modified rendition must still be added to the render table, and the modified render table sent back to the widget, before it is accessible to a widget needing to display a compound string.

The XmRenditionCreate function allocates memory for the created rendition structure. The application calling this function is responsible for maintaining its own memory management scheme. Use XmRenditionFree to recover memory space allocated to a rendition when the application is done with it. The application may dispose of the rendition as soon as it has been added to a render table.

A collection of renditions, each identified by a rendition "tag" (type XmStringTag), constitutes a render table (type XmRenderTable). Each rendition contains specifications describing how to display text, including the font, the color, the tab stops, and other information.

A compound string can specify its rendition in more than one way. The typical way is simply for each compound string text component to be associated with a rendition tag, which is matched with the entry in the render table with the same tag. However, an application may use the default rendition for the current locale (tag=_MOTIF_DEFAULT_LOCALE). Alternatively, older applications may specify a charset tag, which will identify a font to use to display some text. The charset and the locale options may not both be specified, but both may exist with one or more rendition tags.

Renditions are accumulated as a compound string is read. If there have been three rendition begin tags and only one corresponding rendition end tag preceding a particular segment of text, then there are two renditions associated with that text. The last rendition specified that is still in effect is the primary rendition. If a segment of text is associated with more than one rendition, and if there are unspecified values in the primary rendition, the widget must create an effective rendition for that segment. This is formed by using the previous (active) rendition to fill in the unspecified values of the primary rendition. If this effective rendition still has unspecified values, then the next active rendition back is used, and so on. Finally, if the resulting rendition still has resources with unspecified values and the segment has a locale or charset tag (these are optional and mutually exclusive) this tag is matched with a rendition in the render table, and the missing rendition values are filled in from that entry.

If no matching rendition is found for a particular tag, then the XmNoRenditionCallback of the XmDisplay object is called and the render table is searched again for that tag.

If the resulting rendition does not specify a font or fontset, then for segments whose text type is XmCHARSET_TEXT, the render table will be searched for a rendition tagged with XmFONTLIST_DEFAULT_TAG, and if a matching rendition is found, it will be merged into the current rendition. If the resulting rendition contains no font or fontset, the XmNnoFontCallback will be called with the default rendition and "" as the font name. If no rendition matches or no font was found after the callback, then the first rendition in the render table will be merged into the current rendition. If this rendition still has no font, then the segment will not be rendered and a warning will be issued.

For segments whose text type is XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT, the render table will be searched for a rendition tagged with _MOTIF_DEFAULT_LOCALE, and if a matching rendition is found, it will be merged into the current rendition. If the resulting rendition contains no font, the XmNnoFontCallback will be called with the default rendition and "" as the font name. If no rendition matches or no font was found after the callback, then the segment will not be rendered and a warning will be issued.

For example, imagine a render table containing three renditions. One belongs to the default locale, and has the tag _MOTIF_DEFAULT_LOCALE, while the other two renditions are called fred and susan. Further suppose the default locale rendition specifies a font, but the foreground and background color resources are XmUNSPECIFIED_PIXEL. Rendition fred specifies the foreground color as red, but the background field is XmUNSPECIFIED_PIXEL, and rendition susan gives blue for the foreground and purple for the background. Following is a schematic representation of such a render table:

_MOTIF_DEFAULT_LOCALE:
      XmNfontName:   variable
      XmNfontType:   XmFONT_IS_FONT
      XmNrenditionForeground: XmUNSPECIFIED_PIXEL
      XmNrenditionBackground: XmUNSPECIFIED_PIXEL
      ...
fred:
      XmNfontName:   XmAS_IS
      XmNfontType:   XmAS_IS
      XmNrenditionForeground: red
      XmNrenditionBackground: XmUNSPECIFIED_PIXEL
      ...
susan:
      XmNfontName:   XmAS_IS
      XmNfontType:   XmAS_IS
      XmNrenditionForeground: blue
      XmNrenditionBackground: purple
      ...

A text component associated with the fred and susan tags (in that order) will have red type on a purple background. But a component using susan and fred will have blue type on a purple background. Both components will use the font corresponding to the locale rendition, variable in this case. Note that the order of the renditions in the merge sequence is the opposite of the order in which the corresponding XmSTRING_COMPONENT_RENDITION_BEGIN components appear in the compound string. That is, the primary rendition for some piece of text corresponds to the last rendition component read.

If the search of the render table results in no font or fontset, then if there is a rendition in the render table with a tag of _MOTIF_DEFAULT_LOCALE, and if that rendition specifies a font, then that font will be used. If no font or fontset is specified at this point, the text component will not be rendered and a warning message will be displayed.

n = 0;
XtSetArg( args[n], XmNtopAttachment, XmATTACH_FORM ); n++;
XtSetArg( args[n], XmNwidth, LIST_WIDTH ); n++;
XtSetArg( args[n], XmNvisibleItemCount, NUM_ITEMS ); n++;
List = XmCreateList( Manager, "List", args, n );
XtManageChild(List);

n = 0;
XtSetArg( args[n], XmNfontName, "fixed" ); n++;
XtSetArg( args[n], XmNfontType, XmFONT_IS_FONT ); n++;
XtSetArg( args[n], XmNunderlineType, XmNO_LINE );  n++;
Renditions[0] = XmRenditionCreate( List, (XmStringTag)tags[0],
                  args, n );

n = 0;
XtSetArg( args[n], XmNfontName, XmAS_IS ); n++;
XtSetArg( args[n], XmNfontType, XmFONT_IS_FONT ); n++;
XtSetArg( args[n], XmNunderlineType, XmSINGLE_LINE );  n++;
Renditions[1] = XmRenditionCreate( List, (XmStringTag)tags[1],
                  args, n );

n = 0;
XtSetArg( args[n], XmNfontName, "variable" ); n++;
XtSetArg( args[n], XmNfontType, XmFONT_IS_FONT ); n++;
XtSetArg( args[n], XmNunderlineType, XmDOUBLE_LINE );  n++;
Renditions[2] = XmRenditionCreate( List, (XmStringTag)tags[2],
                  args, n );

RenderTable =
    XmRenderTableAddRenditions( NULL, Renditions, 3,
                            XmREPLACE );

n = 0;
XtSetArg( args[n], XmNrenderTable, RenderTable ); n++;
XtSetValues( List, args, n );

int n;
XmRendition Rendition;

     Rendition = XmRenderTableGetRenditions(RenderTable,
                      (XmStringTag) "variable", 1);

     n = 0;
     XtSetArg( args[n], XmNstrikethruType, XmSINGLE_LINE ); n++;
     XmRenditionUpdate( Rendition, args, n );

     XmRenderTableAddRenditions(RenderTable, Rendition, 1,
                      XmMERGE_NEW);

     n = 0;
     XtSetArg( args[n], XmNrenderTable, RenderTable ); n++;
     XtSetValues( List, args, n );

resource_spec: [ tag [, tag ]* ]

resource_spec [*|.] rendition[*|.] resource_name:value

*List.renderTable: green, variable
*List.renderTable.green.renditionForeground: Green
*List.renderTable.green.fontName: AS_IS
*List.renderTable.variable.underlineType: SINGLE_LINE
*List.renderTable.variable.renditionForeground: Red
*List.renderTable.variable.fontName: variable
*List.renderTable.variable.fontType: FONT_IS_FONT
*List.renderTable.renditionForegound: black
*List.renderTable.fontName: fixed
*List.renderTable.fontType: FONT_IS_FONT
*List.renderTable.variable.underlineType: NO_LINE
*List.renderTable*tabList: 1in, +1.5in, +3in

typedef struct
{
        int     reason;
        XEvent  *event;
        XmRendition     rendition;
        char    *font_name;
        XmRenderTable   render_table;
        XmStringTag     tag;
}XmDisplayCallbackStruct;

The font list paradigm of Motif 1 has been supplanted by renditions and render tables. The font list management routines are provided only for backward compatibility with older applications written. They should not be used for new applications, which can use renditions and render tables for the same effect. Following is a list of the remaining font list management functions:

The following functions are used to create a single tab stop.

Use the XmTabCreate convenience function to create a tab stop from a tab value, the tab units, and the offset model. To specify the offset model, there are the defined constants XmABSOLUTE and XmRELATIVE. Note that the tab value must be a positive number, and that, if a tab stop would cause a text component to overwrite the previous component, the x position of the component will be moved (the tab is ignored) to follow the first component. There is also an input argument to XmTabCreate to define the alignment of the text relative to the tab stop. Presently, XmALIGNMENT_BEGINNING is the only valid value.

Tab stops may be measured in any of the following units:

Font units are calculated from the dimensions of the font used. Horizontal font units (used in horizontal tabs) are calculated as follows:

The XmTabGetValues function separates a tab stop into its constituent parts, as outlined above, and the XmTabSetValue function is used to change only the value field, or the actual measurement of an existing tab stop. XmTabSetValue has no effect on the units, the offset model, or the alignment of a tab stop.

Motif provides convenience functions to create tab lists in an application.

The XmTabListInsertTabs function adds one or more XmTabs to an already existing XmTabList. Use it with an empty input tab list to create a tab list.

The XmStringTableProposeTablist function takes an XmStringTable structure containing tabbed compound strings and, using its rendition information and input about the desired padding between columns, returns a proposed tab list. This tab list is defined so that, if used to render the strings in the table, it would cause the strings to line up in columns with no overlap and with the specified amount of padding between the widest item in each column and the start of the next column. Each tab in the tab list would have the same unit type, offset model, and alignment type, specified on input.

Tab stops and tab lists may also be specified in a resource file. To create a tab stop in a resource file, use the following syntax:

resource_spec: tab [, tab ]*

The resource value string consists of one or more tabs separated by commas. Each tab identifies the value of the tab, the unit type, and whether the offset is relative or absolute. The tab stop specification uses the following syntax:

tab = [ + ]  float [ units ]

The tab contains a decimal number and an indication of the units to be used. If no units are specified, the default unit is pixels. The presence or absence of a sign indicates, respectively, a relative offset or an absolute offset model. A relative tab stop is measured from the previous tab stop in the list, while an absolute tab stop is measured from the left margin (or the right margin if the layout direction is right-to-left).

For example, the following line of a resource file sets a tab list for a rendition (rend1) in a render table (render_table) used by a widget called List. It specifies a tab list consisting of a 1-inch absolute tab followed by a 1-inch relative tab (equivalent to a 2-inch absolute tab, unless and until a third tab is inserted between the two):

*List.render_table.rend1.tabList: 1in, +1in

The recognized units and their abbreviations include:

See section 9.3.1 for more information about font units.

These are the functions provided to maintain and modify a tab list:

To remove tabs from a list, a program may use either XmTabListRemoveTabs, XmTabListCopy, or XmTabListReplacePositions. The first of these actually deletes the indicated XmTab entries from the list. The second and third functions create a new XmTabList using a subset of the original list. For XmTabListCopy, the subset must be in order in the original list, while XmTabListReplacePositions can pick an assortment of tab stops out of the old list to put in the new one.

The XmTabListGetTab function returns a copy of the tab stop at the indicated position in the list, and XmTabListTabCount simply returns the number of tab stops in a given tab list.

The functions that create tabs and tab lists allocate memory in which to put them. When an application is finished with the tabs, it should use XmTabFree and XmTabListFree to free that memory for other uses.

Though the parse mapping is at heart nothing more than the text/compound string pairs, Motif stores each parse mapping with resources that indicate how the parsing is to proceed. Note that these are not widget resources, but the widget resource model provides a convenient way to specify and recall parse mapping instructions.

Following this model, an application uses the XtSetArg function to build a resource-style argument list to submit to the XmParseMappingCreate, XmParseMappingGetValues, or XmParseMappingSetValues in the same manner that would be used to create or change the resource values of some widget.

The parse mapping "resources" are outlined briefly below. For more information about the XmParseMapping data type and its resources, please see the Motif Programmer's Reference.

XmIncludeStatus (*XmParseProc)(
        XtPointer       *text_in_out,
        XtPointer       text_end,
        XmTextType      type,
        XmStringTag     tag,
        XmParseMapping  entry,
        int     pattern_length,
        XmString        *str_include,
        XtPointer       call_data)

The following functions use a parse table to translate text into the compound string format and the reverse.

To use a parse table, send it and a companion text string to the XmStringParseText function. This function also accepts a pointer to data that may be passed to a parse procedure, if one exists. The function will walk through the input text string, copying characters from it into a compound string; when it finds a pattern (specified by XmNpattern in the parse mappings) to match a pattern in the input parse table, it will not copy the pattern, but write the corresponding compound string (indicated by XmNsubstitute in the parse mapping) to the output XmString.

In the event it is desirable to translate a compound string back into a text string, the XmStringUnparse function is provided. This provides the precise converse to the XmStringParseText function, stepping through the input compound string and substituting text patterns for XmString components that match the XmNsubstitute resources in the parse table. If there is no parse procedure nominated in the parse table, the XmStringUnparse function called on the output of the XmStringParseText function will equal the input of XmStringParseText. A compound string created with a parse table that includes a parse procedure will not be correctly translated into simple text by a call to XmStringUnparse.

The routines that create parse mappings allocate memory in which to store those mappings. It is the responsibility of the application, however, to free that memory when the mappings and tables are no longer needed. Use XmParseMappingFree and XmParseTableFree to free the memory for other uses.

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

UIL recognizes a number of keywords specifying character sets. UIL associates parsing rules, including parsing direction and whether characters have 8 or 16 bits, for each character set it recognizes. It is also possible to define a character set by using the UIL CHARACTER_SET function.

The syntax of a string literal is one of the following:

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

For each syntax, the character set of the string is determined as follows:

Note that certain predefined escape sequences, beginning with a backslash (), may appear in string literals, with these exceptions:

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:

However, if you specify an enumerated constant from the following group, then you must supply a string as the second argument:

If XmSTRING_COMPONENT_DIRECTION is the first argument, the second argument must be an XmStringDirection enumerated constant. Finally, if you specify XmSTRING_COMPONENT_LAYOUT_PUSH as the first argument, then you must specify an XmDirection enumerated constant as the second argument.

For more information on UIL string and compound string syntax, see the UIL(5X) reference page in the Motif Programmer's Reference.

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.