WIDGET CLASS NAME

ControlArea

SYNOPSIS

#include <Intrinsic.h>
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <ControlAre.h>

widget = XtCreateWidget(name, controlAreaWidgetClass, ...);
widget = XtCreateWidget(name, controlAreaWidgetClass, ...);

DESCRIPTION

ControlArea Components

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

The ControlArea composite widget arranges its child widgets, presenting them 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.  Keyboard Traversal

Users can traverse among Text and TextField widgets within any ancestor ControlArea, BulletinBoard, or Form widget using the NEXTFIELD and PREVFIELD keys:

—NEXTFIELD moves the caret to the next traversable Text or TextField widget in the managing ancestor widget.  When the caret is in the last traversable field, NEXTFIELD moves the caret to the first traversable field. 

—PREVFIELD moves the caret to the previous traversable field in the managing ancestor widget.  When the caret is in the first traversable field, PREVFIELD moves the caret to the last traversable field. 

The default key mappings for NEXTFIELD and PREVFIELD are TAB and SHIFT-TAB, respectively.  A user may change these defaults through the appropriate Workspace Properties window.  ControlArea Coloration

the diagram Control Area Coloration illustrates the resources that affect the 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       G∗
       XtNbackground           Pixel         White  SGI†
 XtNbackgroundPixmap          Pixmap        (none)  SGI†
      XtNborderColor           Pixel         Black  SGI†
     XtNborderPixmap          Pixmap        (none)  SGI†
      XtNborderWidth       Dimension             0      SGI
           XtNcenter         Boolean         FALSE      SGI
            XtNdepth             int    (parent’s)       GI
  XtNdestroyCallback  XtCallbackList          NULL       SI
             XtNhPad       Dimension             4      SGI
           XtNhSpace       Dimension             4      SGI
           XtNheight       Dimension  (calculated)      SGI XtNmappedWhenManaged         Boolean          TRUE      SGI
ControlArea Resource Set (cont.)
               Name       Type       Default  Access
         XtNmeasure        int             1     SGI
       XtNsensitive    Boolean          TRUE     GI∗ 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 XtNalignCaptions

Range of Values:

TRUE
TRUE
FALSE

This resource controls how the ControlArea widget aligns widgets of the Caption class.  If set to TRUE, 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 XtNalignCaption XtNalignCaption resource is set to FALSE, FALSE, the ControlArea will align all Caption widgets the same as other widgets—by their overall width. 

This resource takes precedence over the XtNcenter XtNcenter resource, but only for Caption widgets.  XtNcenter

Range of Values:

TRUE
TRUE
FALSE

This resource controls how the ControlArea widget orients each widget within a column (although see also XtNalignCaptions).  XtNalignCaptions).  If set to TRUE, TRUE, the ControlArea will center each widget with each column; if set to FALSE, FALSE, the ControlArea will left justify each widget within each column, unless the XtNalignCaptions XtNalignCaptions resource is TRUE.  TRUE.  XtNhPad
XtNvPad

Range of Values:

0 ≤ XtNhPad
0 ≤ XtNhPad
0 ≤ XtNvPad

These resources give the amount of padding, in pixels, to leave around the edges of the control area, left and right, and top and bottom, respectively, as suggested by the diagram Padding Around Controls. 

  Figure 3 Padding Around Controls

XtNhSpace
XtNvSpace

Range of Values:

0 ≤ XtNhSpace
0 ≤ XtNhSpace
0 ≤ XtNvSpace

These resources give the amount of space, in pixels, to leave between controls horizontally and vertically, respectively.  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

Range of Values:

OL_FIXEDROWS/"fixedrows"
OL_FIXEDROWS/"fixedrows"
OL_FIXEDCOLS/"fixedcols"
OL_FIXEDWIDTH/"fixedwidth"
OL_FIXEDHEIGHT/"fixedheight"

This resource controls the layout of the child widgets by the ControlArea composite.  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.  The values of the XtNlayoutType XtNlayoutType resource can be:

OL_FIXEDROWS

OL_FIXEDROWS
if the layout should have a fixed number of rows and enough columns to hold all the controls;

OL_FIXEDCOLS

OL_FIXEDCOLS
if the layout should have a fixed number of columns and enough rows to hold all the controls;

OL_FIXEDWIDTH

OL_FIXEDWIDTH
if the layout should be of a fixed width but tall enough to hold all the controls;

OL_FIXEDHEIGHT

OL_FIXEDHEIGHT
if the layout should be of a fixed height but wide enough to hold all the controls.

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

Range of Values:

0 < XtNmeasure 0 < XtNmeasure

Default:

If XtNlayoutType is OL_FIXEDROWS or OL_FIXEDCOLS: 1 If XtNlayoutType is OL_FIXEDROWS or OL_FIXEDCOLS: 1
If XtNlayoutType is OL_FIXEDWIDTH or OL_FIXEDHEIGHT: If XtNlayoutType is OL_FIXEDWIDTH or OL_FIXEDHEIGHT:

width or height of widest or tallest widget, depending on width or height of widest or tallest widget, depending on XtNlayoutType.  XtNlayoutType. 

This resource gives the number of rows or columns in the layout of the child widgets, or the fixed width or height of the control area.  When XtNlayoutType XtNlayoutType is OL_FIXEDWIDTH OL_FIXEDWIDTH or OL_FIXEDHEIGHT, OL_FIXEDHEIGHT, the measure includes the padding on both edges and the inter-control spacing, as suggested by the diagram XtNmeasure. 

  Figure 5 XtNmeasure XtNsameSize

Range of Values:

OL_NONE/"none"
OL_NONE/"none"
OL_COLUMNS/"columns"
OL_ALL/"all"

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

OL_NONE

OL_NONEThe 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

OL_COLUMNS
Controls of the same class 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

OL_ALLAll controls are made the same width, the width of the widest control in the ControlArea widget. 

XtNtraversalManager

This resource controls whether this widget manages traversal for its descendants. 

Sun Release 4.1  —  Last change: 1/8/90