[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide



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

  1. A string expression consists of two or more literals with different character sets or writing directions, or

  2. The literal or expression in question is used as a value that has a compound string data type (such as the value of a resource whose data type is XmString).

    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:

    1. For a string declared as ' string', the character set is the code set component of the LANG environment variable if it is set in the UIL compilation environment, or the value of XmFALLBACK_CHARSET if LANG is not set or has no code set. By default, the value of XmFALLBACK_CHARSET is ISO8859-1, but vendors may supply different values.

    2. For a string declared as # char_set" string", the character set is char_set. If the char_set in a string specified in this form is not a built-in charset, and is not a user-defined charset, the charset of the string will be set to XmFONTLIST_DEFAULT_TAG, and an informational message will be issued to the user to note that this substitution has been made.

    3. For a string declared as " string", the character set depends on whether or not the module has a character_set clause and on whether or not the UIL compiler's use_setlocale_flag is set:

      1. If the module has a character_set clause, the character set is the one specified in that clause.

      2. If the module has no character_set clause but the uil command was invoked with the -s option, or the Uil function was invoked with the use_setlocale_flag set, UIL calls setlocale and parses the string in the current locale. The character set of the resulting string is XmFONTLIST_DEFAULT_TAG.

      3. If the module has no character_set clause and the uil command was invoked without the -s option, or the Uil function was invoked without the use_setlocale_flag, the character set is the code set component of the LANG environment variable if it is set in the UIL compilation environment; if LANG is not set or has no code set, the character set is the value of XmFALLBACK_CHARSET.

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

        1. A string in single quotes can span multiple lines, with each newline escaped by a backslash. A string in double quotes cannot span multiple lines.

        2. Escape sequences are processed literally inside a string that is parsed in the current locale (a localized string).

        3. 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:

          1. XmSTRING_COMPONENT_SEPARATOR

          2. XmSTRING_COMPONENT_LAYOUT_POP

          3. XmSTRING_COMPONENT_TAB

          4. XmSTRING_COMPONENT_LOCALE

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

            1. XmSTRING_COMPONENT_TAG

            2. XmSTRING_COMPONENT_TEXT

            3. XmSTRING_COMPONENT_LOCALE_TEXT

            4. XmSTRING_COMPONENT_WIDECHAR_TEXT

            5. XmSTRING_COMPONENT_RENDITION_BEGIN

            6. XmSTRING_COMPONENT_RENDITION_END

              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.

            7. 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.


              [ Previous | Next | Contents | Glossary | Home | Search ]