RectButton(3W) UNIX System V RectButton(3W)
NAME
RectButton - a primitive widget consisting of a label surrounded by a
rectangular border
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <RectButton.h>
widget = XtCreateWidget(name, rectButtonWidgetClass, ...);
DESCRIPTION
RectButton Components
The RectButton widget implements one of the OPEN LOOK button widgets. It
consists of a Label surrounded by a rectangular Border. The Border can
change to reflect that the button may be a default of several buttons
(double border), or represents a current state of an object (thick
border), or represents a current state of one of several objects with
different states (dimmed border).
Figure 1 shows several buttons, in normal, default, and current states
(two versions).
Figure 1. Rectangular Buttons
Use of Rectangular Buttons
Rectangular buttons are not used alone but in one of the Exclusives or
Nonexclusives composite widgets for implementing a one-of-many or
several-of-many selection. Making this widget a child of a different
composite widget will not produce an error message, but proper behavior
is not guaranteed.
Toggling the State
A RectButton widget has two states: "set" and "not set". (When set, its
border is thickened.) Toggling this state alternates a resource (XtNset)
between "true" and "false" and starts an action associated with the
button. The RectButton widget is typically toggled by the user using
SELECT or MENU, except that it is possible to disable user toggling of a
button that is already set.
Work in Exclusives/Nonexclusives Only
If a RectButton widget is not the child of an Exclusives or NonExclusives
widget, it will toggle between set and unset status, as in Nonexclusives.
Rectangular Buttons in a Pop-up Menu
Entering a rectangular button while MENU is depressed changes the
appearance of the button from unset to set state or vice versa, to
reflect the state the button would be in if MENU were released.
Releasing MENU toggles the state associated with the button. Leaving the
button before releasing MENU restore the original state appearance and
does not toggle the button.
10/89 Page 1
RectButton(3W) UNIX System V RectButton(3W)
Rectangular Buttons Not in a Pop-up Menu
Clicking SELECT on a rectangular button toggles the state associated with
it. Pressing SELECT, or moving the pointer into the button while SELECT
is pressed, changes the border from unset to set state or vice versa, to
reflect the state the button would be in if SELECT were released.
Releasing SELECT toggles the state. Moving the pointer off the button
before releasing SELECT restores the state appearance and does not toggle
the button. but does not toggle the state.
If the button is in a stay-up menu, clicking or pressing MENU works the
same as SELECT. If the button is not in a stay-up (or pop-up) menu,
clicking or pressing MENU does not do anything; the event is passed up to
an ancestor widget.
RectButton Coloration
Figure 2 illustrates the resources that affect the coloration of the
RectButton widget.
On a monochrome display, the RectButton widget indicates that it has
input focus by inverting the foreground and background colors of the
control.
On color displays, when the RectButton widget receives the input focus,
the background color is changed to the input focus color set in the
XtNinputFocusColor resource.
EXCEPTIONS:
- If the input focus color is the same as the font color for the control
labels, then the coloration of the active control is inverted.
- If the input focus color is the same as the Input Window Header Color
and the active control is in the window header, then invert the colors.
- If the input focus color is the same as the window background color,
then the RectButton widget inverts the foreground and background colors
when it has input focus.
Figure 2. Rectangular Button Coloration
Keyboard Traversal
The default value of the XtNtraversalOn resource is True.
The RectButton widget responds to the following keyboard navigation keys:
- NEXT_FIELD moves to the next traversable widget in the window
- PREV_FIELD moves to the previous traversable widget in the window
- MOVEUP moves to the RectButton above the current widget in the
Nonexclusives or Exclusives composite
Page 2 10/89
RectButton(3W) UNIX System V RectButton(3W)
- MOVEDOWN moves to the RectButton below the current widget in the
Nonexclusives or Exclusives composite
- LEFT moves to the RectButton to the left of the current widget in the
Nonexclusives or Exclusives composite
- MOVERIGHT moves to the RectButton to the right of the current widget in
the Nonexclusives or Exclusives composite
- 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
The RectButton will respond to the SELECTKEY by acting as if the SELECT
buttons had been clicked.
_________________________________________________________________________
| RectButton Activation Types |
|_____________________________|__________________________________________|
| Activation Type | Expected Results |
|_____________________________|__________________________________________|
| OL_MENUDEFAULTKEY | Set the sub-object as the |
| | shell's default object (if on |
| | a menu) |
| OL_SELECTKEY | Call its callbacks |
|_____________________________|__________________________________________|
Display of Keyboard Mnemonic
The RectButton widget displays the mnemonic accelerator for its child as
part of its label. If the mnemonic character is in the label, then that
character is highlighted according to the value returned by
OlQueryMnemonicDisplay(). If the mnemonic character is not in the label,
it is displayed to the right of the label in parenthesis and highlighted
according to the value returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parenthesis is
truncated as a unit.
Display of Keyboard Accelerators
The RectButton widget displays the keyboard accelerator as part of its
label. The string in the XtNacceleratorText resource is displayed to the
right of the label (or mnemonic) separated by at least one space. The
acceleratorText is right justified.
If truncation is necessary, the accelerator is truncated as a unit. The
accelerator is truncated before the mnemonic or the label.
10/89 Page 3
RectButton(3W) UNIX System V RectButton(3W)
RESOURCES
__________________________________________________________________________________________
| RectButton Resource Set |
|_____________________|______________________|________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|__________________|________|
__________________________________________________________________________________________
XtNaccelerator XtCAccelerator String NULL SGI
__________________________________________________________________________________________
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
__________________________________________________________________________________________
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
__________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
__________________________________________________________________________________________
XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI†
__________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
__________________________________________________________________________________________
XtNdefault XtCDefault Boolean FALSE SGI
__________________________________________________________________________________________
XtNdepth XtCDepth int (parent's) GI
__________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
__________________________________________________________________________________________
XtNdim XtCDim Boolean FALSE SGI
__________________________________________________________________________________________
XtNfont XtCFont XFontStruct * (OPEN LOOK font) SI
__________________________________________________________________________________________
XtNfontColor XtCFontColor Pixel Black* SGI
__________________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI†
__________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
__________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
__________________________________________________________________________________________
XtNlabel XtCLabel String (class name) SGI
__________________________________________________________________________________________
XtNlabelImage XtCLabelImage XImage * NULL SGI
__________________________________________________________________________________________
XtNlabelJustify XtCLabelJustify OlDefine OL_LEFT SGI
__________________________________________________________________________________________
XtNlabelTile XtCLabelTile Boolean FALSE SGI
__________________________________________________________________________________________
XtNlabelType XtCLabelType int OL_STRING SGI
__________________________________________________________________________________________
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
__________________________________________________________________________________________
XtNmnemonic XtCMnemonic unsigned char NULL SGI
__________________________________________________________________________________________
XtNreferenceName XtCReferenceName String NULL SGI
Page 4 10/89
RectButton(3W) UNIX System V RectButton(3W)
__________________________________________________________________________________________
| RectButton Resource Set |
|_____________________|______________________|________________|__________________|________|
| Name | Class | Type | Default | Access|
|_____________________|______________________|________________|__________________|________|
|_____________________|______________________|________________|__________________|________|
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNrecomputeSize | XtCRecomputeSize | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNselect | XtCCallback | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|__________________|________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_____________________|______________________|________________|__________________|________|
| XtNset | XtCSet | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNunselect | XtCCallback | XtCallbackList| NULL | SI |
|_____________________|______________________|________________|__________________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_____________________|______________________|________________|__________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_____________________|______________________|________________|__________________|________|
XtNdefault
Range of Values:
TRUE
FALSE
If this resource is TRUE, the Border is doubled to two lines, to show
that the button is the default choice of one or more buttons.
XtNdim
Range of Values:
TRUE
FALSE
If this resource is TRUE, then the button border is dimmed to show that
the button represents the state of one or more of several objects that,
as a group, are in different states.
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
10/89 Page 5
RectButton(3W) UNIX System V RectButton(3W)
This resource identifies the font to be used to display the Label.
The default value points to a cached font structure; an application
should not expect to get this value with a call to XtGetValues() and use
it reliably thereafter.
XtNfontColor
Range of Values:
(any Pixel value valid for the current display)/(any name from the
rgb.txt file)
This resource specifies the color for the font. If not set, the color
from the XtNforeground resource, if available, is used for the font.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNforeground
This resource defines the foreground color for the widget.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources, Section 2.
XtNlabel
This resource is a pointer to the text for the Label. This resource is
ignored if the XtNlabelType resource has the value OLIMAGE.
XtNlabelImage
This resource is a pointer to the image for the Label. This resource is
ignored unless the XtNlabelType resource has the value OLIMAGE.
If the image is of type XYBitmap, the image is highlighted when
appropriate by reversing the 0 and 1 values of each pixel (i.e. by
"`xor'ing" the image data). If the image is of type XYPixmap or ZPixmap,
the image is not highlighted, although the space around the image inside
the Border is highlighted.
If the image is smaller than the space available for it inside the Border
and XtNlabelTile is FALSE, the image is centered vertically and either
centered or left-justified horizontally, depending on the value of the
XtNlabelJustify resource. If the image is larger than the space
available for it, it is clipped so that it does not stray outside the
Border. If the XtNdefault resource is TRUE so that the Border is
doubled, the space available is that inside the inner line of the Border.
XtNlabelJustify
Range of Values:
OLLEFT/"left"
OLCENTER/"center"
Page 6 10/89
RectButton(3W) UNIX System V RectButton(3W)
This resource dictates whether the Label should be left-justified or
centered within the widget width.
XtNlabelTile
Range of 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.
XtNlabelType
Range of Values:
OLSTRING/"string"
OLIMAGE/"image"
This resource identifies the form that the Label takes. It can have the
value OLSTRING or OLIMAGE for text or image, respectively.
XtNrecomputeSize
Range of Values:
TRUE
FALSE
This resource indicates whether the RectButton widget should calculate
its size and automatically set the XtNheight and XtNwidth resources. If
set to TRUE, the RectButton widget will do normal size calculations that
may cause its geometry to change. If set to FALSE, the RectButton widget
will leave its size alone; this may cause truncation of the visible image
being shown by the RectButton widget if the fixed size is too small, or
may cause padding if the fixed size is too large. The location of the
padding is determined by the XtNlabelJustify resource.
XtNselect
This is the list of callbacks invoked when the widget is selected.
XtNset
Range of Values:
TRUE
FALSE
This resource reflects the current state of the button. The button's
border is thickened to show a TRUE state.
10/89 Page 7
RectButton(3W) UNIX System V RectButton(3W)
XtNunselect
This is the list of callbacks invoked when a RectButton widget is toggled
into the ``unset'' mode by the end user to make XtNset be FALSE. Note
that simply setting XtNset to FALSE with a call to XtSetValues() does not
issue the XtNunselect callbacks.
XtNdim, XtNdefault, XtNset
The XtNdim, XtNdefault, and XtNset resources can be set independently;
however, all these states cannot be reflected in the visual appearance of
the rectangular button, as the state table in Figure 3 shows.
Figure 3. Rectangular Button Appearance when Set/Default/Dim
Label Appearance
The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources
interact to produce a truncated, clipped, centered, or left-justified
label as shown in Figure 4.
Figure 4. Label Appearance
When the label is centered or left-justified, the extra space is filled
with the background color of the RectButton widget, as determined by the
XtNbackground and XtNbackgroundPixmap resources.
When the label is truncated, a solid-black triangle is inserted to show
that part of the label is missing. The triangle requires that more of
the label be truncated than would otherwise be necessary. If the width
of the button is too small to show even one character with the triangle,
only the triangle is shown. If the width is so small that the entire
triangle cannot be shown, the triangle is clipped on the right.
See also the XtNlabelTile resource for how it affects the appearance of a
label.
Page 8 10/89