NAME
Command widget − command button activated by pointer click.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Command.h>
Private Header:<X11/Xaw/CommandP.h>
Class Name:Command
Class Pointer:commandWidgetClass
Instantiation:widget = XtCreateWidget(name, commandWidgetClass, ...)
CLASS HIERARCHY
Core → Simple → Label → Command
DESCRIPTION
The Command widget is an area, often rectangular, that contains a text or pixmap label. This selectable area is sometimes referred to as a "button". When the pointer cursor is on the button, the button border is highlighted to indicate that the button is ready for selection. When pointer button 1 is pressed, the command widget indicates that it has been selected by reversing its foreground and background colors. When the pointer button is released, the Command widget’s notify action is invoked, calling all functions on its callback list.
RESOURCES
When creating a Command widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNbitmap | Pixmap | None | Pixmap to display in place of the label. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNcallback | XtCallbackList | NULL | Callback for button select. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNcornerRound− Percent |
Dimension | 25 | See below. | |||
| XtNcursor | Cursor | None | Pointer cursor. | |||
| XtNdepth | int | Parent’s depth. | (C)Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNencoding | unsigned char | XawTextEncoding8bit | For I18N. | |||
| XtNfont | XFontStruct∗ | XtDefaultFont | Label font. | |||
| XtNforeground | Pixel | XtDefault− Foreground |
Foreground color. | |||
| XtNheight | Dimension | font height + 2 ∗ XtNinternalHeight |
(A) Button height. | |||
| XtNhighlight− Thickness |
Dimension | 2 | (A) Width of border to be highlighted. | |||
| XtNinsensitive− Border |
Pixmap | Gray pixmap. | Border when not sensitive. | |||
| XtNinternal− Height |
Dimension | 2 | Internal border height for highlighting. | |||
| XtNinternalWidth | Dimension | 4 | Internal border width for highlighting. | |||
| XtNjustify | XtJustify | XtJustifyCenter | Type of text alignment. | |||
| XtNlabel | String | Name of widget. | Button label. | |||
| (R5) XtNleftBitmap | Bitmap | None | Pixmap before label. | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget() is automatic. | |||
| XtNresize | Boolean | TRUE | Whether to auto-resize in SetValues. | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed: this is not a settable resource. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNshapeStyle | ShapeStyle | Rectangle | See below. | |||
| XtNtranslations | Translation− Table |
See below. | Event-to-action translations. | |||
| XtNwidth | Dimension | XtNlabel width + 2 ∗ XtNinternalWidth |
(A) Button width. | |||
| XtNx | Position | 0 | x coordinate in pixels. | |||
| XtNy | Position | 0 | y coordinate in pixels. | |||
Note that the Command widget supports two callback lists: XtNdestroyCallback and XtNcallback. The notify action executes the callbacks on the XtNcallback list. The call_data argument is unused.
The new resources (not inherited from superclasses) associated with the Command widget are:
XtNcallback
The callback list executed by the notify action.
XtNhighlightThickness
The thickness of the line drawn by the highlight action.
XtNshapeStyle
Nonrectangular buttons may be created using this resource. Nonrectangular buttons are supported only on a server that supports the Shape Extension. If nonrectangular buttons are specified for a server lacking this extension, the shape is ignored and the widgets will be rectangular. The following shapes are currently supported: XmuShapeRectangle, XmuShapeOval, XmuShapeEllipse, and XmuShapeRoundedRectangle.
XtNcornerRoundPercent
When a ShapeStyle of roundedRectangle is used, this resource controls the radius of the rounded corner. The radius of the rounded corners is specified as a percentage of the length of the shortest side of the widget.
TRANSLATIONS AND ACTIONS
The following are the default translation bindings that are used by the Command widget: <EnterWindow>: highlight() <LeaveWindow>: reset() <Btn1Down>: set() <Btn1Up>: notify() unset() With these bindings, the user can cancel the action before releasing the button by moving the pointer out of the Command widget.
The Command widget supports the following actions:
•Switching the button between the foreground and background colors with set and unset.
•Processing application callbacks with notify.
•Switching the internal border between highlighted and unhighlighted states with highlight and unhighlight.
The full list of actions supported by Command is as follows:
highlight()Displays the internal highlight border in the color (XtNforeground or XtNbackground) that contrasts with the interior color of the Command widget. The conditions WhenUnset and Always are understood by this action procedure. If no argument is passed, WhenUnset is assumed.
unhighlight()
Displays the internal highlight border in the color (XtNforeground or XtNbackground) that matches the interior color of the Command widget.
set()Enters the set state, in which notify is possible and displays the interior of the button, including the highlight border, in the foreground color. The label is displayed in the background color.
unset()Cancels the set state and displays the interior of the button, including the highlight border, in the background color. The label is displayed in the foreground color.
reset()Cancels any set or highlight and displays the interior of the button in the background color, with the label displayed in the foreground color.
notify()Executes the callback list specified by XtNcallback, if executed in the set state. The value of the call_data argument is undefined.
SEE ALSO
Box, Label, MenuButton.