Volume 6A: Motif Programming Manual

Like imported widgets, you need to make sure that the type of an imported variable matches the type in its

definition. If they do not match, there's a good chance you'll run into problems when you create a widget that

references the imported value.

25.3.2 Fetching Values

As we mentioned earlier, an application can read all types of exported variables from a UIL module, with the

exception of character_set and color_table values. You retrieve most exported variables using

MrmFetchLiteral(). However, pixmap and color are retrieved with special routines that we'll describe later.

Fetching values from a UIL module is useful for obtaining internationalized strings or widget resource values that

change dynamically based on the state of the program. MrmFetchLiteral() takes the following form:

Cardinal

MrmFetchLiteral(hierarchy, name, display, value_return, type_return)

MrmHierarchy hierarchy;

String name;

Display *display;

XtPointer *value_return;

MrmCode *type_return)

Mrm looks for the variable specified by name in the UID files associated with the hierarchy parameter. The files

are searched in the same order as they appeared in the array of files passed to

MrmOpenHierarchyPerDisplay(), so if two variables with the same name occur in separate files, you'll get

the value from the first file in the list. When a value is fetched successfully, the function returns MrmSUCCESS, fills

in value_return with a pointer to the value, and fills in type_return with a constant from

<Mrm/MrmPublic.h> indicating the type of value. If MrmFetchLiteral() cannot find the variable in any of the

UID files, it returns MrmNOT_FOUND.

The value_return parameter usually contains a pointer to the value that you fetched, even for types such as

integer and boolean. You can check the type by examining type_return. lists each UIL data type, the type

of the value placed in value_return, and the associated type identifier placed in type_return.

tab(@), linesize(2); lp9 | lp9 | lp9 | lp9 lp8w(1i) | lp8 | lp8 | lp8.

Type@Mrm Return Type@C Return Type@Free Routine

_

asciz_table@MrmRtypeChar8Vector@String*@XtFree()

boolean@MrmRtypeBoolean@int*@XtFree()

class_rec_name@MrmRtypeClassRecName@WidgetClass@N/A

color@N/A@Pixel@XFreeColors()

compound_string@MrmRtypeCString@XmString@XmStringFree() T{ compound_

string_table T}@MrmRtypeCStringVector@XmStringTable@XtFree()

float@MrmRtypeFloat@double*@XtFree() font@MrmRtypeFont@XFontStruct*@N/A

fontset@MrmRtypeFontSet@XFontSet@N/A

font_table@MrmRtypeFontList@XmFontList@XmFonyListFree()

icon@N/A@Pixmap@XFreePixmap() integer@MrmRtypeInteger@int*@XtFree()

integer_table@MrmRtypeIntegerVector@int*@XtFree()

keysym@MrmRtypeKeysym@char@N/A rgb@N/A@Pixel@XFreeColors()

single_float@MrmRtypeSingleFloat@float*@XtFree()

string@MrmRtypeChar8@String@XtFree()

translation_table@MrmRtypeTransTable@XtTranslations@N/A

wide_character@MrmRtypeWideCharacter@wchar_t*@XtFree()

xbitmapfile@N/A@Pixmap@XFreePixmap() _ Mrm allocates an int for boolean values, so you cannot

25 Creating a User Interface With UIL 25.3.2 Fetching Values

671

use the Xt Boolean type because on some machines it is defined as a char. However, you can still assign the int

that is returned to a Boolean. The specialized routines MrmFetchBitmapLiteral(),

MrmFetchColorLiteral(), and MrmFetchIconLiteral() do not have an MrmType argument. If the

named value is not the right type, a status of MrmWRONG_TYPE is returned. Mrm allocates storage for most of the

values returned by MrmFetchLiteral(). The application is responsible for freeing the storage; it uses the routine

indicated in However, note that you should not free font or fontset values because they are cached by Mrm and

are reused as needed. There is no need to free class_rec_name or keysym values because they are returned by

value, and you cannot free translation_table -values because Xt does not provide a way to free them. In

addition, Mrm allocates asciz_string_table, compound_string_table, and integer_table values in

a single chunk of memory, which means you should free them with a single call, rather than freeing the individual

elements.

The following code fragment illustrates using MrmFetchLiteral() to fetch a string and an integer:

extern MrmHierarchy hierarchy;

extern Widget toplevel;

Cardinal status;

MrmCode type;

String animal;

int *count;

status = MrmFetchLiteral (hierarchy, "animal", XtDisplay(toplevel),

(XtPointer) &animal, &type);

if (status != MrmSUCCESS || type != MrmRtypeChar8)

error ();

status = MrmFetchLiteral (hierarchy, "count", XtDisplay(toplevel),

(XtPointer) &count, &type);

if (status != MrmSUCCESS || type != MrmRtypeInteger)

error ();

printf ("There are %d %s0, *count, animal);

XtFree (count);

XtFree (animal);

Mrm fills in the string pointer and the integer pointer with the values from the UID file. The integer value is

returned as a pointer to an integer. We check the types of the values returned just in case the values are not a string

and an integer as expected. The two values can be defined in a UIL module as follows:

value

animal : exported "frogs";

count : 7;

With MrmFetchLiteral(), you can retrieve values from a UIL module that are not necessarily part of the user

interface, such as printed error messages and program configuration values.

Since values fetched from a UIL module are often used to set resources of existing widgets, Mrm provides a function

that handles this situation. If you use MrmFetchLiteral(), you still have to call XtVaSetValues() to set the

values. MrmFetchSetValues() handles both fetching the values and setting the resources. This routine takes the

following form:

Cardinal

MrmFetchSetValues(hierarchy, widget, args, num_args)

MrmHierarchy hierarchy;

25 Creating a User Interface With UIL 25.3.2 Fetching Values

672

Widget widget;

ArgList args;

Cardinal num_args;

The hierarchy argument specifies the Mrm hierarchy, and widget specifies the widget on which to set the

values. The args parameter is an array of resource settings, and num_args specifies the size of the array. Each

array element is an Arg structure, which is defined as follows:

typedef struct {

String name;

XtArgVal value;

} Arg, *ArgList;

This structure is the same one used with XtSetValues(), but it is used in a slightly different way. When you call

MrmFetchSetValues(), the name field still specifies the name of a resource, but the value field names a UIL

variable that contains the value instead of specifying the value directly. The function and its structure are

demonstrated in the Message() routine shown in the source code

extern Widget message_dialog;

...

void

Message(hierarchy, name)

MrmHierarchy hierarchy;

String name;

{

char msg_buf[33], type_buf[3];

Arg args[2];

sprintf (type_buf, "%s_type", name);

sprintf (msg_buf, "%s_msg", name);

args[0].name = XmNdialogType;

args[0].value = (XtArgVal) type_buf;

args[1].name = XmNmessageString;

args[1].value = (XtArgVal) msg_buf;

MrmFetchSetValues (hierarchy, message_dialog, args, XtNumber (args));

XtManageChild (message_dialog);

}

This function uses its name argument to form two UIL variable names and calls MrmFetchSetValues() to fetch

the values and set the resources of a MessageDialog. The string buffers are only 33 characters long because a UIL

variable name can be at most 32 characters long. The corresponding variable definitions in a UIL module might look

like the following:

value

fnf_msg : exported compound_string ("File not found!");

fnf_type : exported XmDIALOG_ERROR;

dsl_msg : exported compound_string ("Almost out of disk space.");

dsl_type : exported XmDIALOG_WARNING;

An application could use the following function calls to display the MessageDialog with these messages:

Message (hierarchy, "fnf");

Message (hierarchy, "dsl");

25 Creating a User Interface With UIL 25.3.2 Fetching Values

673