by Kamran Husain

IN THIS CHAPTER

• n Writing Motif Applications

• Designing Layouts

• Menus

• Dialog Boxes

• Managing the Queue

• The Graphics Context

• Drawing Lines, Points, Arcs, and Polygons

• Using Fonts and FontLists

• Pixmaps, Bitmaps, and Images

This chapter will cover the following topics:

• The basics of writing Motif applications for Linux

• Special naming conventions in Motif and X

• Writing and compiling your first Motif application

• Revisiting the Widget hierarchy

• Using labels and strings in Motif

• Using various common Widgets

• Designing layout

• Using menus

• Dialog boxes

• Event handling and other sources of input

• Colors in X

• Drawing lines, points, arcs, and polygons

A question you might be asking is "Why include a topic on a development system that you have to pay for, when just about everything for Linux is free?" Well, if you want to develop any applications for the Common Desktop Environment (CDE), you should know how to program Motif applications. Linux is a mature enough system to enable you this luxury of building portable applications. (Plus, the $150 or so you pay for the Motif license will well pay for itself if you can do the work at home on your Linux system rather than commuting!)

This chapter introduces you to writing Motif applications. The information here will not be limited to writing applications for Linux alone, because the concepts in this chapter can be applied to other UNIX systems as well.

In programming Motif applications, you have to get used to programming in an event-driven environment. A typical C application runs from start to finish at its own pace. When it needs information, the application looks for this information from a source such as a file or the keyboard and (almost always) gets the information as soon as it asks for it. If the information is not available when the application asks for it, the application either waits for it or displays an error message. Also, the order of the incoming data is important for such applications; pieces of data that are out of sequence may cause the application to behave strangely.

In the case of event-driven programming, an application must wait for events on an input queue. The queue orders all incoming events in the order they are received. The first message to come in from one end of a queue is the first one to leave the queue. (Such queues are often called FIFOs, for First In, First Out.) An event can be anything from a mouse click to a timeout notification.

Because events can come in at any time, and in no predefined order, they are referred to as asynchronous events. That is, the order and time of arrival of each event is not deterministic. The application must wait for an event to occur and then proceed based on that event. Thus the term event-driven programming.

In the case of the X Window system, each X Window application has one input queue for all of its incoming events. The application must wait for events on this input queue. Similarly, a server waits for an event from a client and then responds based on the type of event received. This event handling and other aspects of X programming are handled by a toolkit called XtIntrinsics, or Xt for short.

In Xt, an application will typically run in a loop forever. This loop is called an event loop. An application enters the loop by calling a function XtAppMainLoop(). While in this event loop, an application will always wait for an event, When the application receives an event, the application handles the event itself or almost always "dispatches" the event to a window or Widget.

A Widget registers functions that it wants called when a type of event is received. This function is called a callback function. In most cases, a callback function is independent of the entire application. For example, some Widgets will redraw themselves when a pointer button is clicked in their display area. In this case, they would register a redraw callback function on a button click.

Xt also supports actions, which enable applications to register a function with Xt. An action is called when one or more sequences of specific event types are received. For example, pressing Ctrl-X would call the exit function. The mapping of the action to an event is handled via a translation table within Xt. Functions that handle specific events are referred to as event handlers.

By default, most Xlib functions begin with the letter X, but you should not always rely on this being true for all functions. Several macros and functions in the X Window system do not begin with X. For example, the names BlackColor and WhiteColor are not macros. In general, though, if a name in Xlib begins with X, it's probably a function. If a name begins with a capital letter (A through Z), it's a macro.

With Xt, the naming conventions get better, but only slightly. In Xt, macros are not differentiated from functions in any way.

In Motif, almost all declarations begin with Xm. Therefore, XmC refers to a class, XmR refers to a resource, XmN refers to a name, and XtN refers to Xt resources used by Motif. Declarations ending with the words WidgetClass define the base class for a type of Widget. A few conventions to remember about parameters for most Xlib functions are

• Width is always to the left of height

• X is always to the left of y

• Source is always to the left of destination

• Display usually is the first parameter

With practice, you will be able to identify the type of parameters to pass and which toolkit a function belongs to, and be able to make some educated guesses as to what parameters an unknown function might expect.

Let's look at the basic format for a Motif application, shown in Listing 34.1. (I added line numbers for your benefit.) I will discuss this application in detail. You will build other Motif applications based on the structure in this particular application as you progress through this chapter.

The Core Widget class provides the basis for all classes. It provides at least the following resources for all Widgets: XmNx,XmNy: A Widget's position on the display.

XmNheight, XmNwidth: A Widget's size.

XmNborderWidth: Set to 1 by default.

XmNsensitive: A Boolean resource that specifies whether this Widget can receive input.

XmNcolorMap: The default color map.

XmNbackground: The background color.

Check the Motif Programmer's reference manual for a complete listing.

The XmPrimitive Widget class inherits all the resources from Core and adds more functionality. XmNforeground: The foreground color.

XmNhighlightOnEnter: Changes color when the pointer is within a displayed area of Widget.

XmNhighlightThickness: If XmNhighlightOnEnter is TRUE, changes the border to this thickness.

XmNhighlightColor: The color a Widget changes to when highlighted.

XmNshadowThickness: This is the thickness to show the pseudo-three-dimensional look for which Motif is famous. The default value is 2.

XmNtopShadowColor and XmNbottomShadowColor: Sets the color for top and bottom lines around a Widget.

XmNuserData: A pointer available for the programmer's use.

The XmPrimitive Widget also provides the XmNdestroyCallback resource. This can be set to a function that would do clean-up when a Widget is destroyed. In Motif 1.2.x or later, the XmPrimitive class also provides a XmNhelpCallback that is called when the F1 key is pressed in the Widget's window. This is to allow specific help information for a button, for example.

The XmManager class provides support for all Motif Widgets that contain other Widgets. This is never used directly in an application, and it works in a manner similar to the XmPrimitive class. It provides the following resources: XmNforeground: The color of the pixels in the foreground.

XmNshadowThickness: For the three-dimensional effect.

XmNtopShadowColor: For the three-dimensional effect. This is automatically defaulted to a color derived from the background color. This color is used on the left and top borders of a Widget.

XmNbottomShadowColor: For the three-dimensional effect. This is automatically defaulted to a color derived from the background color. This color is used on the right and bottom borders of a Widget.

XmNuserData: For storing user data. Could be used as a void pointer.

The Label Widget is used to display strings or pixmaps. Include the Xm/Label.h file in your source file before using this Widget. Some of the resources for this Widget include these: XmNalignment: Determines the alignment of the text in this Widget. The acceptable values are XmALIGNNMENT_END, XmALIGNMENT_CENTER, and XmALIGNEMENT_BEGIN for right, center, and left justification, respectively.

XmNrecomputeSize: A Boolean resource. If set to TRUE, the Widget will resize should the size of the string or pixmap change dynamically. This is the default. If set to FALSE, the Widget will not attempt to resize itself.

XmNlabelType: The default value of this type is XmSTRING to show strings. However, it can also be set to XmPIXMAP when displaying a pixmap specified in the XmNpixmap resource.

XmNlabelPixmap: This is used to specify which pixmap to use when the XmNlabelType is set to XmPIXMAP.

XmNlabelString: This is used to specify which XmString compound string to use for the label. This defaults to the name of the label. See the section, "Strings in Motif: Compound Strings."

To get acquainted with left and right justification on a label, see Listing 34.2. The listing also shows how the resources can be set to change Widget parameters programmatically and via the .Xresource files.

A compound string is Motif's way of representing a string. In a typical C program, a NULL- terminated string is enough to specify a string. In Motif, a string is also defined by the character set it uses. Strings in Motif are referred to as compound strings and are kept in opaque data structures called XmString.

In order to get a compound string from a regular C string, use this function call:

XmString XmStringCreate( char *text, char *tag);

This function will return an equivalent compound string given a pointer to a NULL- terminated C string and a tag. The tag specifies which fontlist to use and is defaulted to XmFONTLIST_DEFAULT_TAG.

New lines in C strings have to be handled by special separators in Motif. So to create a string and preserve the newlines, use the call

XmString XmStringCreateLtoR( char *text, char *tag);

The compound strings have to be created and destroyed just like any other object. They persist long after the function call that created them returns. Therefore, it's a good idea to free all locally used XmStrings in a function before returning, or else all references to the strings will be lost. The definition of a call to free XmString resources is

XmStringFree( XmString s);

You can run similar operations on strings as you would in a C program, except that these string operations are called by different names. Use the function

Boolean XmStringByteCompare( XmString s1, XmString s2);

for a strict byte-for-byte comparison, and for just the text comparison, use

Boolean XmStringCompare( XmString s1, XmString s2);

To check if a string is empty, use

Boolean XmStringEmpty( XmString s1);

To string two strings together, use

XmString XmStringConcat( XmString s1, XmString s2);

XmString Concat() creates a new string by concatenating s2 to s1 and returns it. This returned string has to be freed just like s1 and s2.

If you want to use sprintf, use it on a temporary buffer and then create a new string. For example:

char str[32];

XmString xms;

......

sprintf(str," pi = %lf, Area = %lf", PI, TWOPI*r);

xms =  XmStringCreateLtoR( str,  XmFONTLIST_DEFAULT_TAG);

......

n = 0;

XtSetArg(arg[n],XmNlabelString,xms); n++;

XtSetValues(someLabel, arg, n);

XmStringFree(xms);

If a string value becomes corrupted without your performing any direct actions on it, check to see whether the Widget is not making a copy for its use of the passed XmString. Sometimes a Widget might be keeping only a pointer to the XmString. If that string were freed, the Widget might wind up pointing to bad data.

One good way to check is to set an XmString resource, then use the XtGetValues function to get the same resource from the Widget. If the values of the XmStrings are the same, the Widget is not making a copy for itself. If they are not the same, it is safe to free the original because the Widget is making a local copy. The default course of action is to assume that a Widget makes a copy of such resources for itself.

A similar test could be used to determine whether a Widget returns a copy of its resource or a pointer to it. Use the same listing shown two paragraphs ago, but this time use a getValue to get the same resource twice. Then do the comparison to see whether the address for the original string matches the address of the returned value from getValue(): If the values match, the Widget keeps a pointer. If the values do not match, the Widget keeps an internal copy.

/**

*** This is a sample partial listing of how to check if the

*** data returned on an XtGetValues and an XtSetValues

*** call is a copy or a reference.

***/



#include "Xm/Text.h"

..

Widget w;

XmString x1, x2, x3;



x3 = XmStringCreateLtoR("test", XmFONTLIST_DEFAULT_TAG);

XmTextSetString(w,x3);

...

x1 = XmTextGetString(w);

x2 = XmTextGetString(w);



XtWarning(" Checking SetValues");

if (x1 != x3)

      XtWarning("Widget keeps a copy ! Free original!");

else

      XtWarning("Widget does not keep a copy! Do NOT free original");





XtWarning(" Checking GetValues");

if (x1 == x2)

      XtWarning("Widget returns a copy! Do NOT free");

else

      XtWarning("Widget does not return a copy! You should free it ");

The XtWarning() message is especially useful for debugging the progress of programs. The message is relayed to the stderr of the invoking application. If this is an xterm, you will see an error message on that terminal window. If no stderr is available for the invoke mechanism, the message is lost.

#define XtSetArg(arg,n,d) \
((void)((arg).name = (n).(arg).value = (XtArgVal)(d)))

Do not use XtSetArg(arg[n++]... because this will increment n twice.

---

The XmPushButton is perhaps the most heavily used Widget in Motif. Listings 34.1 and 34.2 show the basic usage for PushButton. When a button is pressed in the PushButton area, the button goes into an armed state (a state between not pressed and going to pressed). The color of the button changes to reflect this state, and you can set this color by using XmNarmColor. This color is shown when the XmNfillOnArm resource is set to TRUE.

The callback functions for a PushButton are the following: XmNarmCallback: Called when a PushButton is armed.

XmNactivateCallback: Called when a button is released in the Widget area while the Widget is armed. This is not invoked if the pointer is outside the Widget when the button is released.

XmNdisarmCallback: Called when a button is released with the pointer outside the Widget area while the Widget is armed.

In Listing 34.2, you saw how a callback function was added to a PushButton with the XtAddCallback function. The same method can be used to call other functions for other actions such as the XmNdisarmCallback.