flatwidget(3W)
NAME
OlFlatCallAcceptFocus, OlFlatGetFocusItem, OlFlatGetItemIndex, OlFlatGetItemGeometry, OlFlatGetValues, OlFlatSetValues, OlVaFlatGetValues OlVaFlatSetValues − flattened widget functions
SYNOPSIS
There are several convenience routines for querying or manipulating flattened widget attributes. All of these routines issue a warning if the widget id is not a subclass of a flattened widget.
#include <Xol/OpenLook,h>
. . .
Boolean OlFlatCallAcceptFocus(
Widget widget,
Cardinal index,
Time time);
#include <Xol/OpenLook,h>
. . .
Cardinal OlFlatGetFocusItem(
Widget widget);
#include <Xol/OpenLook,h>
. . .
Cardinal OlFlatGetItemIndex(
Widget widget,
Position x,
Position y);
#include <Xol/OpenLook,h>
. . .
void OlFlatGetItemGeometry(
Widget widget,
Cardinal index,
Position ∗x_ret,
Position ∗y_ret,
Dimension ∗w_ret,
Dimension ∗h_ret);
#include <Xol/OpenLook,h>
. . .
void OlFlatGetValues(
Widget widget,
Cardinal index,
ArgList args,
Cardinal num_args);
#include <Xol/OpenLook,h>
. . .
void OlFlatSetValues(
Widget widget,
Cardinal index,
ArgList args,
Cardinal num_args);
#include <Xol/OpenLook,h>
. . .
void OlVaFlatGetValues(
Widget widget,
Cardinal index,);
#include <Xol/OpenLook,h>
. . .
void OlVaFlatSetValues(
Widget widget,
Cardinal index);
DESCRIPTION
OlFlatCallAcceptFocus()
If specified item is capable of accepting input focus, focus is assigned to the item and function returns TRUE; otherwise, FALSE.
OlFlatGetFocusItem()
Returns the item within the flattened widget which has focus. OL_NO_ITEM is returned if no item within the widget has focus.
OlFlatGetItemIndex()
Returns the item that contains the given x and y coordinates. OL_NO_ITEM is returned otherwise if no item contains the coordinate pair.
OlFlatGetItemGeometry()
Returns the location and width/height of an item with respect to its flattened widget container. If the supplied item index is invalid, a warning is issued and the return values are set to zero.
OlFlatGetValues()
Queries attributes of an item. This routine is very similar to XtGetValues. Applications can query any attribute of an item even if the attribute was not specified in the XtNitemFields resource of the flat widget container. Also see OlVaFlatGetValues().
OlFlatSetValues()
Sets attributes of an item. This routine is very similar to XtSetValues. Applications can set values of item attributes only even if the attribute name was specified in the XtNitemFields resource of the flat widget container or if the item’s attribute is always maintained (i.e., implicitly) by the flat widget container regardless of the XtNitemFields entries. For example, since the FlatExclusives Widget always maintains the value of an item’s XtNset attribute even if XtNset was not in the XtNitemFields resource (see FlatExclusives(3W)).Therefore,anapplication the value of XtNset even though XtNset was not specified explicitly in the XtNitemFields resource for the widget. XtNfont, on the other hand, is not implicitly maintained by the FlatExclusives widget, so an application must specify XtNfont in the XtNitemFields resource if that application wants to change the font value via OlFlatSetValues. Also see OlVaFlatSetValues().
OlVaFlatGetValues()
Variable argument interface to OlFlatGetValues. The variable length list of resource name/value pairs is terminated by a NULL resource name.
OlVaFlatSetValues()
Variable argument interface to OlFlatSetValues. The variable length list of resource name/value pairs is terminated by a NULL resource name.
Flat Widgets
Flattened widgets give the visual appearance and functionality of many discrete windowed widgets, but are implemented as one widget with a single associated window created with one, convenient toolkit request. Flattened widgets consume a fraction of the memory that a similar widget hierarchy requires.
The following widgets have flattened versions:
•Exclusives
•Nonexclusives
•CheckBox
In general, flattened widgets have the following attributes:
1.They are container objects, responsible for managing the look and feel of one or more sub-objects (called items for brevity).
2.The sub-object classes are limited to one or a select few.
3.Typically, after the container is populated, minimal or no manipulation of the sub-objects is desired.
4.Each container is simply a region that contains zero or more sub-objects of a certain type.
5.The sub-objects within the container do not have an associated window or widget structure.
From the user’s perspective, there’s no distinguishable difference between a flattened widget interface and a traditionally-composed interface. From the programmer’s perspective, flattened widgets have a different interface than traditional widgets or gadgets. A single toolkit request can specify an arbitrary number of primitive graphical user interface components (i.e., the sub-objects), thus achieving a substantial reduction in the lines of code required to produce a complex graphical interface component.
Sub-object Lists and Allowable Resources
Sub-objects of a flat container are specified in list format. For the life of the list, both the flat container and the application share the same list. Each list is an array of application-defined records (typically, in a ’C’ structure format or as an array), where each record describes a particular sub-object.
For efficiency reasons, each record in the array must have the same form as the other records in the array, i.e., each structure in the list has identical fields. This restriction applies on a per list basis only, since each list may have a different set of fields per record if the application desires different attributes.
For example, if an application wanted to specify an "unselect" callback procedure for one group of exclusives but not for another, the application would specify an XtNunselectProc field as an element field for the first list but not for the second list. For data alignment and parsing reasons, the fields of each record must use the XtArgVal type (see the code example).
The fields of each record are resource values that describe the state of the sub-object. Allowable sub-object resources are a subset of its container’s resource set. The genealogy of flattened widget resources is derived from release 1.0 resources, though new resources have been added (and some old ones removed) to provide greater convenience to the application programmer and achieve a higher degree of consistency between all flat containers and their sub-objects.
Since all sub-object resources are part of its container, sub-objects inherit any non-specified resource from its container. For example, if the application wanted a particular font color for all sub-objects, the application does not have to specify the XtNfontColor resource for each sub-object; the application simply sets the font color resource on the container and all sub-objects will use that font color. Though sub-object resources are part of its container’s resource set, none of the sub-object resources have any direct effect on the container.
Since the "form" of the sub-object record is defined within the application’s domain, the container must be given a hint about the record’s form so that it can parse the supplied list. A resource name list is the key to unlocking the application’s sub-object list.
While the ordering of fields in each record is not important, the application must give the resource names in the same sequence that their associated values appear in the record. For example, if the records specifying sub-objects of a flat exclusives container had a "label" field followed by the "selectProc" callback field, the application must supply the container with the XtNlabel resource name followed by the XtNselectProc resource name. Inconsistent ordering of the fields will result in undefined behavior when the sub-objects are instantiated.
Example
The following code example illustrates how to create a flat exclusives settings. Notice that all the fields in the application-defined structure, FlatExclusives, have the type XtArgVal.
Note
An alternate form for specifying the FlatExclusives type is:
typedef XtArgVal FlatExclusives[number];
where number
is the number fields per record.
Since each item has the same client data for the select callback procedure, the XtNclientData resources is specified for the container only, which allows each sub-object to inherit this value. If each sub-object wanted a different client data, the XtNclientData resource should be added to the other sub-object resources, which would disable the inheriting of the container’s client data value.
To improve the readability of this example, required type casts of the fields in the FlatExclusives structure initialization deliberately have been omitted. The resources used in the example will be describe in a later section.
/∗ Application Defined Structure ∗/
typedef struct {
XtArgVal label; /∗ pointer to a string ∗/
} FlatExclusives;
String
exc_fields[] = { XtNlabel, XtNselectProc };
static void
cb()
{ /∗ something interesting in here ∗/ }
CreateObjects(parent)
Widgetparent;
{
Arg args[6];
static FlatExclusives exc_items[] = {
{ "Choice 1" },
{ "Choice 2" },
{ "Choice 3" }
};
XtSetArg(args[0], XtNitems, exc_items);
XtSetArg(args[1], XtNnumItems, XtNumber(exc_items));
XtSetArg(args[2], XtNitemFields, exc_fields);
XtSetArg(args[3], XtNnumItemFields, XtNumber(exc_fields));
XtSetArg(args[4], XtNselectProc, cb,);
XtSetArg(args[5], XtNclientData, "test case");
XtCreateManagedWidget("exclusives", flatExclusivesWidgetClass,
parent, args, 6);
} /∗ END OF CreateObjects() ∗/
Specifying Sub-Objects
Sub-objects of flattened widget containers are specified in list format with each list having a corresponding set of resource names describing how the container is to parse the list. Four common resources are used by each container class to describe the necessary sub-object information:
Table 1 Flat Widget Resource Set Name Class Type Access
XtNitemsXtCItems XtPointer SGI XtNnumItems XtCNumItems Cardinal SGI XtNitemFields XtCItemFields String ∗ SGI XtNnumItemFields XtCNumItemFields Cardinal SGI
XtNitemsThis is the list of sub-object items. This value must point to a static list since flat containers reference this list after initialization, but do not cache its information.
XtNnumItemsThis resource specifies the number of sub-object items.
XtNitemFieldsThis resource contains the list of resource names used to parse the records in the XtNitems list. XtNitemFields does not have to point to static information since the flat container does not use this information after initialization. Although the flat container does not reference this resource’s value after initialization, it holds onto it for responding to an XtGetValues() request and suppling it in the OlFlatCallData structure during callbacks. Therefore, if the application plans on querying this resource, it’s recommended that the application make this resource point to static information.
XtNnumItemFields
This resource specifies the number of resource names contained in XtNitemFields.
Callbacks and Flat Widgets
There are two differences in the way callbacks are handled for flat widgets versus traditional widgets. The first difference is that sub-objects do not use XtCallback lists; instead, they use a single XtCallbackProc procedure.
Note:
Remember a callback procedure has the following form:
typedef void (∗XtCallbackProc)(widget, client_data, call_data);
Widget widget;
XtPointer client_data;
XtPointer call_data;
Secondly, since the sub-objects of flattened widget containers are not true widget instances, the widget argument supplied to an application’s callback procedure indicates the flat container widget that is ultimately responsible for managing the sub-objects. For example, the flatExclusivesWidget id would be supplied as the widget id to callback procedure for all sub-objects within the flat exclusives container. By maintaining this rule, the application always has the correct widget handy in the event that the application wishes to modify the item or its list from within the callback procedure. The value of the XtNclientData resource is supplied as the client_data field to the callback procedure.
The call_data field is a structure that the application can use to determine information about the sub-object associated with the current callback. The new structure is as follows:
typedef struct {
Cardinal item_index; /∗ sub-object initiating callback ∗/
XtPointer items; /∗ Sub-object list head ∗/
Cardinal num_items; /∗ number of items ∗/
String ∗ item_fields; /∗ key of fields for list ∗/
Cardinal num_item_fields; /∗ number of fields per item ∗/
} OlFlatCallData;
Where:
item_indexIndex of the item responsible for the callback.
itemsthe head of item list that contains the sub-object initiating the callback
num_itemsthe total number of items in the sub-object list
item_fieldsthe list of resource name used to parse the records in the items list.
num_item_fields
The number of resource names contained in item_fields.
Setting/Getting the State of a Sub-Object
Setting the State of a Sub-Object
The application can use two methods to change the state of an item: use the OlFlatSetValues procedure to modify one or more attributes of a sub-object, or directly modify the item list that the container and the application share.
OlFlatSetValues(widget, item_index, args, num_args)
Widget widget; /∗ flat widget id ∗/
Cardinal item_index; /∗ item to modify ∗/
ArgList args; /∗ new resources ∗/
Cardinal num_args; /∗ number of new resources ∗/
The first approach is very similar to doing an XtSetValues request on a widget, except that the OlFlatSetValues routine requires the item index as well as the widget id, args and num_args. The following code example illustrates how to change an item’s label from within a callback procedure. The example assumes the new label was specified as the client data.
Callback(widget, client_data, call_data)
Widget widget; /∗ FlatExclusives Widget id ∗/
caddr_t client_data; /∗ the new static label ∗/
caddr_t call_data; /∗ OlFlatCallData structure pointer ∗/
{
OlFlatCallData ∗ fcd = (OlFlatCallData ∗)call_data;
Arg args[1];
/∗ Set the label to be the new one passed in
∗ with the client data field. ∗/
XtSetArg(args[0], XtNlabel, client_data);
OlFlatSetValues(widget, fcp->item_index, args, 1);
} /∗ END OF Callback() ∗/
Notice that the callback procedure did not have to know the number or the order of the item fields. The only requirement was that the XtNlabel resource is among the application-specified item fields, because if it was not, the above request would be ignored. (Note: there are some exceptions to this rule.
For instance, the flat containers maintain the set item and the default item even if the application did not specify XtNset or XtNdefault
in the item fields. Having exceptions in this case are worthwhile since if the exceptions were not made, the application always would have to specify a minimum set of item fields, which would have been an undesirable requirement. See the individual manual pages for each widget for a better description of the exceptions.)
If the application does not use the above approach and modifies the item list directly, the application must ensure that all items within the list have valid states, since the container literally treats this type of modification as if the container was given a new list.
For example, if an application wished to change a currently-set exclusive item, the application would have to unset the currently-set item and set the new item. If the application only set the new item, the container would generate a warning since the item list contains more than one set item.
The following example shows how a callback procedure changes the set item by modifying the item list. This example makes the first item be the set item whenever the last item is selected. Notice that once the list has been touched, the application must ’inform’ the container of the modification. Also notice that in this example the application needs to know the structure of the application to directly change its contents.
/∗ Application Defined Structure
∗ from previous example ∗/
typedef struct {
XtArgVal label; /∗ pointer to a string ∗/
XtArgVal select_proc; /∗ pointer to a callback procedure ∗/
XtArgVal set; /∗ this item is currently set ∗/
XtArgVal sensitive; /∗ this item is sensitive ∗/
} FlatExclusives;
Callback(widget, client_data, call_data)
Widget widget; /∗ FlatExclusives Widget id ∗/
XtPointer client_data; /∗ application’s client data ∗/
XtPointer call_data; /∗ OlFlatCallData structure pointer ∗/
{
OlFlatCallData ∗ fcd = (OlFlatCallData ∗) call_data;
if (fcd->num_items == (fcd->item_index + 1))
{
FlatExclusives ∗ fexc_items = (FlatExclusives ∗) fcd->items;
Arg args[1];
/∗ Unset this item and
∗ set the first one ∗/
fexc_items[fcd->item_index].set = FALSE;
fexc_items[0].set = TRUE;
/∗ Inform the container that the list
∗ was modified ∗/
XtSetArg(args[0], XtNitemsTouched, TRUE);
XtSetValues(widget, args, 1);
}
} /∗ END OF Callback() ∗/
Getting the State of a Sub-Object
Obtaining the state of a sub-object can be achieved in two ways:
1.Using the OlFlatGetValues routine, specify the index of the item to be queried.
OlFlatGetValues(widget, item_index, args, num_args)
Widget widget; /∗ flat widget id ∗/
Cardinal item_index; /∗ item to query ∗/
ArgList args; /∗ query resources ∗/
Cardinal num_args; /∗ number of query resources ∗/
If this approach is used, the application can query any sub-object resource even though it does not appear in the item fields. In the initial example for instance, the application can query the XtNfontColor resource from any sub-object even though it does not appear in the FlatExclusives structure.
2.Looking directly into the sub-object list since both the application and flat container share the same instance of the sub-object description.
EXAMPLE
Obtaining Help on a Sub-Object
The application can specify a unique help message for each sub-object in a similar fashion as help is registered for widgets, i.e., through the OlRegisterHelp routine. Since sub-objects are not real widgets, but are extensions of the flat widget container, the help registration routine has a complex id:
typedef struct {
Widget widget; /∗ Flat Widget id ∗/
Cardinal item_index; /∗ item to register help on ∗/
} OlFlatHelpId;
The following example registers help on item number 8.
static String tag = "Item 8";
static String source = "Item 8’s help";
OlFlatHelpId help_id;
help_id.widget = flat_widget;
help_id.item_index = 8;
OlRegisterHelp((XtPointer) &help_id, OL_FLAT_HELP, tag,
OL_STRING_SOURCE, source);
SEE ALSO
Version 3.0.1 — Last change: June 92