OblongButton(3W)
NAME
OblongButton − oblong button widget and gadget
GADGET CLASS NAME
SYNOPSIS
#include <Xol/OblongButt.h>
#include <Xol/OpenLook.h>
. . .
ANCESTRY
Core-Primitive-Button-OblongButton
DESCRIPTION
The OblongButton is an action widget which the user can "push" by pressing SELECT on it. When the button is "pushed", its border inverts, making it appear as if the button has actually been pressed. It is typically used to initiate one or several application-defined actions.
Components
The OblongButton consists of a label surrounded by a rounded, or oblong, border.
Figure 1 Oblong Buttons
Busy Indication During Callbacks
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.
OblongButtons In Popup Menus
Entering an oblong button while MENU is depressed highlights the button’s interior. 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.
OblongButtons Not In Popup Menus
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, highlights the button’s interior. 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.
OblongButton Gadgets
OblongButton gadgets cannot be parents, that is, they cannot be given as the parent argument 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 ields but, since they are not subclasses of Core, do not have all Core fields. In particular, they do not have a name field or a translation field, so translations cannot be specified or overriden.
Event Handlers cannot be added to gadgets using XtAddEventHandler.
Note: Events that occur outside the border (but within the OblongButton widget) are still in the domain of the button.
Coloration
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. of the OblongButton widget.
Figure 2 OblongButton 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
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 parentheses and displayed/highlighted according to the value returned by OlQueryMnemonicDisplay().
If truncation is necessary, the mnemonic displayed in parentheses is truncated as a unit.
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 XtNacceleratorText 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
Table 1 Oblong Buttons Resource Summary
Name Type Default Access
XtNaccelerator- String NULL SGI
XtNacceleratorText- String Dynamic SGI
XtNancestorSensitive- Boolean TRUE GO
XtNbackground- Pixel XtDefaultBackground SGI
XtNbackgroundPixmap∗ Pixmap (none) SGI
XtNbusy Boolean FALSE SGI
XtNconsumeEvent- XtCallbackList NULL SGI
XtNdefault Boolean FALSE SGI
XtNdepth∗ int (parent’s) GI
XtNdestroyCallback- XtCallbackList NULL SI
XtNfont XFontStruct∗ (OPEN LOOK font) SI
XtNfontColor Pixel XtDefaultForeground SGI
XtNforeground- Pixel XtDefaultForeground SGI
XtNheight- Dimension (calculated) SGI
XtNinputFocusColor- Pixel Red SGI
XtNlabel String (class name) SGI
XtNlabelImage XImage∗ NULL SGI
XtNlabelJustify OlDefine OL_LEFT SGI
XtNlabelTile Boolean FALSE SGI
XtNlabelType OlDefine OL_STRING SGI
XtNmappedWhenManaged∗ Boolean TRUE SGI
XtNmnemonic- unsigned char NULL SGI
XtNrecomputeSize Boolean TRUE SGI
XtNreferenceName- String NULL SGI
XtNreferenceWidget- Widget NULL SGI
XtNscale int 12 GI
XtNselect XtCallbackList NULL SI
XtNsensitive- Boolean TRUE GIO
XtNtraversalOn- Boolean TRUE SGI
XtNuserData- XtPointer NULL SGI
XtNwidth- Dimension (calculated) SGI
XtNx- Position 0 SGI
XtNy- Position 0 SGI
Access: S = XtSetValues G = XtGetValues
I = init time O = other access
∗ not available for OblongButton gadgets
† see resources(3W)
XtNbusy
class:XtCBusy type:Boolean default:FALSEaccess:SGI
Action: controls whether the button is stippled when “busy.”
Values: TRUE – the system will beep if the end user attempts to select the button; the attempt is refused and no callbacks are invoked. FALSE – no stippling
XtNdefault
class:XtCDefault type:Boolean default:FALSEaccess:SGI
Action: indicates whether or not defaultOblongButtonis
Values: TRUE – if the button is in a menu, an oval ring is drawn around the button to show that the button is the default choice of one or more buttons. FALSE – the button is not the default choice.
XtNfont
class:XtCFont type:XFontStruct∗ default:(OPEN LOOK font)access:SI
Action: identifies the font to be used to display the label.
Values: any valid return from XLoadQueryFont()
The default is chosen to match the scale and screen resolution. 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
class:XtCFontColor type:Pixel default:XtDefaultForegroundaccess:SGI
Action: specifies the font color.
Values: any pixel value valid for the current display, or
any name from the rgb.txt file
If not set, the color from the XtNforeground resource, if available, is used for the font.
XtNforeground
class:XtCForeground type:Pixel default:XtDefaultForegroundaccess:SGI
Action: defines the foreground color for the widget.
XtNlabel
class:XtCLabel type:String default:(class name)access:SGI
Action: is a pointer to the text for the Label. This resource is ignored if the XtNlabelType resource has the value OL_IMAGE.
XtNlabelImage
class:XtCLabelImage type:XImage default:NULLaccess:SGI
Action: points to the image for the Label.
This resource is ignored unless the XtNlabelType resource has the value OL_IMAGE. If the image is of type XYBitmap, the image is highlighted when appropriate by reversing the 0 and 1 values of each pixel (that is, by XORing 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
class:XtCLabelJustify type:OlDefine default:OL_LEFTaccess:SGI
Action: dictates whether the label should be left-justified or centered within the widget width.
Values: OL_LEFT, OL_CENTER
XtNlabelTile
class:XtCLabelTile type:Boolean default:FALSEaccess:SGI
Action: partially controls tiling the sub-object’s background.
Values: TRUE, FALSE
This resource augments the XtNlabelImage resource to allow tiling the sub-object’s background. For an image that is smaller than the sub-object’s background, the label area is tiled with the image 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
class:XtCLabelType type:int default:OL_STRINGaccess:SGI
Action: identifies the form that the Label takes.
Values: OL_STRING – for text OL_IMAGE – for an image OL_POPUP – for text followed by an ellipsis, for example label....
XtNrecomputeSize
class:XtCRecomputeSize type:Boolean default:TRUEaccess:SGI
Action: indicates whether the OblongButton widget should calculate its size.HP
Values: TRUE – the OblongButton widget will do normal size calculations that may cause its geometry to change, and automatically set the XtNheight and XtNwidth resources. 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.
XtNscale
class:XtCScale type:Int default:12access:GI
Action: determines size of graphical elements, in points
Values: 0 < XtNscale
This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources. The units of this resource are points (1/72 of an inch), not pixels. Only sizes 10, 12, 14, and 19 are presently supported. If this resource is set to any other value, one of these is substituted instead.
XtNselect
class:XtCCallback type:XtCallbackList default:NULLaccess:SI
Action: 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
Table 2 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.
Version 3.0.1 — Last change: June 92