NAME

ControlArea − control area widget

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/ControlAre.h>
 . . .
Widget my_controlarea, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_controlarea =  XtCreate( my_name, controlAreaWidgetClass,

my_parent, args, num_args);

DESCRIPTION

Components

The ControlArea widget has zero or more Child Widgets and an optional Border. 

Layout Control

The ControlArea is a composite widget, that presents its child widgets to the end-user as a group of “controls”.  The application can choose one of four simple layout schemes:

Fixed number of columns in the control pane,

fixed number of rows,

fixed overall width of the control area,

and fixed overall height. 

The application can also specify the inter-control spacing and the size of the margin around the children. 

Equal Height Rows

The children in each row align at the top of the row.  The distance between the top of one row and the next is the height of the tallest control in the row plus the application specified inter-row spacing. 

Coloration

of the ControlArea widget. 

  Figure 1 Control Area Coloration

RESOURCES

  Table 1 ControlArea Resource Set

ControlArea          Resource       Set
Name                 Type           Default             Access
 
XtNalignCaptions     Boolean        FALSE               SGI
XtNancestorSensitive Boolean        TRUE                GO
XtNbackground        Pixel          XtDefaultBackground SGI
XtNbackgroundPixmap  Pixmap         (none)              SGI
XtNborderColor       Pixel          XtDefaultForeground SGI
XtNborderPixmap      Pixmap         (none)              SGI
XtNborderWidth       Dimension      0                   SGI
XtNcenter            Boolean        FALSE               SGI
XtNconsumeEvent      XtCallbackList NULL                SG
XtNdepth             int            (parent’s)          GI
XtNdestroyCallback   XtCallbackList NULL                SI
XtNhPad              Dimension      4                   SGI
XtNhSpace            Dimension      4                   SGI
XtNheight            Dimension      (calculated)        SGI
XtNlayoutType        OlDefine       OL_FIXEDROWS        SGI
XtNmappedWhenManaged Boolean        TRUE                SGI
XtNmeasure           int            1                   SGI
 
TRAVERSAL            XtNnextTop     XtCCallback         XtCallbackList
XtNsameSize          OlDefine       OL_COLUMNS          SGI
XtNsensitive         Boolean        TRUE                GIO
 
TRANSPARENT          XtNtransparent XtCTransparent      Boolean
XtNtraversalManager  Boolean        FALSE               SGI
XtNuserData          XtPointer      NULL                SGI
XtNvPad              Dimension      4                   SGI
XtNvSpace            Dimension      4                   SGI
XtNwidth             Dimension      (calculated)        SGI
XtNx                 Position       0                   SGI
XtNy                 Position       0                   SGI

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access
† see resources(3W)

XtNalignCaptions

 class:XtCAlignCaptions type:Boolean default:FALSEaccess:SGI

Action: controls how the ControlArea widget aligns caption widgets. 

Values: TRUE, FALSE

If set to TRUE the ControlArea will align all Caption widgets in each column so that their captions are right justified.  This may affect the width calculation for a column. 

The effective width for the Caption widgets in a column becomes the sum of the width of the widest caption, plus the largest caption/child widget separation and child widget width.  This alignment is only for groups of Caption widgets with all their captions on the left or the right. 

Mixed orientation, or captions above or below, cannot be aligned well. 

  Figure 2 Aligning Captions

If the XtNalignCaptions resource is set to FALSE the ControlArea will align all Caption widgets the same as other widgets—by their overall width.  This resource takes precedence over the XtNcenter resource, but only for Caption widgets. 

XtNcenter

 class:XtCCenter type:Boolean default:FALSEaccess:SGI
 class:XtCCentertype:Booleandefault:FALSEaccess:SGI

Action: controls how the ControlArea orients each widget within a column. 

Values: TRUE – center each widget with each column.  FALSE – left justify each widget within each column, unless the XtNalignCaptions resource is TRUE.

See Also: XtNalignCaptions. 

XtNhPad

 class:XtCHPad type:Dimension default:4access:SGI

XtNvPad

 class:XtCVPad type:Dimension default:4access:SGI

Action: sets the amount of padding, in pixels, to leave around the edges of the control area. 

Values: 0 ≤ XtNhPad , 0 ≤ XtNvPad

The caption of this resource is

  Figure 3 Padding Around Controls

XtNhSpace

 class:XtCHSpace type:Dimension default:4access:SGI
 class:XtCHSpacetype:Dimensiondefault:4access:SGI

XtNvSpace

 class:XtCVSpace type:Dimension default:4access:SGI

Action: set the amount of space, in pixels, to leave between controls. 

Values: 0 ≤ XtNhSpace , 0 ≤ XtNvSpace

If the controls are of different sizes in a row or column, the spacing applies to the widest or tallest dimension of all the controls. 

  Figure 4 Spacing Between Controls

XtNlayoutType

 class:XtCLayoutType type:OlDefine default:OL_FIXEDROWSaccess:SGI
 class:XtCLayoutTypetype:OlDefinedefault:OL_FIXEDROWSaccess:SGI

Action: controls the layout of the child widgets by the ControlArea. 

Values: OL_FIXEDROWS/fixedrows if the layout should have a fixed number of rows and enough columns to hold all the controls; OL_FIXEDCOLS/fixedcols if the layout should have a fixed number of columns and enough rows to hold all the controls; OL_FIXEDWIDTH/fixedwidth if the layout should be of a fixed width but tall enough to hold all the controls; OL_FIXEDHEIGHT/fixedheight if the layout should be of a fixed height but wide enough to hold all the controls.

The XtNmeasure resource gives the number of rows or columns or the fixed height or width. 

The choices are to specify the number of rows or columns, or to specify the overall height or width of the layout area.  Only one of these dimensions can be specified directly; the other is determined by the number of controls added. 

For instance, if the application specifies that the control area should have four columns, the number of rows will be the number of controls divided by four. 

XtNmeasure

 class:XtCMeasure type:int default:1access:SGI

Action: gives the number of rows or columns in the layout of the child widgets, or the fixed width or height of the control area. 

Values: 0 < XtNmeasure

Default: If XtNlayoutType is OL_FIXEDROWS or OL_FIXEDCOLS then 1.  If XtNlayoutType is OL_FIXEDWIDTH or OL_FIXEDHEIGHT then the width or height of widest or tallest widget, depending on XtNlayoutType.

When XtNlayoutType is OL_FIXEDWIDTH or OL_FIXEDHEIGHT the measure includes the padding on both edges and the inter-control spacing,

  Figure 5 XtNmeasure

XtNsameSize

 class:XtCSameSize type:OlDefine default:OL_COLUMNSaccess:SGI

Action: determines which controls, if any, within the ControlArea widget are forced to be the same width

Values: OL_NONE The controls are placed in fixed-width columns, but the size of each control is left alone.  The width of each column is the width of the widest control in the column.  OL_COLUMNS Controls in each column are made the same width as the widest of them. The width of each column is thus the width of the widest control in the column. OL_ALL All controls are made the same width, the width of the widest control in the ControlArea widget.
 
 

Version 3.0  —  19 July 91