Volume 6A: Motif Programming Manual

Manual, Motif Edition. The string "Push Me" is the string value; the length of the string, including the

NULL−terminating byte, is 8.

The XtVaTypedArg method for specifying a compound string resource is only a programmatic convenience; it does

not save time or improve performance. The three−step process of creating, setting, and freeing the compound string

still takes place, but it happens within Motif's compound string resource converter. Using automatic conversion is

actually slower than converting a string using XmStringCreateLocalized(). However, unless you are creating

hundreds of strings, the difference is negligible. The convenience and elegance of the XtVaTypedArg method may

be worth the performance tradeoff.

The reason most of the examples in this book do not make use of the feature is that we are trying to demonstrate good

programming techniques tuned to a large−scale, production−size, and quality application. Using the XtVaTypedArg

method for compound strings is painfully slow when repeated over hundreds of Labels, PushButtons, Lists, and other

widgets. The XtVaTypedArg method is perfectly reasonable for converting other types of resources, however. If

you are converting a lot of values from one type to another, it is in your own best interest to evaluate the conversion

process yourself by testing the automatic versus the manual conversion methods.

20.2.2 Font List Tags

Motif provides two different compound string creation routines that allow you to specify a tag used to associate the

compound string with a font or a font set. This tag is a programmer−specified identifier that enables a Motif widget to

pick its font from a list of fonts at run−time. In Motif 1.1, the font list tag was referred to as a character set, but strictly

speaking, it does not specify a character set.

The XmStringCreate() and XmStringCreateLtoR() routines allow you to specify a font list tag. These

routines take the following form:

XmString

XmStringCreate(text, tag)

char *text;

char *tag;

XmString

XmStringCreateLtoR(text, tag)

char *text;

char *tag;

Both of these routines create and allocate a new compound string and associate the tag parameter with that string. As

with any compound string, be sure to free it with XmStringFree() when you are done using it.

XmStringCreate() creates a compound string that has no specified direction. The default direction of a string

may be taken from the XmNstringDirection resource. This resource is defined by manager widgets; it specifies

the string direction for all the children of the manager. If the default direction is not adequate,

XmStringDirectionCreate() can be used to create a compound string with an explicit direction, as we'll

discuss shortly.

XmStringCreateLtoR() creates a compound string in which the direction is hard−coded as left−to−right. Motif

also defines the XmStringLtoRCreate() routine; its functionality is identical to XmStringCreateLtoR().

This function is also useful for converting newline−separated strings into

compound strings, as we explain later in this section. Unfortunately, Motif

does not provide a corresponding right−to−left compound string creation

function. If you need such a routine, it is not that difficult to write one.

20 Compound Strings 20.2.2 Font List Tags

566

The actual font or font set that is associated with the compound string is dependent on the widget that renders the

string. Every Motif widget that displays text has an XmNfontList resource. This resource specifies a list of fonts

and/or font sets for the widget; each entry in the list may have an optional tag associated with it. For example, a

resource file might specify a font list as follows:

*fontList: −*−courier−*−r−*−−*−120−*=TAG1, −*−courier−*−r−*−−*−140−*=TAG2, −*−courier−*−r−*−−*−180−*=TAG3

At run−time, the compound string is rendered using the first font or font set in the widget's font list that matches the

font list tag specified in the compound string creation function. In Motif 1.2, the compound string rendering functions

use the new X11R5 text output functions, so compound strings are displayed appropriately for the current locale. If

Motif cannot find a match, the compound string is rendered using the first item in the widget's font list, regardless of

its tag. This loose binding between the compound string and the font or font set used to render it is useful in a number

of ways:

The same compound string can be rendered using different fonts in different widgets simply by specifying a

different font list for each widget. For example:

•

*XmPushButton.fontList: −*−courier−*−r−*−−*−120−*=TAG1

*XmPushButtonGadget.fontList: −*−courier−*−r−*−−*−120−*=TAG1

*XmList.fontList: −*−helvetica−*−r−*−−*−120−*=TAG1

These resource settings indicate that TAG1 maps to a 12−point Courier font for all PushButton widgets and

gadgets and maps to a 12−point Helvetica font for all List widgets.

Compound strings rendered in different fonts can be concatenated to create a multi−font compound string.

The font for each segment is selected from the widget's font list by means of a unique tag.

•

Compound strings can be language−independent, with the tag used to select between fonts with different

character set encodings. This is the least common use for compound strings, and as of X11R5, it is no longer

needed to support internationalized text output.

•

the source code demonstrates how a compound string can be rendered using different fonts in different PushButton

widgets. XtSetLanguageProc() is only available in X11R5; there is no corresponding function in X11R4.

XmStringCreateLocalized() is only available in Motif 1.2; XmStringCreateSimple() is the

corresponding function in Motif 1.1.

/* string.c −− create a compound string with the "MY_TAG" tag.

* The tag defaults to the "9x15" font. Create three pushbuttons:

* pb1, pb2, and pb3. The user can specify resources so that each of the

* widgets has a different font associated with the "MY_TAG" tag

* specified in the compound string.

*/

#include <Xm/RowColumn.h>

#include <Xm/PushBG.h>

String fallbacks[] = { "*fontList:9x15=MY_TAG", NULL };

main(argc, argv)

int argc;

char *argv[];

{

Widget toplevel, rowcol;

XtAppContext app;

XmString text;

Display *dpy;

XtSetLanguageProc (NULL, NULL, NULL);

20 Compound Strings 20.2.2 Font List Tags

567

toplevel = XtVaAppInitialize (&app, "String", NULL, 0,

&argc, argv, fallbacks, NULL);

text = XmStringCreate ("Testing, testing...", "MY_TAG");

rowcol = XtVaCreateWidget ("rowcol",

xmRowColumnWidgetClass, toplevel,

NULL);

XtVaCreateManagedWidget ("pb1",

xmPushButtonGadgetClass, rowcol,

XmNlabelString, text,

NULL);

XtVaCreateManagedWidget ("pb2",

xmPushButtonGadgetClass, rowcol,

XmNlabelString, text,

NULL);

XtVaCreateManagedWidget ("pb3",

xmPushButtonGadgetClass, rowcol,

XmNlabelString, text,

NULL);

XmStringFree (text);

XtManageChild (rowcol);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

This simple program creates three PushButton gadgets that all use the same compound string for their labels. The font

list tag MY_TAG is associated with the 9x15 font in the fallback resources. By default, all of the buttons look the

same, as shown in the figure.

Output of string.c

However, the figure shows what happens to the output when the following resources are specified:

*pb1.fontList: −*−courier−*−r−*−−*−120−*=MY_TAG

*pb2.fontList: −*−courier−*−r−*−−*−140−*=MY_TAG

*pb3.fontList: −*−courier−*−r−*−−*−180−*=MY_TAG

20 Compound Strings 20.2.2 Font List Tags

568

Output of string.c with font list resources set

The font associated with MY_TAG for each of the PushButtons is different, so the compound string for each one is

rendered in a different font. This case isn't really that exciting, however, because we could have achieved the same

effect without specifying a font list tag for each font. Since each font list only contains one font, Motif has no choice

but to display the compound string using that font. The following resource specification creates the output shown in

the figure:

*pb1.fontList: −*−courier−*−r−*−−*−120−*

*pb2.fontList: fixed,−*−courier−*−r−*−−*−140−*=ANOTHER_TAG

*pb3.fontList: fixed,−*−courier−*−r−*−−*−180−*=MY_TAG

Output of string.c with multiple font list resources set

In this case, the compound string in the first PushButton uses a 12−point Courier font, since that is the only font in the

font list. The second PushButton uses the fixed font because it is first in the list and neither of the fonts has

MY_TAG associated with it. The third button uses the 18−point Courier font associated with MY_TAG. In Motif 1.2,

the constant XmFONTLIST_DEFAULT_TAG is used to tag compound strings that are created in the encoding of the

current locale. When a compound string is created using XmStringCreateLocalized(), this tag is used. The

equivalent compound string can also be created using XmStringCreate() with the tag explicitly set to

XmFONTLIST_DEFAULT_TAG. Just as with other font list tags, Motif looks for a font or font set with a matching tag

when it renders the compound string. This font list tag is used to identify the font or font set that is correct for the

encoding of the current locale. If a font list does not use XmFONTLIST_DEFAULT_TAG, the first item in the font list

is automatically associated with this tag.

An internationalized application should only use XmFONTLIST_DEFAULT_TAG in font lists to ensure that

compound strings are rendered correctly for the current locale. However, it is possible to use explicit font list tags for

locale−specific text. Explicit tags are necessary when an application wants to display compound strings using different

point sizes or type styles. In this case, the compound string and the font list associated with it need to use the same tag,

and the tag should be mapped to XmFONTLIST_DEFAULT_TAG using XmRegisterSegmentEncoding().

20 Compound Strings 20.2.2 Font List Tags

569