NAME

FlatExclusives − flat, exclusive choice widget

SYNOPSIS

#include <Xol/OpenLook.h>
#include <Xol/FExclusive.h>
 . . .

ANCESTRY

Core-Primitive-Flat-FlatExclusives

DESCRIPTION

The FlatExclusives widget provides the same functionality as an Exclusives widget managing RectButtons.  Instead of creating individual Rectbuttons as children of a container widget, it creates sub-objects that have the same behavior as the Rectbuttons. It is useful in applications that use large arrays of exclusive settings since it requires fewer widgets to be created. 

  Figure 1 Flat Exclusives Widget

Selection Control

There are two modes of operation, determined by XtNnoneSet.  In one mode, when XtNnoneSet is FALSE, exactly one sub-object in a FlatExclusives widget must be set. That is, the XtNset resource is TRUE for one of the sub-objects.  A warning is generated if two or more sub-objects are set.  If no items are set, the FlatExclusives makes the first sub-object that is both managed and mapped when managed be the set item.  No warning is produced in this case.  The FlatExclusives maintains this condition by ensuring that when a sub-object is set by the user clicking SELECT over it, the sub-object that was set is cleared and its XtNunselectProc procedure is called and the sub-object under the pointer is made to be set and its XtNselectProc procedure is called.  However, clicking SELECT over a sub-object that is already set does nothing. 

In the other mode of operation, when XtNnoneSet is TRUE, at most one sub-object in a FlatExclusives widget can be "set." A warning is generated if two or more sub-objects are set.  The FlatExclusives maintains this condition by ensuring that when a sub-object is set by the user clicking SELECT over it, the sub-object that was set is cleared and its XtNunselectProc procedure is called and the sub-object under the pointer is made to be set and its XtNselectProc procedure is called.  Clicking SELECT over a sub-object that is already set clears it and its XtNselectProc procedure is called. 

Menu Use

The FlatExclusives widget can be added as child in a menu pane to implement a one-of-many menu choice. 

Coloration

The FlatExclusives container inherits its background color from the container’s parent widget.  Setting the background color affects only the sub-objects’ background. 

Keyboard Traversal

The FlatExclusives widget is a Primitive widget that manages the traversal between a set of sub-objects.  When the user traverses to a FlatExclusives widget, the first sub-object in the set will display itself as having input focus (see the RectButton widget for a description of this appearance.) 

The MOVEUP, MOVEDOWN, MOVERIGHT, and MOVELEFT keys move the input focus between the sub-objects.  To traverse out of the FlatExclusives widget, the following keys can be used:

—NEXT_FIELD moves to the next traversable widget in the window

—PREV_FIELD moves to the previous traversable widget in the window

—NEXTWINDOW moves to the next window in the application. 

—PREVWINDOW moves to the previous window in the application. 

—NEXTAPP moves to the first window in the next application. 

—PREVAPP moves to the first window in the previous application. 

Keyboard Operation

Flat Exclusives Activation Types
OL_MENUDEFAULTKEY: If the FlatExclusives is on a menu, this command will set the item with focus to be menu’s default; otherwise, this command is ignored.
OL_SELECTKEY: This command acts as if the SELECT mouse button had been clicked on the
sub-object with focus.  See "Selection Control" sections
above.

RESOURCES

Sub-object Resources

The following tables list the resources for the FlatExclusives.  Resources marked by a bullet (•) denote sub-object resources.  If these resources are not included in the XtNitemFields list, they are inherited from the container widget.  An application can change the default values for sub-object resources by setting them on the container directly.  Even though a sub-object resource is not included in the XtNitemFields list, the application can query the value of any sub-object resource with OlFlatGetValues(). 

  Table 1 Flat Exclusives Resource Set

Name                      Type           Default             Access
XtNancestorSensitive-    Boolean          TRUE           GO
XtNconsumeEvent-         XtCallbackList   NULL           SG
XtNdepth-                int              (parent’s)     GI
XtNdestroyCallback-      XtCallbackList   NULL           SI
XtNheight-               Dimension        (calculated)   SGI
XtNlayoutType            OlDefine         OL_FIXEDROWS   SGI
XtNmappedWhenManaged-    Boolean          TRUE           SGI
XtNmeasure               int              1              SGI
XtNnoneSet               Boolean          FALSE          SGI
XtNreferenceName-        String           NULL           GI
XtNreferenceWidget-      Widget           NULL           GI
XtNsensitive-            Boolean          TRUE           GIO
XtNtraversalOn-          Boolean          TRUE           SGI
XtNuserData-             XtPointer        NULL           SGI
XtNwidth-                Dimension        (calculated)   SGI
XtNx-                    Position         0              SGI
XtNy-                    Position         0              SGI
XtNlayoutHeight-         OlDefine         OL_MINIMIZE    SGI
XtNlayoutType-           OlDefine         OL_FIXEDROWS   SGI
XtNlayoutWidth-          OlDefine         OL_MINIMIZE    SGI
XtNmanaged               Boolean          TRUE           SGI
XtNmappedWhenManaged-+   Boolean          TRUE           SGI
XtNmeasure-              int              1              SGI
XtNmnemonic-+            unsigned char    NULL           SGI
XtNnoneSet               Boolean          FALSE          SGI
XtNnumItemFields         Cardinal         0              SGI
XtNnumItems              Cardinal         0              SGI
XtNposition+             OlDefine         OL_LEFT        SGI
XtNreferenceName-        String           NULL           SGI
XtNreferenceWidget-      Widget           NULL           SGI
XtNsameHeight-           OlDefine         OL_ALL         SGI
XtNsameWidth-            OlDefine         OL_COLUMNS     SGI
XtNselectProc+           XtCallbackProc   NULL           SGI
XtNsensitive-+           Boolean          TRUE           SGI
XtNset+                  Boolean          FALSE          SGI∗
XtNtraversalOn-+         Boolean          TRUE           SGI
XtNunselectProc+         XtCallbackProc   NULL           SGI
XtNuserData-+            XtPointer        NULL           SGI
XtNvPad-                 Dimension        0              SGI
XtNvSpace-               Dimension        (calculated)   SGI
XtNwidth-                Dimension        (calculated)   SGI
XtNx-                    Position         0              SGI
XtNy-                    Position         0              SGI

Access:   S = XtSetValues   G = XtGetValues
            I = init time   O = other access
• sub-object resources; see below
∗ not inherited from container
† see resources(3W)

XtNancestorSensitive

class:XtCAncestorSensitive type:Boolean default:TRUEaccess:GO

Action: indicates the sensitivity of the sub-object’s ancestors. 

Values: TRUE – all the sub-object’s ancestors are sensitive and the sub-object is sensitive to user input.  FALSE – one or more of the sub-object’s ancestors are insensitive, so the sub-object displays an inactive visual and is not sensitive to user input.

XtNbackground

class:XtCBackground type:Pixel default:XtDefaultBackgroundaccess:SGI

Action: indicates the pixel color used to fill in the background of the sub-object. 

XtNbackgroundPixmap

class:XtCBackgroundPixmap type:Pixmap default:Noneaccess:SGI

Action: specifies the pixmap that is displayed as the sub-object’s label. 

Any supplied pixmap must have the same depth as the flat widget’s depth.  Pixmaps of None and ParentRelative are not considered valid values.  If either XtNlabel or XtNlabelImage has a non-NULL value, this resource is ignored. 

XtNclientData

class:XtCClientData type:XtPointer default:NULLaccess:SGI

Action: indicates the client data supplied to all callback procedures. 

XtNdefault

class:XtCDefault type:Boolean default:FALSEaccess:SGI

Action: When used on the container, this resource indicates whether or not one of the sub-objects is a default item. 

Values: TRUE – If a sub-object is a default item FALSE – otherwise

Setting this resource on the container widget indicates whether or not one of the sub-objects should be a default item. 

If the application sets this value to

TRUE on the container, the container will set the first managed and mapped sub-object as the default item if a default item does not exist. 

FALSE the container will unset its default item if one exists. 

Even if the application does not use XtNdefault in its item fields list, the container will correctly maintain the default item and the application can change the default item via OlFlatSetValues .

When used on the sub-object, this resource specifies whether or not the sub-object is a default item.  If more than one item is a set as a default item, a warning is generated and all but the first default item is unselected. 

XtNdim

class:XtCDim type:Boolean default:FALSEaccess:SGI

Action: indicates substate changes visually

Values: TRUE – the sub-object shows a dimmed visual indicating that the item represents the state of one or more objects, that as a group, are in different states.  FALSE – otherwise

XtNfont

class:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI

Action: specifies the font for the string specified by the XtNlabel resource. 

XtNfontColor

class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the foreground color of the sub-object’s label, even if the label is an XImage. 

XtNforeground

class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI

Action: specifies the pixel color used when drawing the sub-object’s outline in 2-D mode. 

XtNitems

class:XtCItems type:XtPointer default:NULLaccess:SGI

Action: specifies 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. 

XtNitemFields

class:XtCItemFields type:String default:NULLaccess:GI

Action: This is the list of resource names used to parse the records in the XtNitems list.  This resource does not have to point to static information since the flat container does not use this information after initialization.  Though the flat container does not reference this resource’s value after initialization, it holds onto it for responding to an XtGetValues() request and supplying 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. 

XtNitemsTouched

class:XtCItemsTouched type:Boolean default:FALSEaccess:SG

Action: Whenever the application modifies an item list directly, it must supply this resource (with a value of TRUE) to the flat widget container so that the container can update the visual. 

Values: TRUE, FALSE

If the resource value is supplied, the flat widget container treats its current item list as a new list and hence, updates its entire visual.  Since the list is treated as a new list, the flat container may request a change in geometry from its parent. 

Note: It is not necessary to use this resource if the application modifies the list with the OlFlatSetValues procedure; nor is it necessary to use this resource whenever the application supplies a new list to the flat container. 

XtNlabel

class:XtCLabel type:String default:NULLaccess:SGI

Action: specifies the text string that appears in the sub-object. 

XtNlabelImage

class:XtCLabelImage type:XImage default:NULLaccess:SGI

Action: specifies an XImage pointer that can appear in a sub-object. 

This resource is ignored if XtNlabel is non-NULL. 

XtNlabelJustify

class:XtCLabelJustify type:OlDefine default:OL_LEFTaccess:SGI

Action: specifies the justification of the label of sub-object. 

Values: OL_LEFT, OL_CENTER, OL_RIGHT. 

XtNlabelTile

class:XtCLabelTile type:Boolean default:FALSEaccess:SGI

Action: specifies tiling of subobject’s background. 

Values: TRUE, FALSE

This resource augments the XtNlabelImage/XtNlabelPixmap resource to allow tiling of the sub-object’s background.  For an image/pixmap that is smaller than the sub-object’s background, the label area is tiled with the image/pixmap to fill the sub-object’s background if this resource is TRUE.  Otherwise, the label is placed as described by the XtNlabelJustify resource.  The XtNlabelTile resource is ignored for text labels. 

XtNmanaged

class:XtCManaged type:Boolean default:TRUEaccess:SGI

Action: Determines whether the FlatExclusives widget manages its sub-objects. 

Values: TRUE – the widget manages its sub-objects.  FALSE – the widget doesn’t manage its sub-objects.

XtNmappedWhenManaged

class:XtCMappedWhenManaged type:Boolean default:TRUEaccess:SGI

Action: specifies whether or not a managed sub-object is displayed. 

Values: TRUE, FALSE

Note: This resource is never inherited from the container, so its default value is always TRUE

Regardless of this resource’s value, all managed sub-objects will be included when determining the layout. 

XtNnoneSet

class:XtCNoneSet type:Boolean default:FALSEaccess:SGI

Action: controls whether the settings can be toggled into an unset mode directly. 

Values: TRUE – zero or more than one sub-object can be set at any time.  The user can select the currently set sub-object and toggle it back to an unset state.  FALSE – exactly one sub-object must be in the set state always. Attempting to select the currently set sub-object does nothing.

XtNnumItems

class:XtCNumItems type:Cardinal default:0access:SGI

Action: specifies the number of sub-object items. 

XtNnumItemFields

class:XtCNumItemFields type:Cardinal default:0access:SGI

Action: indicates the number of resource names contained in XtNitemFields

XtNsameHeight

class:XtCSameHeight type:OlDefine default:OL_ALLaccess:SGI

Action: specifies the rows that are forced to the same height. 

Values: OL_ALL, OL_ROWS

XtNsameWidth

class:XtCSameWidth type:OlDefine default:OL_COLUMNSaccess:SGI

Action: specifies the columns that are forced to the same width. 

Values: OL_ALL, OL_COLUMNS

XtNselectProc

class:XtCCallbackProc type:XtCallbackProc default:NULLaccess:SGI

Action: specifies the callback procedure for the sub-object becoming selected by user input. 

XtNsensitive

class:XtCSensitive type:Boolean default:TRUEaccess:SGI

Action: specifies sensitivity to user input

Values: TRUE – the sub-object is sensitive to user input.  FALSE – the sub-object is insensitive to user input and an inactive visual is displayed to indicate this state.

Note: This resource is never inherited from the container, so its default value is always TRUE. 

XtNset

class:XtCSet type:Boolean default:FALSEaccess:SGI

Action: reflects the current state of the sub-object. 

Values: TRUE, FALSE

Note: This resource is never inherited from the container, so its default value is always FALSE

Even if the application does not use XtNset in its item fields list, the container will correctly maintain the set item and the application can change the set item via OlFlatSetValues. 

XtNunselectProc

class:XtCCallbackProc type:XtCallbackProc default:NULLaccess:SGI

Action: specifies the callback procedure for the sub-object becoming unselected by user input. 
 

Version 3.0.1  —  Last change: June 92