Volume 6A: Motif Programming Manual

XmFontListEntry

XmFontListNextEntry(context)

XmFontContext context;

This routine cycles through all of the font list entries in the font list. The first call returns the first entry in the font list;

repeated calls using the same font context access successive entries. Since the XmFontListEntry type is also

opaque, you have to use XmFontListEntryGetFont() and XmFontListEntryGetTag() to retrieve the

actual font or font set and tag for the font list entry. These routines take the following form:

XtPointer

XmFontListEntryGetFont(entry, type_return)

XmFontListEntry entry;

XmFontType *type_return;

char *

XmFontListEntryGetTag(entry)

XmFontListEntry entry;

XmFontListEntryGetFont() returns an XFontStruct or an XFontSet depending on the value of

type_return. The routine does not copy the data structure, so the application must not free it.

XmFontListEntryGetTag() retrieves the tag for the font list entry. This routine allocates storage for the tag, so

the application must free it.

In Motif 1.1, you call XmFontListGetNextFont() to cycle through the fonts in a font list. This routine has the

following form:

Boolean

XmFontListGetNextFont(context, charset, font)

XmFontContext context;

XmStringCharSet *charset;

XFontStruct **font;

If the function returns True, the character set and font pointers are set to the appropriate values. The charset

returned is a pointer to allocated data that must be freed when no longer needed. The value for font points to the

actual XFontStruct data used in the font list, so it must not be freed. If the end of the list has been reached, the

function returns False. This routine exists for backwards compatibility and should not be used with Motif 1.2.

When you are done querying the font list, you need to free the font context using

XmFontListFreeFontContext(), which takes the following form:

void

XmFontListFreeFontContext(context)

XmFontListFontContext context;

If you are searching through a font list and need to back up, you must restart the entire process by freeing the current

font context and creating a new one.

20.5 Rendering Compound Strings

Motif always renders compound strings automatically within its widgets, so you should never find yourself in a

situation where you need to render a compound string manually. However, if you are writing your own widget, you

may need to incorporate the same type of functionality. Motif provides three functions that render compound strings:

20 Compound Strings 20.5 Rendering Compound Strings

584

XmStringDraw()

XmStringDrawImage()

XmStringDrawUnderline()

In Motif 1.2, all of these routines use the X11R5 text output routines when necessary, to ensure that the text is

rendered correctly for the current locale.

The most basic rendering function is XmStringDraw(), which takes the following form:

XmStringDraw(display, window, fontlist, string, gc, x, y, width,

alignment, layout_direction, clip);

Display *display;

Window window;

XmFontList fontlist;

XmString string;

GC gc;

Position x, y;

Dimension width;

unsigned char alignment;

unsigned char layout_direction;

XRectangle *clip;

As you can see, the function requires a great deal of information to actually render the string. If you are rendering into

a widget, you can specify the display and window using XtWindow() and XtDisplay(). Since a gadget does

not have a window, you must use XtWindowOfObject() with a gadget. The fontlist parameter can be

constructed using any of the functions described in Section #sfontlist, or you can retrieve a font list from a widget

using XtVaGetValues().

The function also requires a graphics context (GC) so that certain rendering attributes such as color can be applied. A

graphics context is generally not available through a widget, so you have to get one at the Xlib level. If you are

writing your own widget, you can probably use a GC that is cached by Xt and returned by XtGetGC() (see

Volume Four, X Toolkit Intrinsics Programming Manual). Also, if you are writing your own widget, you may want

to consider exposing the GC to the programmer in the form of a resource.

The x, y, and width parameters specify the coordinates and width of the rectangle that contains the compound

string. The width parameter is used only for alignment purposes. There is no height parameter because the font list

may specify fonts that are unknown in size and whose heights are too variable. The clip parameter defines the

drawing boundary; you can pass NULL to indicate that the rendering should not be clipped.

The alignment parameter can be set to one of the following values:

XmALIGNMENT_BEGINNING

XmALIGNMENT_CENTER

XmALIGNMENT_END

The value identifies the justification for the text. The effect of the value is modified by the value of the

layout_direction parameter, which can be set to XmSTRING_DIRECTION_L_TO_R or

XmSTRING_DIRECTION_R_TO_L.

The function XmStringDrawImage() is to XmStringDraw() as XDrawString() is to

XDrawImageString(). The difference is that the image routines overwrite the background even in places where

the font does not set bits in the character image, while the other routines only render foreground pixels.

20 Compound Strings 20.5 Rendering Compound Strings

585