diff options
Diffstat (limited to 'libXaw/specs/Command.xml')
| -rw-r--r-- | libXaw/specs/Command.xml | 525 |
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 <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> |