aboutsummaryrefslogtreecommitdiff
path: root/libXaw/specs/Command.xml
diff options
context:
space:
mode:
Diffstat (limited to 'libXaw/specs/Command.xml')
-rw-r--r--libXaw/specs/Command.xml525
1 files changed, 525 insertions, 0 deletions
diff --git a/libXaw/specs/Command.xml b/libXaw/specs/Command.xml
new file mode 100644
index 000000000..92d1b7253
--- /dev/null
+++ b/libXaw/specs/Command.xml
@@ -0,0 +1,525 @@
+<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 &lt;X11/Xaw/Command.h&gt;
+<!-- .IN "Command.h" "" -->
+Class header file &lt;X11/Xaw/CommandP.h&gt;
+<!-- .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 -->
+ &lt;EnterWindow&gt;: highlight(\|)
+ &lt;LeaveWindow&gt;: reset(\|)
+ &lt;Btn1Down&gt;: set(\|)
+ &lt;Btn1Up&gt;: 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 &lt;Btn1Down&gt;,&lt;Btn1Up&gt;: 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>