Volume 6A: Motif Programming Manual

rgb, single_float, string, string_table,

translation_table, wide_character, xbitmapfile

T}

_ Programmer−defined symbols, also called identifiers, are used to name the variables, procedures, lists, and widgets

that you define in a UIL module. For the most part, you can choose any name that you like for these items, although

the UIL compiler imposes three rules:

A name must be unique within a module.•

A name must begin with one of the characters A−Z, a−z, $, or _ and may contain these characters as well as

the digits 0−9.

•

A name must be no longer than 32 characters.•

Based on these rules, you can see that Alpha, $money, _tab, and moon44 are legal identifiers, while the following

symbols are not: 1993, 3DogNight, next−char, and ask_the_user_to_save_her_work_callback.

23.3.6 Sections of a UIL Module

The main body of a UIL module is divided into several sections that group the different types of definitions and

declarations. Each section begins with the section name and ends at the start of the next section. The list below gives a

brief overview of the five sections supported by UIL: object, value, identifier, procedure, and list.

An object section defines the widget hierarchy and widgets in a user interface. The widget definitions may

include initial resource and callback settings. The other four sections are used to define named items that you

use for these settings. The object section is covered in detail in Section #suilobject.

•

A value section contains definitions of variables used as resource settings in an object section or as the

client_data argument to callbacks specified in the module. You can also retrieve most values directly

from an application. UIL supports value types for almost every type of resource that can be specified in a

widget definition. The value section is described in Section #suilvalue.

•

An identifier section contains declarations of variables defined in the application program. Identifiers

can represent values that do not have a corresponding UIL type or cannot be determined until run−time. The

identifier section is explained in Section #suilident.

•

A procedure section contains declarations of callback procedures that are used in the application program.

Any routine specified as a callback in an object section must be declared in a procedure section. The

procedure section is covered in Section #suilproc.

•

A list section defines lists of resource settings, callback settings (for different callbacks), callback

procedures (for a single callback), and widget children. It is often convenient to define lists of commonly used

settings. The list section is described in Section #suillist.

•

These different sections help to organize a UIL module and make it easier for the UIL compiler to parse a module.

Unlike larger applications, the source code only contains value, procedure, and object sections. Without

describing the syntax of these sections in detail, we'll look at how they are used in this module. The first section in the

source code is a value section that defines a symbolic constant:

value

form_margin : 3;

This section defines form_margin, whose value is the integer 3. You can place more than one definition in a

value section. As you can see in the module, the second value section defines three more constants: the string

hello_string, the font hello_font, and the pixmap world_icon. Although we've only defined integer,

string, font, and pixmap values, UIL supports a number of additional data types. The complete set is described in

23 Introduction to UIL 23.3.6 Sections of a UIL Module

638

Section #suiltypes.

You gain a couple of benefits by defining symbolic constants instead of always using literal values. First, the name of

a value helps document your UIL module by making its purpose more clear. Second, you can easily change values

that are used in more than one place, which is useful for changing strings or adjusting the layout of your interface. In

UIL, a callback procedure is just a specialized type of value used to set a widget's callback resource. Like other

constant values, you need to declare callbacks in a UIL module, but these declarations go in a procedure section

instead. We say that callbacks are declared instead of defined (like values) because the callback definitions really

occur in the application's source code. The following procedure section appears in our example:

procedure

quit (string);

This section declares a callback named quit that takes a string argument. The actual callback is defined in the

hello_world.c program. The argument in a procedure declaration specifies the type of the expected argument, similar

to a function prototype in C. In some cases, the UIL compiler can convert a compatible value to the expected type.

This capability is explained in Section #suilarg. As with value sections, single procedure sections may contain

multiple declarations. Section #suilproc describes the syntax of a procedure section in further detail. Although

constants and procedures are important, widget definitions usually constitute the majority of a UIL module. In UIL,

you can define almost the entire widget hierarchy of your application, including top−level windows, dialog boxes, and

menu systems. As we mentioned earlier, only the ApplicationShell widget of an application must be created with

application code.

A widget definition occurs in an object section of a UIL module. While an object section can contain more than

one widget definition, we have adopted the style of putting each widget definition in its own object section. This

practice causes widget definitions to stand out, making UIL modules easier to read and modify. The widget hierarchy

of our example application starts with the following definition:

object hello_main : XmForm

{

controls {

XmLabel world;

XmPushButton hello;

};

arguments {

XmNshadowThickness = 0;

XmNresizePolicy = XmRESIZE_GROW;

XmNmarginHeight = form_margin;

XmNmarginWidth = form_margin;

};

};

This object section defines the Form widget hello_main, which is the parent of the other widgets in the module.

A definition consists of a name, which is just a UIL identifier, and a widget type. You can use the name of any Motif

widget or widget variant as a type name. For example, both XmRowColumn and XmPulldownMenu are legal

widget types. (For a complete list of UIL widget types see Volume Six B, Motif Reference Manual.)

Widget definitions can contain three optional subsections that specify different widget attributes: controls, which

specify a widget's children; arguments, which set the widget's initial resource settings; and callbacks, which

specify the widget's callback procedures. Each subsection can occur only once per widget definition.

Our definition of the hello_main Form contains two of these subsections. The controls subsection indicates

that the Form has two children: a Label and a PushButton. These two widgets are defined later in the module. The UIL

23 Introduction to UIL 23.3.6 Sections of a UIL Module

639