# Command Widget

    Application header file	<X11/Xaw/Command.h>

    Class header file	<X11/Xaw/CommandP.h>

    Class	commandWidgetClass

    Class Name	Command

    Superclass	Label

The Command widget is an area, often rectangular, that contains text or a graphical image. Command widgets are often referred to as push buttons. When the pointer is over a Command widget, the widget becomes highlighted by drawing a rectangle around its perimeter. This highlighting indicates that the widget is ready for selection. When mouse button 1 is pressed, the Command widget indicates that it has been selected by reversing its foreground and background colors. When the mouse button is released, the Command widget's `notify` action is invoked, calling all functions on its callback list. If the pointer is moved off of the widget before the pointer button is released, the widget reverts to its normal foreground and background colors, and releasing the pointer button has no effect. This behavior allows the user to cancel an action.

## Resources

When creating a Command widget instance, the following resources are retrieved from the argument list or from the resource database:

Name | Class | Type | Notes | Default Value
accelerators | Accelerators | AcceleratorTable |  | NULL
ancestorSensitive | AncestorSensitive | Boolean | D | True
background | Background | Pixel |  | XtDefaultBackground
backgroundPixmap | Pixmap | Pixmap |  | XtUnspecifiedPixmap
bitmap | Bitmap | Pixmap |  | None
borderColor | BorderColor | Pixel |  | XtDefaultForeground
borderPixmap | Pixmap | Pixmap |  | XtUnspecifiedPixmap
borderWidth | BorderWidth | Dimension |  | 1
callback | Callback | XtCallbackList |  | NULL
colormap | Colormap | Colormap |  | Parent's Colormap
cornerRoundPercent | CornerRoundPercent | Dimension |  | 25
cursor | Cursor | Cursor |  | None
cursorName | Cursor | String |  | NULL
depth | Depth | int | C | Parent's Depth
destroyCallback | Callback | XtCallbackList |  | NULL
encoding | Encoding | UnsignedChar |  | XawTextEncoding8bit
font | Font | XFontStruct |  | XtDefaultFont
foreground | Foreground | Pixel |  | XtDefaultForeground
height | Height | Dimension | A | graphic height + 2 * `internalHeight`
highlightThickness | Thickness | Dimension | A | 2 (0 if Shaped)
insensitiveBorder | Insensitive | Pixmap |  | GreyPixmap
internalHeight | Height | Dimension |  | 2
internalWidth | Width | Dimension |  | 4
international | International | Boolean | C | False
justify | Justify | Justify |  | XtJustifyCenter (center)
label | Label | String |  | name of widget
leftBitmap | LeftBitmap | Bitmap |  | None
mappedWhenManaged | MappedWhenManaged | Boolean |  | True
pointerColor | Foreground | Pixel |  | XtDefaultForeground
pointerColorBackground | Background | Pixel |  | XtDefaultBackground
resize | Resize | Boolean |  | True
screen | Screen | Screen | R | Parent's Screen
sensitive | Sensitive | Boolean |  | True
shapeStyle | ShapeStyle | ShapeStyle |  | Rectangle
translations | Translations | TranslationTable |  | See below
width | Width | Dimension | A | graphic width + 2 * `internalWidth`
x | Position | Position |  | 0
y | Position | Position |  | 0
_

## Command Actions

The Command widget supports the following actions:

- Switching the button's interior between the foreground and background colors with `set`, `unset`, and `reset`.

- Processing application callbacks with `notify`

- Switching the internal border between highlighted and unhighlighted states with `highlight` and `unhighlight`

The following are the default translation bindings used by the Command widget:

    	<EnterWindow>:	highlight( )
    	<LeaveWindow>:	reset( )
    	<Btn1Down>:	set( )
    	<Btn1Up>:	notify( ) unset( )

The full list of actions supported by Command is:

`highlight`(`condition`)

- Displays the internal highlight border in the color (`foreground` or `background` ) 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 (`foreground` or `background` ) that matches the interior color of the Command widget.

`set`( )

- Enters the `set` state, in which `notify` is possible. This action causes the button to display its interior in the `foreground` color. The label or bitmap is displayed in the `background` color.

`unset`( )

- Cancels the set state and displays the interior of the button in the `background` color. The label or bitmap 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 or bitmap displayed in the `foreground` color.

`notify`( )

- When the button is in the `set` state this action calls all functions in the callback list named by the `callback` resource. The value of the call_data argument passed to these functions is undefined.

A very common alternative to registering callbacks is to augment a Command's translations with an action performing the desired function. This often takes the form of:

    *Myapp*save.translations: #augment <Btn1Down>,<Btn1Up>: Save()

When a bitmap of depth greater that one (1) is specified the set(), unset(), and reset() actions have no effect, since there are no foreground and background colors used in a multi-plane pixmap.