526 lines
13 KiB
XML
526 lines
13 KiB
XML
<sect1 id="Command_Widget">
|
|
<title>Command Widget</title>
|
|
<!-- .XS -->
|
|
<!-- Command Widget -->
|
|
<!-- .XE -->
|
|
<!-- .IN "Command widget" "" "@DEF@" -->
|
|
<literallayout class="monospaced">
|
|
<!-- .TA 2.0i -->
|
|
<!-- .ta 2.0i -->
|
|
<!-- .sp -->
|
|
Application header file <X11/Xaw/Command.h>
|
|
<!-- .IN "Command.h" "" -->
|
|
Class header file <X11/Xaw/CommandP.h>
|
|
<!-- .IN "CommandP.h" "" -->
|
|
Class commandWidgetClass
|
|
<!-- .IN "commandWidgetClass" "" -->
|
|
Class Name Command
|
|
<!-- .IN "Command widget" "class name" -->
|
|
Superclass Label
|
|
<!-- .sp -->
|
|
</literallayout>
|
|
<para>
|
|
<!-- .LP -->
|
|
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 <function>notify</function>
|
|
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.
|
|
</para>
|
|
<sect2 id="Resources">
|
|
<title>Resources</title>
|
|
<para>
|
|
<!-- .LP -->
|
|
When creating a Command widget instance, the following resources are
|
|
retrieved from the argument list or from the resource database:
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .IN "Command widget" "resources" -->
|
|
<informaltable>
|
|
<tgroup cols='5' align='center'>
|
|
<colspec colname='c1'/>
|
|
<colspec colname='c2'/>
|
|
<colspec colname='c3'/>
|
|
<colspec colname='c4'/>
|
|
<colspec colname='c5'/>
|
|
<thead>
|
|
<row>
|
|
<entry>Name</entry>
|
|
<entry>Class</entry>
|
|
<entry>Type</entry>
|
|
<entry>Notes</entry>
|
|
<entry>Default Value</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>accelerators</entry>
|
|
<entry>Accelerators</entry>
|
|
<entry>AcceleratorTable</entry>
|
|
<entry></entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ancestorSensitive</entry>
|
|
<entry>AncestorSensitive</entry>
|
|
<entry>Boolean</entry>
|
|
<entry>D</entry>
|
|
<entry>True</entry>
|
|
</row>
|
|
<row>
|
|
<entry>background</entry>
|
|
<entry>Background</entry>
|
|
<entry>Pixel</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultBackground</entry>
|
|
</row>
|
|
<row>
|
|
<entry>backgroundPixmap</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry></entry>
|
|
<entry>XtUnspecifiedPixmap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>bitmap</entry>
|
|
<entry>Bitmap</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry></entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>borderColor</entry>
|
|
<entry>BorderColor</entry>
|
|
<entry>Pixel</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultForeground</entry>
|
|
</row>
|
|
<row>
|
|
<entry>borderPixmap</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry></entry>
|
|
<entry>XtUnspecifiedPixmap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>borderWidth</entry>
|
|
<entry>BorderWidth</entry>
|
|
<entry>Dimension</entry>
|
|
<entry></entry>
|
|
<entry>1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>callback</entry>
|
|
<entry>Callback</entry>
|
|
<entry>XtCallbackList</entry>
|
|
<entry></entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>colormap</entry>
|
|
<entry>Colormap</entry>
|
|
<entry>Colormap</entry>
|
|
<entry></entry>
|
|
<entry>Parent's Colormap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>cornerRoundPercent</entry>
|
|
<entry>CornerRoundPercent</entry>
|
|
<entry>Dimension</entry>
|
|
<entry></entry>
|
|
<entry>25</entry>
|
|
</row>
|
|
<row>
|
|
<entry>cursor</entry>
|
|
<entry>Cursor</entry>
|
|
<entry>Cursor</entry>
|
|
<entry></entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>cursorName</entry>
|
|
<entry>Cursor</entry>
|
|
<entry>String</entry>
|
|
<entry></entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>depth</entry>
|
|
<entry>Depth</entry>
|
|
<entry>int</entry>
|
|
<entry>C</entry>
|
|
<entry>Parent's Depth</entry>
|
|
</row>
|
|
<row>
|
|
<entry>destroyCallback</entry>
|
|
<entry>Callback</entry>
|
|
<entry>XtCallbackList</entry>
|
|
<entry></entry>
|
|
<entry>NULL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>encoding</entry>
|
|
<entry>Encoding</entry>
|
|
<entry>UnsignedChar</entry>
|
|
<entry></entry>
|
|
<entry>XawTextEncoding8bit</entry>
|
|
</row>
|
|
<row>
|
|
<entry>font</entry>
|
|
<entry>Font</entry>
|
|
<entry>XFontStruct</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultFont</entry>
|
|
</row>
|
|
<row>
|
|
<entry>foreground</entry>
|
|
<entry>Foreground</entry>
|
|
<entry>Pixel</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultForeground</entry>
|
|
</row>
|
|
<row>
|
|
<entry>height</entry>
|
|
<entry>Height</entry>
|
|
<entry>Dimension</entry>
|
|
<entry>A</entry>
|
|
<entry>graphic height + 2 * <function>internalHeight</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>highlightThickness</entry>
|
|
<entry>Thickness</entry>
|
|
<entry>Dimension</entry>
|
|
<entry>A</entry>
|
|
<entry>2 (0 if Shaped)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>insensitiveBorder</entry>
|
|
<entry>Insensitive</entry>
|
|
<entry>Pixmap</entry>
|
|
<entry></entry>
|
|
<entry>GreyPixmap</entry>
|
|
</row>
|
|
<row>
|
|
<entry>internalHeight</entry>
|
|
<entry>Height</entry>
|
|
<entry>Dimension</entry>
|
|
<entry></entry>
|
|
<entry>2</entry>
|
|
</row>
|
|
<row>
|
|
<entry>internalWidth</entry>
|
|
<entry>Width</entry>
|
|
<entry>Dimension</entry>
|
|
<entry></entry>
|
|
<entry>4</entry>
|
|
</row>
|
|
<row>
|
|
<entry>international</entry>
|
|
<entry>International</entry>
|
|
<entry>Boolean</entry>
|
|
<entry>C</entry>
|
|
<entry>False</entry>
|
|
</row>
|
|
<row>
|
|
<entry>justify</entry>
|
|
<entry>Justify</entry>
|
|
<entry>Justify</entry>
|
|
<entry></entry>
|
|
<entry>XtJustifyCenter (center)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>label</entry>
|
|
<entry>Label</entry>
|
|
<entry>String</entry>
|
|
<entry></entry>
|
|
<entry>name of widget</entry>
|
|
</row>
|
|
<row>
|
|
<entry>leftBitmap</entry>
|
|
<entry>LeftBitmap</entry>
|
|
<entry>Bitmap</entry>
|
|
<entry></entry>
|
|
<entry>None</entry>
|
|
</row>
|
|
<row>
|
|
<entry>mappedWhenManaged</entry>
|
|
<entry>MappedWhenManaged</entry>
|
|
<entry>Boolean</entry>
|
|
<entry></entry>
|
|
<entry>True</entry>
|
|
</row>
|
|
<row>
|
|
<entry>pointerColor</entry>
|
|
<entry>Foreground</entry>
|
|
<entry>Pixel</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultForeground</entry>
|
|
</row>
|
|
<row>
|
|
<entry>pointerColorBackground</entry>
|
|
<entry>Background</entry>
|
|
<entry>Pixel</entry>
|
|
<entry></entry>
|
|
<entry>XtDefaultBackground</entry>
|
|
</row>
|
|
<row>
|
|
<entry>resize</entry>
|
|
<entry>Resize</entry>
|
|
<entry>Boolean</entry>
|
|
<entry></entry>
|
|
<entry>True</entry>
|
|
</row>
|
|
<row>
|
|
<entry>screen</entry>
|
|
<entry>Screen</entry>
|
|
<entry>Screen</entry>
|
|
<entry>R</entry>
|
|
<entry>Parent's Screen</entry>
|
|
</row>
|
|
<row>
|
|
<entry>sensitive</entry>
|
|
<entry>Sensitive</entry>
|
|
<entry>Boolean</entry>
|
|
<entry></entry>
|
|
<entry>True</entry>
|
|
</row>
|
|
<row>
|
|
<entry>shapeStyle</entry>
|
|
<entry>ShapeStyle</entry>
|
|
<entry>ShapeStyle</entry>
|
|
<entry></entry>
|
|
<entry>Rectangle</entry>
|
|
</row>
|
|
<row>
|
|
<entry>translations</entry>
|
|
<entry>Translations</entry>
|
|
<entry>TranslationTable</entry>
|
|
<entry></entry>
|
|
<entry>See below</entry>
|
|
</row>
|
|
<row>
|
|
<entry>width</entry>
|
|
<entry>Width</entry>
|
|
<entry>Dimension</entry>
|
|
<entry>A</entry>
|
|
<entry>graphic width + 2 * <function>internalWidth</function></entry>
|
|
</row>
|
|
<row>
|
|
<entry>x</entry>
|
|
<entry>Position</entry>
|
|
<entry>Position</entry>
|
|
<entry></entry>
|
|
<entry>0</entry>
|
|
</row>
|
|
<row>
|
|
<entry>y</entry>
|
|
<entry>Position</entry>
|
|
<entry>Position</entry>
|
|
<entry></entry>
|
|
<entry>0</entry>
|
|
</row>
|
|
<row>
|
|
<entry>_</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
\" Resource Descriptions
|
|
<!-- .Ac -->
|
|
<!-- .As -->
|
|
<!-- .Bg -->
|
|
<!-- .Gp -->
|
|
<!-- .Bm -->
|
|
<!-- .Bc -->
|
|
<!-- .Bp -->
|
|
<!-- .Bw -->
|
|
<!-- .Cb Bold -->
|
|
<!-- .Cm -->
|
|
<!-- .Cr Bold -->
|
|
<!-- .Cu -->
|
|
<!-- .Cn -->
|
|
<!-- .Dp -->
|
|
<!-- .Dc -->
|
|
<!-- .Le -->
|
|
<!-- .Lf -->
|
|
<!-- .Ls -->
|
|
<!-- .Lg -->
|
|
<!-- .Hw -->
|
|
<!-- .Ht Bold -->
|
|
<!-- .Ib -->
|
|
<!-- .Ih -->
|
|
<!-- .In -->
|
|
<!-- .Ju -->
|
|
<!-- .La -->
|
|
<!-- .Ll -->
|
|
<!-- .Mm -->
|
|
<!-- .Pf -->
|
|
<!-- .Pb -->
|
|
<!-- .Re -->
|
|
<!-- .Sc -->
|
|
<!-- .Se -->
|
|
<!-- .Ss Bold -->
|
|
<!-- .Tr -->
|
|
<!-- .Xy -->
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="Command_Actions">
|
|
<title>Command Actions</title>
|
|
<!-- .IN "Command widget" "actions" -->
|
|
<para>
|
|
<!-- .LP -->
|
|
The Command widget supports the following actions:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Switching the button's interior between the foreground and background
|
|
colors with <function>set</function>, <function>unset</function>, and <function>reset</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Processing application callbacks with <function>notify</function>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Switching the internal border between highlighted
|
|
and unhighlighted states with <function>highlight</function> and <function>unhighlight</function>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .IN "Command widget" "translation bindings" -->
|
|
The following are the default translation bindings used by the
|
|
Command widget:
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<literallayout class="monospaced">
|
|
<!-- .TA .5i 2.25i -->
|
|
<!-- .ta .5i 2.25i -->
|
|
<EnterWindow>: highlight(\|)
|
|
<LeaveWindow>: reset(\|)
|
|
<Btn1Down>: set(\|)
|
|
<Btn1Up>: notify(\|) unset(\|)
|
|
</literallayout>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
The full list of actions supported by Command is:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<function>highlight</function>(<function>condition</function>)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Displays the internal highlight border in the color (<function>foreground</function>
|
|
or <function>background</function> ) that contrasts with the interior color of the
|
|
Command widget. The conditions <function>WhenUnset</function> and <function>Always</function> are
|
|
understood by this action procedure. If no argument is passed,
|
|
<function>WhenUnset</function> is assumed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<function>unhighlight</function>(\|)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Displays the internal highlight border in the color (<function>foreground</function>
|
|
or <function>background</function> ) that matches the interior color of the
|
|
Command widget.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<function>set</function>(\|)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enters the <function>set</function> state, in which <function>notify</function> is possible. This
|
|
action causes the button to display its interior in the
|
|
<function>foreground</function> color. The label or bitmap is displayed in the
|
|
<function>background</function> color.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<function>unset</function>(\|)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Cancels the <emphasis remap='I'>set</emphasis> state and displays the interior of the button in the
|
|
<function>background</function> color. The label or bitmap is displayed in the
|
|
<function>foreground</function> color.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<function>reset</function>(\|)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Cancels any <emphasis remap='I'>set</emphasis> or <emphasis remap='I'>highlight</emphasis> and displays the interior of the
|
|
button in the <function>background</function> color, with the label or bitmap displayed
|
|
in the <function>foreground</function> color.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<function>notify</function>(\|)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
When the button is in the <function>set</function> state this action calls all functions in
|
|
the callback list named by the <function>callback</function> resource. The value of
|
|
the <emphasis remap='I'>call_data</emphasis> argument passed to these functions is undefined.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
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:
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<literallayout class="monospaced">
|
|
<!-- .TA .5i 2.25i -->
|
|
<!-- .ta .5i 2.25i -->
|
|
*Myapp*save.translations: #augment <Btn1Down>,<Btn1Up>: Save()
|
|
</literallayout>
|
|
</para>
|
|
<para>
|
|
<!-- .LP -->
|
|
<!-- .NT -->
|
|
When a bitmap of depth greater that one (1) is specified the
|
|
<emphasis remap='I'>set</emphasis>(), <emphasis remap='I'>unset</emphasis>(), and <emphasis remap='I'>reset</emphasis>() actions have no effect,
|
|
since there are no foreground and background colors used in a
|
|
multi-plane pixmap.
|
|
<!-- .NE -->
|
|
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|