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(&quot;Widget does not return a copy! You should free it &quot;);</PRE>

<P>The XtWarning() message is especially useful for debugging the execution 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 invoker, the message is lost.

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="imp.gif" WIDTH = 68 HEIGHT = 35><B>TIP:</B> The XtSetArg macro is defined as:

<BR>

<BR>#define XtSetArg(arg,n,d) \

<BR>    ((void)((arg).name = (n).(arg).value = (XtArgVal)))

<BR>

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

<BR></NOTE>

<HR ALIGN=CENTER>

<H3 ALIGN="CENTER">

<CENTER><A ID="I13" NAME="I13">

<FONT SIZE=4><B>The PushButton Widget</B>

<BR></FONT></A></CENTER></H3>

<P>XmPushButton is perhaps the most heavily used widget in Motif.

<BR></P>

<P>Listings 1 and 2 showed the basic usage for this class. When a button is pressed in the pushbutton area, the button goes into an &quot;armed&quot; state. The color of the button changes to reflect this state. This color can be set by using XmNarmColor. 

This color is shown when the XmNfillOnArm resource is set to TRUE.

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="imp.gif" WIDTH = 68 HEIGHT = 35><B>TIP:</B> If the XmNarmcolor for a pushbutton does not seem to be working, try setting the XmNfillOnArm resource to TRUE.

<BR></NOTE>

<HR ALIGN=CENTER>

<P>The callback functions for a pushbutton are:

<BR></P>

<UL>

<LI>XmNarmCallback: Called when a pushbutton is armed.

<BR>

<BR></LI>

<LI>XmNactivateCallback: Called when a button is released in the widgets area while the widget is armed. This is not invoked if the pointer is outside the widget when the button is released.

<BR>

<BR></LI>

<LI>XmNdisarmCallback: Called when a button is released with the pointer outside the widget area while the widget is armed.

<BR>

<BR></LI></UL>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="imp.gif" WIDTH = 68 HEIGHT = 35><B>TIP:</B> If a callback has more than one function registered for a widget, all the functions will be called but not necessarily in the order they were registered. Do not rely on the same order being preserved on 

other systems. If you want more than one function performed during a callback, sandwich them in one function call.

<BR></NOTE>

<HR ALIGN=CENTER>

<P>In Listing 47.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.

<BR></P>

<H4 ALIGN="CENTER">

<CENTER><A ID="I14" NAME="I14">

<FONT SIZE=3><B>The Toggle Button Widget</B>

<BR></FONT></A></CENTER></H4>

<P>The toggle button class is a subclass of the XmLabel widget class. There are two types of buttons: N of many and one of many. When using N of many, users can select many options. When using one of many, the users must make one selection from many items. 

Note the way the buttons are drawn; N of many buttons are shown as boxes and one of many buttons are shown as diamonds.

<BR></P>

<P>The resources for this widget include:

<BR></P>

<UL>

<LI>XmNindicatorType: This determines the style and can be set to XmN_OF_MANY or XmONE_OF_MANY (the default).

<BR>

<BR></LI>

<LI>XmNspacing: The number of pixels between the button and its label.

<BR>

<BR></LI>

<LI>XmNfillOnSelect: The color of the button changes to reflect a &quot;set&quot; when the XmNfillOnArm resource is set to TRUE.

<BR>

<BR></LI>

<LI>XmNfillColor: The color to show when &quot;set.&quot;

<BR>

<BR></LI>

<LI>XmNset: A Boolean resource indicating whether the button is set or not. If this resource is set from a program, the button will automatically reflect the change.

<BR>

<BR></LI></UL>

<P>It's easier to use the convenience function XmToggleButtonGetState(Widget w) to get the Boolean state for a widget, and to use XmToggleButtonSetState(Widget w, Boolean b) to set the value for a toggle button widget.

<BR></P>

<P>Like the pushbutton class, the toggle button class has three similar callbacks:

<BR></P>

<UL>

<LI>XmNarmCallback: Called when the toggle button is armed.

<BR>

<BR></LI>

<LI>XmNvalueChangedCallback: 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.

<BR>

<BR></LI>

<LI>XmNdisarmCallback: Called when a button is released with the pointer outside the widget area while the widget is armed.

<BR>

<BR></LI></UL>

<P>For the callbacks, the callback data is a structure of type:

<BR></P>

<PRE>typedef struct {

     int  reason;

     XEvent  *event;

     int  set;

} XmToggleButtonCallbackStruct;</PRE>

<P>The reason for the callback is one of the following: XmCR_ARM, XmCR_DISARM, or XmCR_ACTIVATE. The event is a pointer to XEvent that caused this callback. The set value is 0 if the item is not set and non-zero if it's set. The buttons are arranged in one 

column through the RowColumn widget discussed later in this chapter. See file 47_3c on the CD-ROM for an example of how to use the toggle button.

<BR></P>

<P>By defining the DO_RADIO label, you can make this into a radio button application. That is, only one of the buttons can be selected at one time.

<BR></P>

<H3 ALIGN="CENTER">

<CENTER><A ID="I15" NAME="I15">

<FONT SIZE=4><B>Convenience Functions</B>

<BR></FONT></A></CENTER></H3>

<P>Usually, the way to set resources for a widget is to do it when you create the widget. This is done with either the XtVaCreateManaged call or the XmCreateYYY call, where YYY is the widget you're creating. The text uses the variable argument call to 
create and manage widgets. If you use the XmCreateYYY call, you have to set the resource settings in a list of resource sets. An example of creating a Label widget is shown in file 47_4c on the CD-ROM. This is a function that creates a Label widget on a 
widget given the string x.

<BR></P>

<P>Or you could use the variable argument lists to create this label, as shown in file 47_5c.

<BR></P>

<P>In either case, it's your judgment call as to which one to use. The label created with the variable lists is a bit easier to read and maintain. But what about setting values after a widget has been created? This would be done through a call to 
XtSetValue with a list and count of resource settings. For example, to change the alignment and text of a label, you would use the following:

<BR></P>

<PRE>n = 0;

XtSetArg(arg[n], XmNalignment, XmALIGNMENT_BEGIN); n++;

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

XtSetValues(lbl,arg,n);</PRE>

<P>Similarly, to get the values for a widget you would use XtGetValues:

<BR></P>

<PRE>Cardinal n; /* usually an integer or short... use Cardinal to be safe

*/ int align;

XmString x;

...

n = 0;

XtSetArg(arg[n], XmNalignment, &amp;align); n++;

XtSetArg(arg[n], XmNlabelString, &amp;x); n++; XtGetValues(lbl,arg,n);</PRE>

<P>In the case of other widgets, such as the Text widget, this setting scheme is hard to read, quite clumsy, and prone to typos. For example, to get a string for a Text widget, do you use x or address of x?

<BR></P>

<P>For this reason, Motif provides convenience functions. In the ToggleButton widget class, for example, rather than use the combination of XtSetValue and XtSetArg calls to get the state, you would use one call, XmToggleButtonGetState(Widget w), to get the 

state. These functions are valuable code savers when you're writing complex applications. In fact, you should write similar convenience functions whenever you cannot find one that suits your needs.

<BR></P>

<H3 ALIGN="CENTER">

<CENTER><A ID="I16" NAME="I16">

<FONT SIZE=4><B>The List Widget</B>

<BR></FONT></A></CENTER></H3>

<P>The List widget displays a list of items from which the user can select. The list is created from a list of compound strings. Users can select either one item or many items from this list. The resources for this widget include:

<BR></P>

<UL>

<LI>XmNitemCount: This determines the number of items in the list.

<BR>

<BR></LI>

<LI>XmNitems: An array of compound strings. Each entry corresponds to an item in the list. Note that a List widget makes a copy of all items in its list when using XtSetValues; however, it returns a pointer to its internal structure when returning values 
to an XtGetValues call. So do not free this pointer from XtGetValues.

<BR>

<BR></LI>

<LI>XmNselectedItemCount: The number of items currently selected.

<BR>

<BR></LI>

<LI>XmNselectedItems: The list of selected items.

<BR>

<BR></LI>

<LI>XmNvisibleItemCount: The number of items to display at one time.

<BR>

<BR></LI>

<LI>XmNselectionPolicy: This is used to set single or multiple selection capability. If set to XmSINGLE_SELECT, the user will be able to select only one item. Each selection will invoke XmNsingleSelectionCallback. Selecting one item will deselect another 
previously selected item. If set to XmEXTENDED_SELECT, the user will be able to select a block of contiguous items in a list. Selecting one or more new items will deselect other previously selected items. Each selection will invoke the XmNmultipleSelection 

callback.

<BR>

<BR></LI></UL>

<P>If set to XmMULTIPLE_SELECT, the user will be able to select multiple items in any order. Selecting one item will not deselect another previously selected item. Each selection will invoke the XmNmultipleSelection callback.

<BR></P>

<P>If the resource is set to XmBROWSE_SELECT, the user can move the pointer across all the selections with the button pressed, but only one item will be selected. This will invoke XmbrowseSelectionCallback when the button is finally released on the last 
item browsed. Unlike with the XmSINGLE_SELECT setting, the user does not have to press and release the button to select an item.

<BR></P>

<P>It is easier to create the List widget with a call to XmCreateScrolledList(), because this will automatically create a scrolled window for you. Also, the following convenience functions will make working with List widgets easier. However, they may prove 

to be slow when compared to XtSetValues() calls. If you feel that speed is important, consider using XtSetValues(). You should create the list for the first time by using XtSetValues.

<BR></P>

<UL>

<LI>XmListAddItem(Widget w, XmString x, int pos): This will add the compound string x to the List widget w at the 1-relative position pos. If pos is 0, the item is added to the back of the list. This function is very slow. Do not use it to create a new 
list, because it rearranges the entire list before returning.

<BR>

<BR></LI>

<LI>XmListAddItems(Widget w, XmString *x, int count, int pos): This will add the array of compound strings, x, of size count, to the List widget w from the position pos. If pos is 0, the item is added to the back of the list. This function is slow too, so 

do not use it to create a new list.

<BR>

<BR></LI>

<LI>XmDeleteAllItems(Widget w): This will delete all the items in a list. It's better to write a convenience function:

<BR>

<BR>n = 0; 

<BR>XtSetArg(arg[n], XmNitems, NULL); n++;

<BR>XtSetArg(arg[n], XmNitemCount, 0); n++;

<BR>XtSetValues(mylist,arg,n);

<BR></LI>

<LI>XmDeleteItem(Widget w, XmString x): Deletes the item x from the list. This is a slow function.

<BR>

<BR></LI>

<LI>XmDeleteItems(Widget w, XmString *x, int count): Deletes all the count items in x from the list. This is an even slower function. You might be better off installing a new list.

<BR>

<BR></LI>

<LI>XmListSelectItem(Widget w, XmString x, Boolean Notify): Programmatically selects x in the list. If Notify is TRUE, the appropriate callback function is also invoked.

<BR>

<BR></LI>

<LI>XmListDeselectItem(Widget w, XmString x): Programmatically deselects x in the list.

<BR>

<BR></LI>

<LI>XmListPos( Widget w, XmString x): Returns the position of x in the list. 0 if not found.

<BR>

<BR></LI></UL>

<P>See file 47_6c on the CD-ROM.

<BR></P>

<H3 ALIGN="CENTER">

<CENTER><A ID="I17" NAME="I17">

<FONT SIZE=4><B>The Scrollbar Widget</B>

<BR></FONT></A></CENTER></H3>

<P>The Scrollbar widget allows the user to select a value from a range. Its resources include:

<BR></P>

<UL>

<LI>XmNvalue: The value representing the location of the slider.

<BR>

<BR></LI>

<LI>XmNminimum and XmNmaximum: The range of values for the slider.

<BR>

<BR></LI>

<LI>XmNshowArrows: The Boolean value if set shows arrows at either end.

<BR>

<BR></LI>

<LI>XmNorientation: Set to XmHORIZONTAL for a horizontal bar or XmVERTICAL (default) for a vertical bar.

<BR>

<BR></LI>

<LI>XmNprocessingDirection: Set to either XmMAX_ON_LEFT or XmMAX_ON_RIGHT for XmHORIZONTAL, or XmMAX_ON_TOP or XmMAX_ON_BOTTOM for XmVERTICAL orientation.

<BR>

<BR></LI>

<LI>XmNincrement: The increment per move.

<BR>

<BR></LI>

<LI>XmNpageIncrement: The increment if a button is pressed in the arrows or the box. This is defaulted to 10.

<BR>

<BR></LI>

<LI>XmNdecimalPoint: Shows the decimal point from the right. Note that all values in the Scrollbar widget's values are given as integers. Look at the radio station selection example in file 47_8c on the CD-ROM. Note that the Push to Exit button for the 
application is offset on the left and right by 20 pixels. This is done by offsetting the XmATTACH_FORM value for each side (left or right) through the value in XmNleftOffset and XmNrightOffset. See the &quot;Forms&quot; section for more details.

<BR>

<BR></LI></UL>

<P>For the case of FM selections, you would want the bar to show odd numbers. A good exercise for you would be to allow only odd numbers in the selection. Hint: Use XmNvalueChangedCallback:

<BR></P>

<PRE>XtAddCallback(aScale, XmNvalueChangedCallback, myfunction);</PRE>

<P>The callback will send a pointer to the structure of type XMScaleCallbackStruct. where myfunction is defined as:

<BR></P>

<PRE>/**

*** Partial listing for not allowing even numbers for FM selection.