OblongButton(3W) UNIX System V OblongButton(3W)
NAME
OblongButton - a one-choice element or button used to execute a command
SYNOPSIS
#include <Intrinsic.h>
#include <OpenLook.h>
#include <StringDefs.h>
#include <OblongButt.h>
widget = XtCreateWidget(name, oblongButtonWidgetClass, ...);
OR widget = XtCreateWidget(name, oblongButtonGadgetClass, ...);
DESCRIPTION
OblongButton Components
The OblongButton consists of a Label surrounded by a rounded oblong,
Border.
Figure 1. Oblong Buttons
Busy Button while Action Takes Place
Each OblongButton is associated with an application-defined action
implemented as a list of callbacks. To let the end user know that an
action is still taking place, the OblongButton stipples the area inside
the border before issuing the callbacks. When the last callback returns,
the OblongButton restores its original appearance. If the application's
action continues to be "busy" after the callbacks return, the application
should set the XtNbusy resource to TRUE before returning from the
callbacks, then reset it to FALSE when the action is no longer taking
place.
The "busy" stipple pattern is designed to show enough dots to gray the
button noticeably, while still leaving a text label legible.
Oblong Buttons in a Pop-up Menu
Entering an oblong button while MENU is depressed previews the set
appearance of the button. Releasing MENU then restores the original
appearance and invokes the action for the button as described above.
Leaving the button before releasing MENU restores the appearance but does
not invoke the action.
Oblong Buttons not in a Pop-up Menu
Clicking SELECT on an oblong button starts the action associated with the
button. Pressing SELECT, or moving the pointer into the button while
SELECT is pressed, previews the set appearance of the button. Releasing
SELECT restores the appearance and invokes the action for the button as
described above. Moving the pointer off the button before releasing
SELECT also restores the appearance, but does not invoke the action.
If the oblong button is in a stay-up menu, clicking or pressing MENU
works the same as SELECT. If the oblong 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.
10/89 Page 1
OblongButton(3W) UNIX System V OblongButton(3W)
OblongButton Gadgets
OblongButton gadgets cannot be parents (i.e., be used as the parent
parameter when creating a widget or other gadget).
Correct button behavior is not guaranteed if gadgets are positioned so
that they overlap.
Gadgets share some core fields but, since they are not subclasses of
Core, do not have all Core fields. In particular, they don't have a name
field or a translation field (so translations cannot be
specified/overriden).
Event Handlers cannot be added to gadgets using XtAddEventHandler.
OblongButton Coloration
Figure 2 illustrates the resources that affect the coloration of the
OblongButton widget.
Note: Events that occur outside the Border (but within the OblongButton
widget) are still in the domain of the button.
On a monochrome display, the OblongButton widget indicates that it has
input focus by inverting the foreground and background colors of the
control.
On color displays, when the OblongButton 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 and fonts 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 the colors are
inverted.
- If the input focus color is the same as the window background color,
then the OblongButton widget inverts the foreground and background
colors when it has input focus.
Page 2 10/89
OblongButton(3W) UNIX System V OblongButton(3W)
Figure 2. Oblong Button Coloration
Keyboard Traversal
The default value of the XtNtraversalOn resource is True.
The OblongButton widget responds to the following keyboard navigation
keys:
- NEXT_FIELD, MOVEDOWN, and MOVERIGHT move to the next traversable widget
in the window
- PREV_FIELD, MOVEUP, and MOVELEFT move 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
The OblongButton will respond to the SELECTKEY by acting as if the SELECT
buttons had been clicked.
_________________________________________________________________________
| Oblong Button/Gadget 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 OblongButton 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 displayed/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
displayed/highlighted according to the value returned by
OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parenthesis is
truncated as a unit.
10/89 Page 3
OblongButton(3W) UNIX System V OblongButton(3W)
Display of Keyboard Accelerators
The OblongButton 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.
RESOURCES
____________________________________________________________________________________________
| OblongButton 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†
____________________________________________________________________________________________
XtNbusy XtCBusy Boolean FALSE SGI
____________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
____________________________________________________________________________________________
XtNdefault XtCDefault Boolean FALSE SGI
____________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
____________________________________________________________________________________________
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
____________________________________________________________________________________________
Page 4 10/89
OblongButton(3W) UNIX System V OblongButton(3W)
____________________________________________________________________________________________
| OblongButton Resource Set |
|_______________________|______________________|________________|__________________|________|
| Name | Class | Type | Default | Access|
|_______________________|______________________|________________|__________________|________|
| XtNlabelType | XtCLabelType | OlDefine | OL_STRING | SGI |
|_______________________|______________________|________________|__________________|________|
| ‡ XtNmappedWhenManaged| XtCMappedWhenManaged| Boolean | TRUE | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNmnemonic | XtCMnemonic | unsigned char | NULL | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNrecomputeSize | XtCRecomputeSize | Boolean | TRUE | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNreferenceName | XtCReferenceName | String | NULL | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNselect | XtCCallback | XtCallbackList| NULL | SI |
|_______________________|______________________|________________|__________________|________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_______________________|______________________|________________|__________________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_______________________|______________________|________________|__________________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_______________________|______________________|________________|__________________|________|
‡ These resources are not available to OblongButton gadgets.
XtNbusy
Range of Values:
TRUE
FALSE
This resource controls whether the button interior should be stippled to
show that the action associated with the button is ``busy.'' While
XtNbusy is TRUE, the system will beep if the end user attempts to select
the button; the attempt is refused and no callbacks are invoked.
XtNdefault
Range of Values:
TRUE
FALSE
If this resource is TRUE, and the button is in a menu, an oval ring is
drawn around the button to show that the button is the default choice of
10/89 Page 5
OblongButton(3W) UNIX System V OblongButton(3W)
one or more buttons.
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
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
Page 6 10/89
OblongButton(3W) UNIX System V OblongButton(3W)
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"
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 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"
OL-POPUP/"string..."
This resource identifies the form that the Label takes. It can have the
value OLSTRING for text, OLIMAGE for an image, or OLPOPUP for text
followed by an ellipsis (such as label... ).
XtNrecomputeSize
Range of Values:
TRUE
FALSE
This resource indicates whether the OblongButton widget should calculate
its size and automatically set the XtNheight and XtNwidth resources. If
set to TRUE, the OblongButton widget will do normal size calculations
that may cause its geometry to change. If set to FALSE, the OblongButton
widget will leave its size alone; this may cause truncation of the
visible image being shown by the OblongButton 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.
10/89 Page 7
OblongButton(3W) UNIX System V OblongButton(3W)
XtNselect
This is the list of callbacks invoked when the widget is selected.
Label Appearance
The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources
interact to produce a truncated, clipped, centered, or left-justified
label as shown in Figure 3.
Figure 3. Label Appearance
When the label is centered or left-justified, the extra space is filled
with the background color of the OblongButton widget, as determined by
the XtNbackground and XtNbackgroundPixmap resources.
When a text label is truncated, the truncation occurs at a character
boundary and a solid 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.
An image label is simply truncated; no triangle is shown.
See also the XtNlabelTile resource for how it affects the appearance of a
label image.
Page 8 10/89