diff options
| author | marha <marha@users.sourceforge.net> | 2011-03-25 15:37:13 +0000 |
|---|---|---|
| committer | marha <marha@users.sourceforge.net> | 2011-03-25 15:37:13 +0000 |
| commit | 41a502478a2972358dec934d82ee401c61a5cd36 (patch) | |
| tree | 3fda8100e6da9b4a2863789e393016a750502067 /libXaw/specs | |
| parent | 81aeaf653a832c4054d9a40b1cc796911521a739 (diff) | |
| parent | 272e57235cd60a2e65ac8258d96a02eb3939b687 (diff) | |
| download | vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.gz vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.tar.bz2 vcxsrv-41a502478a2972358dec934d82ee401c61a5cd36.zip | |
svn merge ^/branches/released .
Diffstat (limited to 'libXaw/specs')
47 files changed, 22011 insertions, 0 deletions
diff --git a/libXaw/specs/AsciiSink.xml b/libXaw/specs/AsciiSink.xml new file mode 100644 index 000000000..06bc87dc4 --- /dev/null +++ b/libXaw/specs/AsciiSink.xml @@ -0,0 +1,141 @@ +<sect1 id="Ascii_Sink_Object_and_Multi_Sink_Object"> +<title>Ascii Sink Object and Multi Sink Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- AsciiSink Object --> +<!-- .XE --> +<!-- .IN "AsciiSink object" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/AsciiSink.h> +<!-- .IN "AsciiSink.h" "" --> +Class Header file <X11/Xaw/AsciiSinkP.h> +<!-- .IN "AsciiSinkP.h" "" --> +Class asciiSinkObjectClass +<!-- .IN "asciiSinkObjectClass" "" --> +Class Name AsciiSink +<!-- .IN "AsciiSink object" "class name" --> +Superclass TextSink +</literallayout> +</para> +<para> +<!-- .LP --> +The AsciiSink or MultiSink object is used by a text widget to render the text. +Depending on its <function>international</function> resource, a +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSink differences noted only as they occur. +The AsciiSink +will display all printing characters in an 8 bit font, along with handling Tab +and Carriage Return. The name has been left as ``AsciiSink'' for compatibility. +\fIThe MultiSink will display all printing characters in a font set, along with +handling Tab and Carriage +Return.\fP The source object also reports the text window metrics to the +text widgets. +</para> +<sect2 id="asciisink_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating an AsciiSink object instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "AsciiSink object" "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>background</entry> + <entry>Background</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultBackground</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>displayNonprinting</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>echo</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>font</entry> + <entry>Font</entry> + <entry>XFontStruct*</entry> + <entry></entry> + <entry>XtDefaultFont</entry> + </row> + <row> + <entry>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</entry> + </row> + <row> + <entry>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Bg Bold --> +This resource is retrieved by the AsciiSink instead of being copied +from the Text widget. +<!-- .Dc --> +<!-- .Sd Bold --> +<!-- .Sh Bold --> +</para> +<para> +<!-- .IP <function>font</function> 1.5i --> +The text font to use when displaying the <function>string</function>. +(This resource is present in the AsciiSink, but not the MultiSink.) +<!-- .IP <function>fontSet</function> 1.5i --> +</para> +<para> +The text font set to use when displaying the <function>string</function>. +(This resource is present in the MultiSink, but not the AsciiSink.) +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/AsciiSource.xml b/libXaw/specs/AsciiSource.xml new file mode 100644 index 000000000..bd51f990a --- /dev/null +++ b/libXaw/specs/AsciiSource.xml @@ -0,0 +1,368 @@ +<sect1 id="Ascii_Source_Object_and_Multi_Source_Object"> +<title>Ascii Source Object and Multi Source Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- AsciiSrc Object --> +<!-- .XE --> +<!-- .IN "AsciiSrc object" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/AsciiSrc.h> or <X11/Xaw/MultiSrc.h> +<!-- .IN "AsciiSrc.h" "" --> +Class Header file <X11/Xaw/AsciiSrcP.h> or <X11/Xaw/MultiSrcP.h> +<!-- .IN "AsciiSrcP.h" "" --> +Class asciiSrcObjectClass or multiSrcObjectClass +<!-- .IN "asciiSrcObjectClass" "" --> +Class Name AsciiSrc or MultiSrc +<!-- .IN "AsciiSrc object" "class name" --> +Superclass TextSource +</literallayout> +</para> +<para> +<!-- .LP --> +The AsciiSrc or MultiSrc object is used by a text widget to read the text from a +file or string in memory. Depending on its <function>international</function> resource, an +AsciiText widget will create one or the other of these when the AsciiText +itself is created. Both types are nearly identical; the following discussion +applies to both, with MultiSrc differences noted only as they occur. +</para> +<para> +<!-- .LP --> +The AsciiSrc understands all Latin1 characters plus Tab +and Carriage Return. \fIThe MultiSrc understands any set of character sets that +the underlying X implementation's internationalization handles.\fP +</para> +<para> +<!-- .LP --> +The AsciiSrc can be either of two types: <function>XawAsciiFile</function> +or <function>XawAsciiString</function>. +</para> +<para> +<!-- .LP --> +AsciiSrc objects of type <function>XawAsciiFile</function> read the text from a file and +store it +into an internal buffer. This buffer may then be modified, provided the +text widget is in the correct edit mode, just as if it were a source of +type <function>XawAsciiString</function>. Unlike R3 and earlier versions of the AsciiSrc, +it is now possible to specify an editable disk source. The file is not +updated, however, until a call to <function>XawAsciiSave</function> is made. When the +source is in this mode the <function>useStringInPlace</function> resource is ignored. +</para> +<para> +<!-- .LP --> +AsciiSrc objects of type <function>XawAsciiString</function> have the text buffer +implemented as a string. +\fIMultiSrc objects of type <function>XawAsciiString</function> have the text buffer +implemented as a wide character string.\fP +The string owner is responsible for allocating and managing storage for the +string. +</para> +<para> +<!-- .LP --> +In the default case for AsciiSrc objects of type <function>XawAsciiString</function>, +the resource <function>useStringInPlace</function> is false, +and the widget owns the string. The initial value of the +string resource, and any update made by the application +programmer to the string resource with <function>XtSetValues</function>, is copied +into memory private to the widget, and managed internally by the widget. +The application writer +does not need to worry about running out of buffer space +(subject to the total memory available to the application). +The performance does not decay linearly as the buffer grows +large, as is necessarily the case when the text buffer is used +in place. The application writer must use <function>XtGetValues</function> to +determine the contents of the text buffer, which will return +a copy of the widget's text buffer as +it existed at the time of the <function>XtGetValues</function> call. This copy +is not affected by subsequent updates to the text buffer, i.e., +it is not updated as the user types input into the text buffer. +This copy is freed upon the next call to XtGetValues to +retrieve the string resource; however, to conserve memory, +there is a convenience routine, <function>XawAsciiSourceFreeString</function>, allowing the +application programmer to direct the widget to free the copy. +</para> +<para> +<!-- .LP --> +When the resource <function>useStringInPlace</function> is true and the AsciiSrc object +is of type <function>XawAsciiString</function>, the application +is the string owner. The widget will take the value +of the string resource as its own text buffer, and the <function>length</function> +resource indicates the buffer size. In this case +the buffer contents change as the user types at the widget; +it is not necessary to call <function>XtGetValues</function> on the string +resource to determine the contents of the buffer-it will +simply return the address of the application's implementation +of the text buffer. +</para> +<sect2 id="asciisource_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating an AsciiSrc object instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "AsciiSrc object" "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>callback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>dataCompression</entry> + <entry>DataCompression</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>editType</entry> + <entry>EditType</entry> + <entry>EditMode</entry> + <entry></entry> + <entry>XawtextRead</entry> + </row> + <row> + <entry>length</entry> + <entry>Length</entry> + <entry>Int</entry> + <entry>A</entry> + <entry>length of <function>string</function></entry> + </row> + <row> + <entry>pieceSize</entry> + <entry>PieceSize</entry> + <entry>Int</entry> + <entry></entry> + <entry>BUFSIZ</entry> + </row> + <row> + <entry>string</entry> + <entry>String</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>type</entry> + <entry>Type</entry> + <entry>AsciiType</entry> + <entry></entry> + <entry>XawAsciiString</entry> + </row> + <row> + <entry>useStringInPlace</entry> + <entry>UseStringInPlace</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Oc Bold --> +<!-- .Dc --> +<!-- .Od Bold --> +<!-- .Oe --> +<!-- .Ol Bold --> +<!-- .Op Bold --> +<!-- .Os Bold --> +<!-- .Ot Bold --> +<!-- .Ou Bold --> +</para> +</sect2> +<sect2 id="asciisource_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .LP --> +The AsciiSrc has a few convenience routines that allow the +application programmer quicker or easier access to some of the +commonly used functionality of the AsciiSrc. +</para> +<sect3 id="Conserving_Memory"> +<title>Conserving Memory</title> +<para> +<!-- .LP --> +When the AsciiSrc widget is not in <function>useStringInPlace</function> mode +space must be allocated whenever the file is saved, or the string is +requested with a call to <function>XtGetValues</function>. This memory is allocated on the +fly, and remains valid until the next time a string needs to be allocated. +You may save memory by freeing this string as soon as you are done +with it by calling <function>XawAsciiSourceFreeString</function>. +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawAsciiSourceFreeString</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will free the memory that contains the string pointer returned +by <function>XtGetValues</function>. This will normally happen automatically when +the next call to <function>XtGetValues</function> occurs, or when the widget is destroyed. +</para> +</sect3> +<sect3 id="Saving_Files"> +<title>Saving Files</title> +<para> +<!-- .LP --> +To save the changes made in the current text source into a file use +<function>XawAsciiSave</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSave</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XawAsciiSave</function> returns <function>True</function> if the save was successful. +It will update the file named in the <function>string</function> resource. +If the buffer has not been changed, no action will be taken. This function +only works on an AsciiSrc of type <function>XawAsciiFile</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To save the contents of the current text buffer into a named file use +<function>XawAsciiSaveAsFile</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSaveAsFile</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String<parameter> name</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +The name of the file to save the current buffer into. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns <function>True</function> if the save was successful. +<function>XawAsciiSaveAsFile</function> will work with a buffer of either type +<function>XawAsciiString</function> or type <function>XawAsciiFile</function>. +</para> +</sect3> +<sect3 id="Seeing_if_the_Source_has_Changed"> +<title>Seeing if the Source has Changed</title> +<para> +<!-- .LP --> +To find out if the text buffer in an AsciiSrc object has changed +since the last time it was saved with <function>XawAsciiSave</function> or queried +<!-- .IN "XawAsciiSave" "" --> +use <function>XawAsciiSourceChanged</function>. +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> XawAsciiSourceChanged</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the AsciiSrc object. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will return <function>True</function> if the source has changed since +the last time it was saved or queried. The internal change flag is +reset whenever the string is queried via <function>XtGetValues</function> or the +buffer is saved via <function>XawAsciiSave</function>. + +</para> +</sect3> +</sect2> +</sect1> diff --git a/libXaw/specs/AsciiText.xml b/libXaw/specs/AsciiText.xml new file mode 100644 index 000000000..1a336d6c8 --- /dev/null +++ b/libXaw/specs/AsciiText.xml @@ -0,0 +1,450 @@ +<sect1 id="Ascii_Text_Widget"> +<title>Ascii Text Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- AsciiText Widget --> +<!-- .XE --> +<!-- .IN "AsciiText widget" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/AsciiText.h> +<!-- .IN "AsciiText.h" "" --> +ClassHeader file <X11/Xaw/AsciiTextP.h> +<!-- .IN "AsciiTextP.h" "" --> +Class asciiTextWidgetClass +<!-- .IN "asciiTextWidgetClass" "" --> +Class Name Text +<!-- .IN "AsciiText widget" "class name" --> +Superclass Text +Sink Name textSink +Source Name textSource +</literallayout> +<!-- .sp 1 --> +</para> +<para> +<!-- .LP --> +For the ease of internationalization, the AsciiText widget class name has not +been changed, although it is actually able to support non-ASCII locales. +The AsciiText widget is really a collection of smaller parts. It +includes the Text widget itself, a ``Source'' (which supports memory management), +and a ``Sink'' (which handles the display). There are currently two supported +sources, the AsciiSrc and MultiSrc, and two supported sinks, the AsciiSink and +<!-- .IN "AsciiSrc object" "" --> +<!-- .IN "AsciiSink object" "" --> +<!-- .IN "MultiSrc object" "" --> +<!-- .IN "MultiSink object" "" --> +MultiSink. Some of +the resources listed below are not actually resources of the +AsciiText, but belong to the associated source or sink. This is +is noted in the explanation of each resource where it applies. When +specifying these resources in a resource file it is necessary to use +<emphasis remap='I'>*AsciiText*resource_name</emphasis> instead of +<emphasis remap='I'>*AsciiText.resource_name</emphasis>, since they actually belong to the +children of the AsciiText widget, and not the AsciiText widget itself. +However, these resources may be set directly on the AsciiText widget at +widget creation time, or via <function>XtSetValues</function>. +</para> +<sect2 id="asciitext_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating an AsciiText widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "AsciiText 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>autoFill</entry> + <entry>AutoFill</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>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>bottomMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</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>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_xterm</entry> + </row> + <row> + <entry>cursorName</entry> + <entry>Cursor</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>dataCompression</entry> + <entry>DataCompression</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</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>displayCaret</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>displayNonprinting</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>displayPosition</entry> + <entry>TextPosition</entry> + <entry>XawTextPosition</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>echo</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>editType</entry> + <entry>EditType</entry> + <entry>XawTextEditType</entry> + <entry></entry> + <entry>XawtextRead</entry> + </row> + <row> + <entry>font</entry> + <entry>Font</entry> + <entry>XFontStruct*</entry> + <entry></entry> + <entry>XtDefaultFont</entry> + </row> + <row> + <entry>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>Font height + margins</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>insertPosition</entry> + <entry>TextPosition</entry> + <entry>int</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</entry> + </row> + <row> + <entry>leftMargin</entry> + <entry>Margin</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>length</entry> + <entry>Length</entry> + <entry>int</entry> + <entry>A</entry> + <entry>length of <function>string</function></entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>pieceSize</entry> + <entry>PieceSize</entry> + <entry>XawTextPosition</entry> + <entry></entry> + <entry>BUFSIZ</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>XawTextResizeMode</entry> + <entry></entry> + <entry>XawtextResizeNever</entry> + </row> + <row> + <entry>rightMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>screen</entry> + <entry>Screen</entry> + <entry>Screen</entry> + <entry>R</entry> + <entry>Parent's Screen</entry> + </row> + <row> + <entry>scrollHorizontal</entry> + <entry>Scroll</entry> + <entry>XawTextScrollMode</entry> + <entry></entry> + <entry>XawtextScrollNever</entry> + </row> + <row> + <entry>scrollVertical</entry> + <entry>Scroll</entry> + <entry>XawTextScrollMode</entry> + <entry></entry> + <entry>XawtextScrollNever</entry> + </row> + <row> + <entry>selectTypes</entry> + <entry>SelectTypes</entry> + <entry>XawTextSelectType*</entry> + <entry></entry> + <entry>See above</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>string</entry> + <entry>String</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>textSink</entry> + <entry>TextSink</entry> + <entry>Widget</entry> + <entry></entry> + <entry>An AsciiSink</entry> + </row> + <row> + <entry>textSource</entry> + <entry>TextSource</entry> + <entry>Widget</entry> + <entry></entry> + <entry>An AsciiSrc</entry> + </row> + <row> + <entry>topMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>See above</entry> + </row> + <row> + <entry>type</entry> + <entry>Type</entry> + <entry>XawAsciiType</entry> + <entry></entry> + <entry>XawAsciiString</entry> + </row> + <row> + <entry>useStringInPlace</entry> + <entry>UseStringInPlace</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>100</entry> + </row> + <row> + <entry>wrap</entry> + <entry>Wrap</entry> + <entry>WrapMode</entry> + <entry></entry> + <entry>XawtextWrapNever</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> + </tbody> + </tgroup> +</informaltable> + + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Box.xml b/libXaw/specs/Box.xml new file mode 100644 index 000000000..fe93b42d3 --- /dev/null +++ b/libXaw/specs/Box.xml @@ -0,0 +1,346 @@ +<sect1 id="Box_Widget"> +<title>Box Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Box Widget --> +<!-- .XE --> +<!-- .IN "Box widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Box.h> +<!-- .IN "Box.h" "" --> +Class Header file <X11/Xaw/BoxP.h> +<!-- .IN "BoxP.h" "" --> +Class boxWidgetClass +<!-- .IN "boxWidgetClass" "" --> +Class Name Box +<!-- .IN "Box widget" "class name" --> +Superclass Composite +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Box widget provides geometry management of arbitrary widgets in a +box of a specified dimension. The children are rearranged when +resizing events occur either on the Box or its children, or when +children are managed or unmanaged. The Box widget always attempts to +pack its children as tightly as possible within the geometry allowed by +its parent. +</para> +<para> +<!-- .LP --> +Box widgets are commonly used to manage a related set of buttons and +are often called ButtonBox widgets, but the children are not +limited to buttons. The Box's children are arranged on a background that +has its own specified dimensions and color. +</para> +<sect2 id="box_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Box widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Box 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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>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>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</function></entry> + </row> + <row> + <entry>hSpace</entry> + <entry>HSpace</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>orientation</entry> + <entry>Orientation</entry> + <entry>Orientation</entry> + <entry></entry> + <entry>XtorientVertical</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>vSpace</entry> + <entry>VSpace</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<variablelist> + <varlistentry> + <term> + <function>hSpace</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>vSpace</function> + </term> + <listitem> + <para> +The amount of space, in pixels, to leave between the children. This +resource specifies the amount of space left between the outermost +children and the edge of the box. +<!-- .Mm --> +<!-- .Nc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>orientation</function> + </term> + <listitem> + <para> +Specifies whether the preferred shape of the box (i.e. the result +returned by the query_geometry class method) is tall and narrow +<function>XtorientVertical</function> or short and wide <function>XtorientHorizontal</function>. +<!-- .IN "XtorientVertical" "" --> +<!-- .IN "XtorientHorizontal" "" --> +<!-- .IN "conversions" "Orientation" --> +When the Box is a child of a parent which enforces width constraints, it +is usually better to specify <function>XtorientVertical</function> (the default). +When the parent enforces height constraints, it is usually better to +specify <function>XtorientHorizontal</function>. +<!-- .Rs "horizontal \fPand\fB vertical" --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Layout_Semantics"> +<title>Layout Semantics</title> +<!-- .IN "Box widget" "layout semantics" --> +<para> +<!-- .LP --> +Each time a child is managed or unmanaged, the Box widget will attempt +to reposition the remaining children to compact the box. Children are +positioned in order left to right, top to bottom. The packing +algorithm used depends on the <function>orientation</function> of the Box. +<variablelist> + <varlistentry> + <term> + <function>XtorientVertical</function> + </term> + <listitem> + <para> +<!-- .IN "XtorientVertical" "" @DEF@ --> +When the next child does not fit on the current row, a new row is +started. If a child is wider than the width of the box, the box will +request a larger width from its parent and will begin the layout +process from the beginning if a new width is granted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>XtorientHorizontal</function> + </term> + <listitem> + <para> +<!-- .IN "XtorientHorizontal" "" @DEF@ --> +When the next child does not fit on the current row, the Box widens if +possible (so as to keep children on a single row); otherwise a new row is +started. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +After positioning all children, the Box widget attempts to shrink its +own size to the minimum dimensions required for the layout. + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/CH1.xml b/libXaw/specs/CH1.xml new file mode 100644 index 000000000..a4fb08c2d --- /dev/null +++ b/libXaw/specs/CH1.xml @@ -0,0 +1,725 @@ +<chapter id="athena_widgets_and_the_intrinsics"> +<title>Athena Widgets and The Intrinsics</title> +<para> +The X Toolkit is made up of two distinct pieces, the Xt Intrinsics and a +widget set. The Athena widget set is a sample implementation of a +widget set built upon the Intrinsics. In the X Toolkit, a widget is the +combination of an X window or subwindow and its associated input and +output semantics. +</para> +<para> +Because the Intrinsics provide the same basic functionality to all widget +sets it may be possible to use widgets from the Athena widget set with +other widget sets based upon the Intrinsics. Since widget sets may also +implement private protocols, all functionality may not be available when +mixing and matching widget sets. For information about the Intrinsics, see +the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +<para> +The Athena widget set is a library package layered on top of the Intrinsics +and Xlib that provides a set of user interface tools sufficient to build +a wide variety of applications. This layer extends the basic +abstractions provided by X and provides the next layer of functionality +primarily by supplying a cohesive set of sample widgets. Although the +Intrinsics are a Consortium standard, there is no standard widget set. +</para> + +<para> +To the extent possible, the Intrinsics are "policy-free". The application +environment and widget set, not the Intrinsics, define, implement, and +enforce: +</para> + +<itemizedlist> + <listitem><para>Policy</para></listitem> + <listitem><para>Consistency</para></listitem> + <listitem><para>Style</para></listitem> +</itemizedlist> + +<para> +Each individual widget implementation defines its own policy. The X Toolkit +design allows for, but does not necessarily encourage, the free mixing +of radically differing widget implementations. +</para> + +<sect1 id="Introduction_to_the_tk"> +<title>Introduction to the X Toolkit</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Introduction to the X Toolkit --> +<!-- .XE --> +<!-- .IN "introduction" "" "@DEF@" --> +The X Toolkit provides tools that simplify the design of +application user interfaces in the X Window System programming environment. +It assists application programmers by providing a set of common +underlying user-interface functions. It also lets widget programmers +modify existing widgets, by subclassing, or add new widgets. By using +the X Toolkit in their applications, programmers can present a similar +user interface across applications to all workstation users. +</para> +<para> +<!-- .LP --> +The X Toolkit consists of: +</para> +<itemizedlist> + <listitem> + <para> +A set of Intrinsics functions for building widgets + </para> + </listitem> + <listitem> + <para> +An architectural model for constructing widgets + </para> + </listitem> + <listitem> + <para> +A widget set for application programming + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +While the majority of the Intrinsics functions are intended +for the widget programmer, +a subset of the Intrinsics functions are to be used by application programmers +(see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>). +The architectural model lets the widget programmer design new widgets +by using the Intrinsics and by combining other widgets. +The application interface layers built on top of the X Toolkit include a +coordinated set of widgets and composition policies. +Some of these widgets and policies are specific to a single +application domain, and others are common to a variety of +applications. +</para> +<para> +<!-- .LP --> +The remainder of this chapter discusses the X Toolkit and Athena widget set: +</para> +<itemizedlist> + <listitem> + <para> +Terminology + </para> + </listitem> + <listitem> + <para> +Model + </para> + </listitem> + <listitem> + <para> +Conventions used in this manual + </para> + </listitem> + <listitem> + <para> +Format of the Widget Reference Chapters + </para> + </listitem> +</itemizedlist> +</sect1> +<sect1 id="Terminology"> +<title>Terminology</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Terminology --> +<!-- .XE --> +</para> +<para> +<!-- .LP --> +In addition to the terms already defined for X programming (see +<emphasis remap='I'>Xlib - C Language Interface</emphasis>), +the following terms are specific to the Intrinsics and Athena widget set +and used throughout this document. +</para> +<para> +<!-- .LP --> +<function>Application programmer</function> +<!-- .IN "application programmer" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A programmer who uses the X Toolkit to produce an application user interface. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Child</function> +<!-- .IN "child" "" "@DEF" --> +</para> +<itemizedlist> + <listitem> + <para> +A widget that is contained within another "parent" widget. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Class</function> +<!-- .IN "class" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +The general group to which a specific object belongs. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Client</function> +<!-- .IN "client" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A function that uses a widget in an application or for composing +other widgets. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>FullName</function> +<!-- .IN "FullName" "" "@DEF" --> +</para> +<itemizedlist> + <listitem> + <para> +The name of a widget instance appended to the full name of its parent. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Instance</function> +<!-- .IN "instance" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A specific widget object as opposed to a general widget class. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Method</function> +<!-- .IN "method" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A function or procedure implemented by a widget class. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Name</function> +<!-- .IN "name" "widget" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +The name that is specific to an instance of a widget for a given client. +This name is specified at creation time and cannot be modified. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Object</function> +<!-- .IN "object" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A data abstraction consisting of private data and private and public +functions that operate on the private data. +Users of the abstraction can interact with the object only through calls +to the object's public functions. +In the X Toolkit, +some of the object's public functions are called directly by the application, +while others are called indirectly when the application calls the common +Intrinsics functions. +In general, if a function is common to all widgets, +an application uses a single Intrinsics function to invoke the function for all +types of widgets. +If a function is unique to a single widget type, +the widget exports the function. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Parent</function> +<!-- .IN "parent" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A widget that contains at least one other ("child") widget. +A parent widget is also known as a composite widget. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Resource</function> +<!-- .IN "resource" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A named piece of data in a widget that can be set by a client, +by an application, or by user defaults. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Superclass</function> +<!-- .IN "superclass" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A larger class of which a specific class is a member. +All members of a class are also members of the superclass. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>User</function> +<!-- .IN "user" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A person interacting with a workstation. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Widget</function> +<!-- .IN "widget" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +An object providing a user-interface abstraction (for example, a Scrollbar +widget). + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Widget class</function> +<!-- .IN "widget class" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +The general group to which a specific widget belongs, +otherwise known as the type of the widget. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>Widget programmer</function> +<!-- .IN "widget programmer" "" "@DEF@" --> +</para> +<itemizedlist> + <listitem> + <para> +A programmer who adds new widgets to the X Toolkit. + </para> + </listitem> +</itemizedlist> +</sect1> +<sect1 id="Underlying_Model"> +<title>Underlying Model</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Underlying Model --> +<!-- .XE --> +<!-- .IN "underlying model" "" "@DEF@" --> +The underlying architectural model is based on the following premises: +<!-- .KS --> +</para> +<itemizedlist> + <listitem> + <para> + </para> + </listitem> + <listitem> + <para> +Every user-interface widget is associated with an X window. +The X window ID for a widget is readily available from the widget. +Standard Xlib calls can be used by widgets for many of their input and +output operations. +<!-- .KE --> +<!-- .KS --> + </para> + </listitem> + <listitem> + <para> + </para> + </listitem> + <listitem> + <para> +The data for every widget is private to the widget and its subclasses. +That is, the data is neither directly accessible +nor visible outside of the module implementing the widget. +All program interaction with the widget is performed by a set of operations +(methods) that are defined for the widget. +<!-- .KE --> +<!-- .KS --> + </para> + </listitem> + <listitem> + <para> + </para> + </listitem> + <listitem> + <para> +Widget semantics are clearly separated from widget layout geometry. +Widgets are concerned with implementing specific user-interface +semantics. They have little control over issues such as their size or +placement relative to other widget peers. Mechanisms are provided for +associating geometric managers with widgets and for widgets to make +suggestions about their own geometry. +<!-- .KE --> + </para> + </listitem> +</itemizedlist> +</sect1> +<sect1 id="Conventions_Used_in_this_Manual"> +<title>Conventions Used in this Manual</title> +<itemizedlist> + <listitem> + <para> +<!-- .IN "conventions" "used in manual" "@DEF@" --> +All resources available to the widgets are listed with each widget. Many +of these are available to more than one widget class due to the object +oriented nature of the Intrinsics. The new resources for each widget are +listed in bold text, and the inherited resources are listed in plain text. + </para> + </listitem> + <listitem> + <para> +Global symbols are printed in <function>bold</function> and can be function names, +symbols defined in include files, or structure names. Arguments are +printed in <emphasis remap='I'>italics</emphasis>. + </para> + </listitem> + <listitem> + <para> +Each function is introduced by a general discussion that distinguishes +it from other functions. The function declaration itself follows, and +each argument is specifically explained. General discussion of the +function, if any is required, follows the arguments. Where +applicable, the last paragraph of the explanation lists the return values +of the function. + </para> + </listitem> + <listitem> + <para> +To eliminate any ambiguity between those arguments that you pass and +those that a function returns to you, the explanations for all +arguments that you pass start with the word <emphasis remap='I'>specifies</emphasis> or, in the +case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>. The explanations +for all arguments that are returned to you start with the word +<emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word +<emphasis remap='I'>return</emphasis>. The explanations for all arguments that you can pass +and are returned start with the words <emphasis remap='I'>specifies and returns</emphasis>. + </para> + </listitem> + <listitem> + <para> +Any pointer to a structure that is used to return a value is +designated as such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name. +All other pointers passed to these functions are used for reading +only. A few arguments use pointers to structures that are used for +both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> +suffix. +<!-- .IN "_return" "" "@DEF@" --> +<!-- .IN "_in_out" "" "@DEF@" --> + </para> + </listitem> +</itemizedlist> +</sect1> +<sect1 id="Format_of_the_Widget_Reference_Chapters"> +<title>Format of the Widget Reference Chapters</title> +<para> +<!-- .LP --> +<!-- .IN "conventions" "chapter format" "@DEF@" --> +<!-- .IN "chapter format" "" "@DEF@" --> +The majority of this document is a reference guide for the Athena +widget set. Chapters three through six give the programmer all +information necessary to use the widgets. The layout of the chapters +follows a specific pattern to allow the programmer to easily find the +desired information. +</para> +<para> +<!-- .LP --> +The first few pages of every chapter give an overview of the widgets +in that section. Widgets are grouped into chapters by functionality. +<variablelist> + <varlistentry> + <term> + "Chapter <!-- xref --> + </term> + <listitem> + <para> +Simple Widgets + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + "Chapter <!-- xref --> + </term> + <listitem> + <para> +Menus + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + "Chapter <!-- xref --> + </term> + <listitem> + <para> +Text Widgets + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + "Chapter <!-- xref --> + </term> + <listitem> + <para> +Composite and Constraint Widget + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Following the introduction will be a description of each widget in that +chapter. When no functional grouping is obvious the widgets are listed +in alphabetical order, such as in chapters three and six. +</para> +<para> +<!-- .LP --> +The first section of each widget's description is a table that +contains general information about this widget class. Here is the +table for the Box widget, and an explanation of all the entries. +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Box.h> +Class Header file <X11/Xaw/BoxP.h> +Class boxWidgetClass +Class Name Box +Superclass Composite +<!-- .sp --> +</literallayout> +<variablelist> + <varlistentry> + <term> + <function>Application Header File</function> + </term> + <listitem> + <para> +<!-- .IN "application header file" "" "@DEF@" --> +This file must be included when an application uses this widget. +It usually contains the class definition, and some resource macros. +This is often called the ``public'' header file. +<!-- .IN "class header file" "" "@DEF@" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Class Header File</function> + </term> + <listitem> + <para> +This file will only be used by widget programmers. It will need to be +included by any widget that subclasses this widget. This is often +called the ``private'' header file. +<!-- .IN "class" "" "@DEF@" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Class</function> + </term> + <listitem> + <para> +This is the widget class of this widget. This global symbol is passed to +<function>XtCreateWidget</function> so that the Intrinsics will know which type of widget +to create. +<!-- .IN "class name" "" "@DEF@" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Class Name</function> + </term> + <listitem> + <para> +This is the resource name of this class. This name can be used in +a resource file to match any widget of this class. +<!-- .IN "superclass" "" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Superclass</function> + </term> + <listitem> + <para> +This is the superclass that this widget class is descended from. If +you understand how the superclass works it will allow you to more quickly +understand what this widget does, since much of its functionality may be +inherited from its superclass. +<!-- .sp --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +After this table follows a general description of the default behavior of +this widget, as seen by the user. In many cases this functionality +may be overridden by the application programmer, or by the user. +</para> +<para> +<!-- .LP --> +The next section is a table showing the +name, class, type and default value of each resource that is available +to this widget. There is also a column containing notes describing +special restrictions placed upon individual resources. +<!-- .IN "notes" "" "@DEF@" --> +<!-- .IN "A, note" "" "@DEF@" --> +<!-- .IN "D, note" "" "@DEF@" --> +<!-- .IN "C, note" "" "@DEF@" --> +<!-- .IN "R, note" "" "@DEF@" --> +<variablelist> + <varlistentry> + <term> + A + </term> + <listitem> + <para> +This resource may be automatically adjusted when another +resource is changed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + C + </term> + <listitem> + <para> +This resource is only settable at widget creation time, and may not +be modified with <function>XtSetValues</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + D + </term> + <listitem> + <para> +Do not modify this resource. While setting this resource will +work, it can cause unexpected behavior. When this symbol appears +there is another, preferred, interface provided by the X Toolkit. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + R + </term> + <listitem> + <para> +This resource is READ-ONLY, and may not be modified. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +After the resource table is a detailed description of every resource +available to that widget. Many of these are redundant, but printing +them with each widget saves page flipping. The names of the resources +that are inherited are printed in plain text, while the names of the +resources that are new to this class are printed in <function>bold</function>. +If you have already read the description of the superclass you need +only pay attention to the resources printed in bold. +</para> +<para> +<!-- .LP --> +For each composite widget there is a section on layout semantics that +follows the resource description. This section will describe the +effect of constraint resources on the layout of the children, as well +as a general description of where it prefers to place its children. +</para> +<para> +<!-- .LP --> +Descriptions of default translations and action routines come next, for +widgets to which they apply. The last item in each widget's +documentation is the description of all convenience routines provided by +the widget. +</para> +</sect1> +<sect1 id="Input_Focus"> +<title>Input Focus</title> +<!-- .XS --> +<!-- Input Focus --> +<!-- .XE --> +<!-- .IN "input focus" "" "@DEF@" --> +<!-- .IN "input" "" "@DEF@" --> +<!-- .IN "XtNinput" "" "@DEF@" --> +<para> +<!-- .LP --> +The Intrinsics define a resource on all Shell widgets that interact with +the window manager called <function>input</function>. This resource requests the +assistance of window manager in acquiring the input focus. The +resource defaults to <function>False</function> in the Intrinsics, but is redefined to +default to <function>True</function> when an application is using the Athena widget +set. An application programmer may override this default and set the +resource back to <function>False</function> if the application does not need the window +manager to give it the input focus. See the +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> for details +on the <emphasis remap='I'>input</emphasis> resource. + +</para> +</sect1> +</chapter> diff --git a/libXaw/specs/CH2.xml b/libXaw/specs/CH2.xml new file mode 100644 index 000000000..08f0ff569 --- /dev/null +++ b/libXaw/specs/CH2.xml @@ -0,0 +1,1891 @@ +<chapter><title>Using Widgets</title> +<sect1 id="using_widgets"> +<title>Using Widgets</title> +<para> +Widgets serve as the primary tools for building a user interface or +application environment. The Athena widget set consists of primitive +widgets that contain no children (for example, a command button) and +composite widgets which may contain one or more widget children (for +example, a Box widget). +</para> +<para> +The remaining chapters explain the widgets that are provided +by the Athena widget set. +These user-interface components serve as an interface for +application programmers who do not want to implement their own widgets. +In addition, they serve as a starting point +for those widget programmers who, using the Intrinsics mechanisms, +want to implement alternative application programming interfaces. +</para> +<para> +This chapter is a brief introduction to widget programming. The +examples provided use the Athena widgets, though most of the concepts +will apply to all widget sets. Although there are several programming +interfaces to the X Toolkit, only one is described here. A full +description of the programming interface is provided in the document +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +<sect2 id="Setting_the_Locale"> +<title>Setting the Locale</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Setting the Locale --> +<!-- .XE --> +If it is desirable that the application take advantage of +internationalization (i18n), you must establish locale with +<function>XtSetLanguageProc</function> +before <function>XtDisplayInitialize</function> or <function>XtAppInitialize</function> +is called. For full details, please refer to the document +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>, section 2.2. However, the following simplest-case +call is sufficient in many or most applications. +</para> +<para> +<!-- .LP --> +<!-- .IN "internationalization" "" "" --> +<!-- .IN "XtSetLanguageProc" "" "@DEF@" --> +<!-- .IN "locale" "" "" --> +<literallayout class="monospaced"> +<!-- .TA .5i 2i --> +<!-- .ta .5i 2i --> + XtSetLanguageProc(NULL, NULL, NULL); +</literallayout> +</para> +<para> +<!-- .LP --> +Most notably, this will affect the Standard C locale, determine which +resource files will be loaded, and what fonts will be required of FontSet +specifications. In many cases, the addition of this line is the only source change +required to internationalize Xaw programs, and will not disturb the function +of programs in the default "C" locale. +</para> +</sect2> +<sect2 id="Initializing_the_Toolkit"> +<title>Initializing the Toolkit</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Initializing the Toolkit --> +<!-- .XE --> +You must call a toolkit initialization function before invoking any +other toolkit routines (besides locale setting, above). +<function>XtAppInitialize</function> +opens the X server connection, parses the command line, +and creates an initial widget that will serve as the root of +a tree of widgets created by this application. +<!-- .IN "initialization" "" "@DEF@" --> +<!-- .IN "toolkit initialization" "" "@DEF@" --> +<!-- .IN "XtAppInitialize" "" "@DEF@" --> +<!-- .IN "fallback resources" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XtAppInitialize</function></funcdef> + <paramdef>XtAppContext<parameter> app_context_return</parameter></paramdef> + <paramdef>String<parameter> application_class</parameter></paramdef> + <paramdef>XrmOptionDescRec<parameter> options</parameter></paramdef> + <paramdef>Cardinal<parameter> num_options</parameter></paramdef> + <paramdef>int<parameter> *argc_in_out</parameter></paramdef> + <paramdef>String<parameter> *argv_in_out</parameter></paramdef> + <paramdef>String<parameter> *fallback_resources</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_con_return</emphasis> + </term> + <listitem> + <para> +Returns the application context of this application, if non-NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>application_class</emphasis> + </term> + <listitem> + <para> +Specifies the class name of this application, +which is usually the generic name for all instances of this application. +A useful convention is to form the class name by capitalizing the +first letter of the application name. For example, the application named +``xman'' has a class name of ``Xman''. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>options</emphasis> + </term> + <listitem> + <para> +Specifies how to parse the command line for any application-specific +resources. +The options argument is passed as a parameter to +<function>XrmParseCommand</function> . +For further information, +see <emphasis remap='I'>Xlib - C Language Interface</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_options</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in the options list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argc_in_out</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the number of command line parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>argv_in_out</emphasis> + </term> + <listitem> + <para> +Specifies the command line parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fallback_resources</emphasis> + </term> + <listitem> + <para> +Specifies resource values to be used if the site-wide application class +defaults file cannot be opened, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list to use when creating the Application shell. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in <emphasis remap='I'>args</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will remove the command line arguments that the toolkit +reads from <emphasis remap='I'>argc_in_out</emphasis>, and <emphasis remap='I'>argv_in_out</emphasis>. It will then +attempt to open the display. If the display cannot be opened, an error +message is issued and XtAppInitialize terminates the application. Once +the display is opened, all resources are read from the locations +specified by the Intrinsics. This function returns an ApplicationShell +widget to be used as the root of the application's widget tree. +</para> +</sect2> +<sect2 id="Creating_a_Widget"> +<title>Creating a Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Creating a Widget --> +<!-- .XE --> +<!-- .IN "widget creation" "" "@DEF@" --> +<!-- .IN "creating widgets" "" "@DEF@" --> +<!-- .IN "XtRealizeWidget" "" "" --> +Creating a widget is a three-step process. First, the widget instance +is allocated, and various instance-specific attributes are set by +using <function>XtCreateWidget</function>. Second, the widget's parent is informed +of the new child by using <function>XtManageChild</function>. Finally, X windows are +created for the parent and all its children by using <function>XtRealizeWidget</function> +and specifying the top-most widget. The first two steps can be +combined by using <function>XtCreateManagedWidget</function>. In addition, +<function>XtRealizeWidget</function> is automatically called when the child becomes +managed if the parent is already realized. +</para> +<para> +<!-- .LP --> +To allocate, initialize, and manage a widget, use +<function>XtCreateManagedWidget .</function> +<!-- .IN "XtCreateManagedWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XtCreateManagedWidget</function></funcdef> + <paramdef>String<parameter> name</parameter></paramdef> + <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef> + <paramdef>Widget<parameter> parent</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the instance name for the created widget that is used for retrieving +widget resources. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>widget_class</emphasis> + </term> + <listitem> + <para> +Specifies the widget class pointer for the created widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>parent</emphasis> + </term> + <listitem> + <para> +Specifies the parent widget ID. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies the argument list. The argument list is a variable-length +list composed of name and value pairs that contain information +pertaining to the specific widget instance being created. For further +information, see Section 2.7.2. <!-- xref> --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. +If the num_args is zero, the argument list is never referenced. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When a widget instance is successfully created, the widget identifier +is returned to the application. If an error is encountered, the +<function>XtError</function> +routine is invoked to inform the user of the error. +<!-- .IN "XtError" "" "" --> +</para> +<para> +<!-- .LP --> +For further information, see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Common_Resources"> +<title>Common Resources</title> +<!-- .XS --> +<!-- Common Resources --> +<!-- .XE --> +<!-- .IN "resource" "" --> +<para> +<!-- .LP --> +Although a widget can have unique arguments that it understands, all +widgets have common arguments that provide some regularity of operation. +The common arguments allow arbitrary widgets to be managed by +higher-level components without regard for the individual widget type. +Widgets will ignore any argument that they do not understand. +</para> +<para> +<!-- .LP --> +The following resources are retrieved from the argument list +or from the resource database by all of the Athena widgets: +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>accelerators</entry> + <entry>Accelerators</entry> + <entry>AcceleratorTable</entry> + <entry>NULL</entry> + </row> + <row> + <entry>ancestorSensitive</entry> + <entry>AncestorSensitive</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>background</entry> + <entry>Background</entry> + <entry>Pixel</entry> + <entry>XtDefaultBackground</entry> + </row> + <row> + <entry>backgroundPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderColor</entry> + <entry>BorderColor</entry> + <entry>Pixel</entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>borderPixmap</entry> + <entry>Pixmap</entry> + <entry>Pixmap</entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>borderWidth</entry> + <entry>BorderWidth</entry> + <entry>Dimension</entry> + <entry>1</entry> + </row> + <row> + <entry>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry>Parent's Colormap</entry> + </row> + <row> + <entry>depth</entry> + <entry>Depth</entry> + <entry>int</entry> + <entry>Parent's Depth</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>screen</entry> + <entry>Screen</entry> + <entry>Screen</entry> + <entry>Parent's Screen</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry>True</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>x</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry>0</entry> + </row> + <row> + <entry>y</entry> + <entry>Position</entry> + <entry>Position</entry> + <entry>0</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .IN "XtDefaultForeground" "" "" --> +<!-- .IN "XtDefaultBackground" "" "" --> +</para> +<para> +<!-- .LP --> +The following additional resources are retrieved from the argument list +or from the resource database by many of the Athena widgets: +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Name</entry> + <entry>Class</entry> + <entry>Type</entry> + <entry>Default Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry>NULL</entry> + </row> + <row> + <entry>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry><emphasis remap='I'>widget dependent</emphasis></entry> + </row> + <row> + <entry>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry>GreyPixmap</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .IN "XtDefaultForeground" "" "" --> +</para> +</sect2> +<sect2 id="Resource_Conversions"> +<title>Resource Conversions</title> +<!-- .XS --> +<!-- Resource Conversions --> +<!-- .XE --> +<!-- .IN "conversions" "" "@DEF@" --> +<!-- .IN "string conversions" "" "@DEF@" --> +<!-- .IN "type conversions" "" "@DEF@" --> +<para> +<!-- .LP --> +Most resources in the Athena widget set have a converter registered that +will translate the string in a resource file to the correct internal +representation. While some are obvious (string to integer, for example), +others need specific mention of the allowable values. Three general +converters are described here: +</para> +<itemizedlist> + <listitem> + <para> +Cursor + </para> + </listitem> + <listitem> + <para> +Pixel + </para> + </listitem> + <listitem> + <para> +Bitmap + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Many widgets have defined special converters that apply only to that +widget. When these occur, the documentation section for that widget +will describe the converter. +</para> +<sect3 id="Cursor_Conversion"> +<title>Cursor Conversion</title> +<!-- .IN "conversions" "ColorCursor" "@DEF@" --> +<!-- .IN "conversions" "Cursor" "@DEF@" --> +<!-- .IN "cursor" "" "" --> +<para> +<!-- .LP --> +The value for the <function>cursorName</function> resource is specified in the resource +database as a string, and is of the following forms: +</para> +<itemizedlist> + <listitem> + <para> +A standard X cursor name from <function>< X11/cursorfont.h ></function>. +The names in <function>cursorfont.h</function> each describe a specific cursor. The +resource names for these cursors are exactly like the names in this file +except the <function>XC_</function> is not used. The cursor definition <function>XC_gumby</function> +has a resource name of <function>gumby</function>. + </para> + </listitem> + <listitem> + <para> +Glyphs, as in <emphasis remap='I'>FONT font-name glyph-index [[ font-name ] glyph-index ]</emphasis>. +The first font and glyph specify the cursor source pixmap. +The second font and glyph specify the cursor mask pixmap. +The mask font defaults to the source font, +and the mask glyph index defaults to the source glyph index. + </para> + </listitem> + <listitem> + <para> +A relative or absolute file name. +If a relative or absolute file name is specified, that file is used to +create the source pixmap. Then the string "Mask" is appended to +locate the cursor mask pixmap. If the "Mask" file does not exist, the +suffix "msk" is tried. If "msk" fails, no cursor mask will be used. +If the filename does not start with '/' or './' the the bitmap +file path is used (see section 2.4.3). <!-- xref --> + </para> + </listitem> +</itemizedlist> +</sect3> +<sect3 id="Pixel_Conversion"> +<title>Pixel Conversion</title> +<para> +<!-- .LP --> +<!-- .IN "conversions" "Pixel" "@DEF@" --> +<!-- .IN "pixel" "" "" --> +<!-- .IN "rgb.txt" "" "" --> +<!-- .IN "XtDefaultForeground" "" "" --> +<!-- .IN "XtDefaultBackground" "" "" --> +The string-to-pixel converter takes any name that is acceptable to +XParseColor (see <emphasis remap='I'>Xlib - C Language Interface</emphasis>). In addition this routine understands +the special toolkit symbols `XtDefaultForeground' and +`XtDefaultBackground', described in <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. In short the acceptable +pixel names are: +</para> +<itemizedlist> + <listitem> + <para> +Any color name for the rgb.txt file (typically in the directory +/usr/lib/X11 on POSIX systems). + </para> + </listitem> + <listitem> + <para> +A numeric specification of the form #<red><green><blue> where these +numeric values are hexadecimal digits (both upper and lower case). + </para> + </listitem> + <listitem> + <para> +The special strings `XtDefaultForeground' and `XtDefaultBackground' + </para> + </listitem> +</itemizedlist> +</sect3> +<sect3 id="Bitmap_Conversion"> +<title>Bitmap Conversion</title> +<!-- .IN "bitmap conversions" "" "@DEF@" --> +<!-- .IN "conversions" "Bitmap" "@DEF@" --> +<!-- .IN "bitmapFilePath" "" "@DEF@" --> +<!-- .IN "BitmapFilePath" "" "@DEF@" --> +<!-- .IN "/usr/include/X11/bitmaps" "" "" --> +<para> +<!-- .LP --> +The string-to-bitmap converter attempts to locate a file containing +bitmap data whose name is specified by the input string. If the file +name is relative (i.e. does not begin with / or ./), the directories to +be searched are specified in the <function>bitmapFilePath</function> resource--class +<function>BitmapFilePath</function>. This resource specifies a colon (:) separated +list of directories that will be searched for the named bitmap or +cursor glyph (see section 2.4.1). The <function>bitmapFilePath</function> resource is +global to the application, and may <function>not</function> be specified differently +for each widget that wishes to convert a cursor to bitmap. In addition +to the directories specified in the <function>bitmapFilePath</function> resource a +default directory is searched. When using POSIX the default +directory is +<function>/usr/include/X11/bitmaps .</function> +</para> +</sect3> +</sect2> +<sect2 id="Realizing_a_Widget"> +<title>Realizing a Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Realizing a Widget --> +<!-- .XE --> +<!-- .IN "realizing widgets" "" "@DEF@" --> +The +<function>XtRealizeWidget</function> +function performs two tasks: +</para> +<itemizedlist> + <listitem> + <para> +Calculates the geometry constraints of all managed descendants +of this widget. The actual calculation is put off until realize time +for performance reasons. + </para> + </listitem> + <listitem> + <para> +Creates an X window for the widget and, if it is a composite widget, +realizes each of its managed children. +<!-- .IN "XtRealizeWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtRealizeWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> + </para> + </listitem> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For further information about this function, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Processing_Events"> +<title>Processing Events</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Processing Events --> +<!-- .XE --> +<!-- .IN "events" "" "" --> +<!-- .IN "XtAppInitialize" "" "" --> +Now that the application has created, managed and realized its +widgets, it is ready to process the events that will be delivered by the +X Server to this client. A function call that will process the +events is <function>XtAppMainLoop</function>. +<!-- .IN "XtAppMainLoop" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtAppMainLoop</function></funcdef> + <paramdef>XtAppContext<parameter> app_context</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context of this application. The value is +normally returned by <function>XtAppInitialize</function>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function never returns: it is an infinite loop that processes the +X events. User input can be handled through callback procedures and +application defined action routines. More details are provided in +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect2> +<sect2 id="Standard_Widget_Manipulation_Functions"> +<title>Standard Widget Manipulation Functions</title> +<!-- .XS --> +<!-- Standard Widget Manipulation Functions --> +<!-- .XE --> +<para> +<!-- .LP --> +After a widget has been created, a client can interact with that +widget by calling one of the standard widget manipulation routines +provided by the Intrinsics, or a widget class-specific manipulation routine. +</para> +<para> +<!-- .LP --> +The Intrinsics provide generic routines to give the application programmer +access to a set of standard widget functions. The common widget +routines let an application or composite widget perform the following +operations on widgets without requiring explicit knowledge of the widget +type. +</para> +<itemizedlist> + <listitem> + <para> +Control the mapping of widget windows + </para> + </listitem> + <listitem> + <para> +Destroy a widget instance + </para> + </listitem> + <listitem> + <para> +Obtain an argument value + </para> + </listitem> + <listitem> + <para> +Set an argument value + </para> + </listitem> +</itemizedlist> +<sect3 id="Mapping_Widgets"> +<title>Mapping Widgets</title> +<para> +<!-- .LP --> +By default, +widget windows are mapped (made viewable) automatically by +<function>XtRealizeWidget</function>. This behavior can be disabled by using +<function>XtSetMappedWhenManaged</function>, making the client responsible for calling +<function>XtMapWidget</function> to make the widget viewable. +<!-- .IN "XtSetMappedWhenManaged" "" "@DEF@" --> +<!-- .IN "XtMapWidget" "" "" --> +<!-- .IN "XtRealizeWidget" "" "" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtSetMappedWhenManaged</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> map_when_managed</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>map_when_managed</emphasis> + </term> + <listitem> + <para> +Specifies the new value. +If map_when_managed is <function>True</function>, the widget is mapped automatically +when it is realized. If map_when_managed is <function>False</function>, the client +must call +<function>XtMapWidget</function> +or make a second call to +<function>XtSetMappedWhenManaged</function> +to cause the child window to be mapped. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +The definition for +<function>XtMapWidget</function> +is: +<!-- .IN "XtMapWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtMapWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When you are creating several children in sequence for a previously +realized common parent it is generally more efficient to construct a +list of children as they are created (using <function>XtCreateWidget</function>) and +then use <function>XtManageChildren</function> to request that their parent managed +them all at once. By managing a list of children at one time, the +parent can avoid wasteful duplication of geometry processing and the +associated ``screen flash''. +<!-- .IN "XtManageChildren" "" "@DEF@" --> +<!-- .IN "XtCreateWidget" "" "" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtManageChildren</function></funcdef> + <paramdef>WidgetList<parameter> children</parameter></paramdef> + <paramdef>Cardinal<parameter> num_children</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>children</emphasis> + </term> + <listitem> + <para> +Specifies a list of children to add. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_children</emphasis> + </term> + <listitem> + <para> +Specifies the number of children to add. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +If the parent is already visible on the screen, it is especially +important to batch updates so that the minimum amount of visible window +reconfiguration is performed. +</para> +<para> +<!-- .LP --> +For further information about these functions, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect3> +<sect3 id="Destroying_Widgets"> +<title>Destroying Widgets</title> +<para> +<!-- .LP --> +To destroy a widget instance of any type, use +<function>XtDestroyWidget</function> +<!-- .IN "XtDestroyWidget" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtDestroyWidget</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XtDestroyWidget</function> +destroys the widget and recursively destroys any children that it may have, +including the windows created by its children. +After calling +<function>XtDestroyWidget ,</function> +no further references should be made to the widget or any children +that the destroyed widget may have had. +</para> +</sect3> +<sect3 id="Retrieving_Widget_Resource_Values"> +<title>Retrieving Widget Resource Values</title> +<para> +<!-- .LP --> +To retrieve the current value of a resource attribute associated +with a widget instance, use +<function>XtGetValues .</function> +<!-- .IN "XtGetValues" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtGetValues</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies a variable-length argument list of name and <function>address</function> +pairs that contain the resource name and the address into which the +resource value is stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The arguments and values passed in the argument list are dependent on +the widget. Note that the caller is responsible for providing space +into which the returned resource value is copied; the <function>ArgList</function> +contains a pointer to this storage (e.g. x and y must be +allocated as Position). For further information, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</sect3> +<sect3 id="Modifying_Widget_Resource_Values"> +<title>Modifying Widget Resource Values</title> +<para> +<!-- .LP --> +To modify the current value of a resource attribute associated with a +widget instance, use +<function>XtSetValues .</function> +<!-- .IN "XtSetValues" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtSetValues</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>ArgList<parameter> args</parameter></paramdef> + <paramdef>Cardinal<parameter> num_args</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>args</emphasis> + </term> + <listitem> + <para> +Specifies an array of name and <function>value</function> pairs that contain the +arguments to be modified and their new values. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_args</emphasis> + </term> + <listitem> + <para> +Specifies the number of arguments in the argument list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The arguments and values that are passed will depend on the widget +being modified. Some widgets may not allow certain resources to be +modified after the widget instance has been created or realized. +No notification is given if any part of a <function>XtSetValues</function> request is +ignored. +</para> +<para> +<!-- .LP --> +For further information about these functions, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +<!-- .IN "XtGetValues" "" "" --> +<!-- .IN "XtSetValues" "" "" --> +<!-- .NT --> +The argument list entry for +<function>XtGetValues</function> +specifies the address to which the caller wants the value copied. The +argument list entry for +<function>XtSetValues ,</function> +however, contains the new value itself, if the size of value is less than +sizeof(XtArgVal) (architecture dependent, but at least sizeof(long)); +otherwise, it is a pointer to the value. String resources are always +passed as pointers, regardless of the length of the string. +<!-- .NE --> +</para> +</sect3> +</sect2> +<sect2 id="Using_the_Client_Callback_Interface"> +<title>Using the Client Callback Interface</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Using the Client Callback Interface --> +<!-- .XE --> +<!-- .IN "callbacks" "" "" --> +Widgets can communicate changes in their state to their clients +by means of a callback facility. +The format for a client's callback handler is: +<!-- .IN "CallbackProc" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> CallbackProc</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies widget for which the callback is registered. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies arbitrary client-supplied data that the widget should pass +back to the client when the widget executes the client's callback +procedure. This is a way for the client registering the callback to +also register client-specific data: a pointer to additional information +about the widget, a reason for invoking the callback, and so on. If no +additional information is necessary, NULL may be passed as this argument. +This field is also frequently known as the <emphasis remap='I'>closure</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies any callback-specific data the widget wants to pass to the client. +For example, when Scrollbar executes its <function>jumpProc</function> callback list, +it passes the current position of the thumb in <emphasis remap='I'>call_data</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Callbacks can be registered either by creating an argument containing +the callback list described below or by using the special convenience +routines <function>XtAddCallback</function> and <function>XtAddCallbacks</function>. When the widget +is created, a pointer to a list of callback procedure and data pairs can +be passed in the argument list to +<function>XtCreateWidget .</function> +The list is of type +<function>XtCallbackList :</function> +<!-- .IN "XtCallbackProc" --> +<!-- .IN "XtAddCallbacks" --> +<!-- .IN "XtAddCallback" --> +<!-- .IN "XtCallbackList" "" "@DEF@" --> +<!-- .IN "XtCallbackRec" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; +</literallayout> +</para> +<para> +<!-- .LP --> +The callback list must be allocated and initialized before calling +<function>XtCreateWidget .</function> +<!-- .IN "XtCreateWidget" --> +The end of the list is identified by an entry containing NULL in +callback and closure. Once the widget is created, the client can change +or de-allocate this list; the widget itself makes no further reference +to it. The closure field contains the client_data passed to the +callback when the callback list is executed. +</para> +<para> +<!-- .LP --> +The second method for registering callbacks is to use +<function>XtAddCallback</function> +after the widget has been created. +<!-- .IN "XtAddCallback" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XtAddCallback</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String<parameter> callback_name</parameter></paramdef> + <paramdef>XtCallbackProc<parameter> callback</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget to add the callback to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback_name</emphasis> + </term> + <listitem> + <para> +Specifies the callback list within the widget to append to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure to add. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the data to be passed to the callback when it is invoked. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XtAddCallback</function> +adds the specified callback to the list for the named widget. +</para> +<para> +<!-- .LP --> +All widgets provide a callback list named +<function>destroyCallback</function> +<!-- .IN "destroyCallback" "" "@DEF@" --> +where clients can register procedures that are to be executed when the +widget is destroyed. The destroy callbacks are executed when the widget +or an ancestor is destroyed. The <emphasis remap='I'>call_data</emphasis> argument is unused for +destroy callbacks. +</para> +</sect2> +<sect2 id="Programming_Considerations"> +<title>Programming Considerations</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Programming Considerations --> +<!-- .XE --> +This section provides some guidelines on how to set up an application +program that uses the X Toolkit. +</para> +<sect3 id="Writing_Applications"> +<title>Writing Applications</title> +<para> +<!-- .LP --> +<!-- .IN "writing applications" --> +<!-- .IN "StringDefs.h" --> +<!-- .IN "Intrinsic.h" --> +When writing an application that uses the X Toolkit, +you should make sure that your application performs the following: +</para> +<orderedlist> + <listitem> + <para> +Include +<function>< X11/Intrinsic.h ></function> +in your application programs. +This header file automatically includes +<function>< X11/Xlib.h >,</function> +so all Xlib functions also are defined. +It may also be necessary to include <function>< X11/StringDefs.h ></function> when setting +up argument lists, as many of the XtN<emphasis remap='I'>something</emphasis> definitions are +only defined in this file. + </para> + </listitem> + <listitem> + <para> +Include the widget-specific header files for each widget type +that you need to use. +For example, +<function>< X11/Xaw/Label.h ></function> +and +<function>< X11/Xaw/Command.h >.</function> + </para> + </listitem> + <listitem> + <para> +Call the +<function>XtAppInitialize</function> +<!-- .IN "XtAppInitialize" --> +function before invoking any other toolkit or Xlib functions. +For further information, +see Section 2.1 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. + </para> + </listitem> + <listitem> + <para> +To pass attributes to the widget creation routines that will override +any site or user customizations, set up argument lists. In this +document, a list of valid argument names is provided in the discussion +of each widget. The names each have a global symbol defined that begins +with <function>XtN</function> to help catch spelling errors. For example, +<function>XtNlabel</function> is defined for the <function>label</function> resource of many widgets. +<!-- .IN "XtN" "" "@DEF@" --> + </para> + </listitem> + <listitem> + <para> +For further information, see Section 2.9.2.2. <!-- xref --> + </para> + </listitem> + <listitem> + <para> +When the argument list is set up, create the widget with the +<function>XtCreateManagedWidget</function> function. For further information, see +Section 2.2 and the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +<!-- .IN "XtCreateManagedWidget" --> + </para> + </listitem> + <listitem> + <para> +If the widget has any callback routines, set by the +<function>XtNcallback</function> +argument or the +<function>XtAddCallback</function> +function, declare these routines within the application. +<!-- .IN "XtAddCallback" --> + </para> + </listitem> + <listitem> + <para> +After creating the initial widget hierarchy, windows must be created +for each widget by calling +<function>XtRealizeWidget</function> +on the top level widget. +<!-- .IN "XtRealizeWidget" --> + </para> + </listitem> + <listitem> + <para> +Most applications now sit in a loop processing events using +<function>XtAppMainLoop ,</function> +for example: +<!-- .IN "XtAppMainLoop" --> + </para> + </listitem> + <listitem> + <para> +<literallayout class="monospaced"> +XtCreateManagedWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>args</emphasis>, <emphasis remap='I'>num_args</emphasis>); +XtRealizeWidget(<emphasis remap='I'>shell</emphasis>); +XtAppMainLoop(<emphasis remap='I'>app_context</emphasis>); +</literallayout> + </para> + </listitem> + <listitem> + <para> +For information about this function, see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. + </para> + </listitem> + <listitem> + <para> +Link your application with +<function>libXaw</function> +(the Athena widgets), +<function>libXmu</function> +(miscellaneous utilities), +<function>libXt</function> +(the X Toolkit Intrinsics), +<function>libSM</function> +(Session Management), +<function>libICE</function> +(Inter-Client Exchange), +<function>libXext</function> +(the extension library needed for the shape extension code which allows +rounded Command buttons), and +<function>libX11</function> +(the core X library). +The following provides a sample command line: +<!-- .IN "libXaw" --> +<!-- .IN "libXmu" --> +<!-- .IN "libXt" --> +<!-- .IN "libSM" --> +<!-- .IN "libICE" --> +<!-- .IN "libXext" --> +<!-- .IN "libX11" --> +<!-- .IN "linking applications" --> +<!-- .IN "compiling applications" --> + </para> + </listitem> + <listitem> + <para> +<literallayout class="monospaced"> +cc -o <emphasis remap='I'>application</emphasis> <emphasis remap='I'>application</emphasis>.c \-lXaw \-lXmu \-lXt \ +\-lSM \-lICE \-lXext \-lX11 +</literallayout> + </para> + </listitem> +</orderedlist> +</sect3> +<sect3 id="Changing_Resource_Values"> +<title>Changing Resource Values</title> +<!-- .IN "resource" "" --> +<para> +<!-- .LP --> +The Intrinsics support two methods of changing the default resource +values; the resource manager, and an argument list passed into +XtCreateWidget. While resources values will get updated no matter +which method you use, the two methods provide slightly different +functionality. +<variablelist> + <varlistentry> + <term>Resource Manager</term> + <listitem> + <para> +This method picks up resource definitions described in <emphasis remap='I'>Xlib - C Language Interface</emphasis> from +many different locations at run time. The locations most important to +the application programmer are the <emphasis remap='I'>fallback resources</emphasis> and the +<emphasis remap='I'>app-defaults</emphasis> file, (see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> for the complete list). +Since these resource are loaded at run time, they can be overridden by +the user, allowing an application to be customized to fit the +particular needs of each individual user. These values can also be +modified without the need to rebuild the application, allowing rapid +prototyping of user interfaces. Application programmers should use +resources in preference to hard-coded values whenever possible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Argument Lists</term> + <listitem> + <para> +The values passed into the widget at creation time via an argument list +cannot be modified by the user, and allow no opportunity for +customization. It is used to set resources that cannot be specified as +strings (e.g. callback lists) or resources that should not be +overridden (e.g. window depth) by the user. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<sect4 id="Specifying_Resources"> +<title>Specifying Resources</title> +<para> +<!-- .LP --> +It is important for all X Toolkit application programmers to +understand how to use the X Resource Manager to specify resources for +widgets in an X application. This section will describe the most common +methods used to specify these resources, and how to use the X Resource +manager. +<!-- .IN "xrdb" --> +<variablelist> + <varlistentry> + <term> + <function>Xrdb</function> + </term> + <listitem> + <para> +The <function>xrdb</function> utility may be used to load a file containing +resources into the X server. Once the resources are loaded, the +resources will affect any new applications started on the display that +they were loaded onto. +<!-- .IN "application defaults" --> +<!-- .IN "app-defaults" --> +<!-- .IN "/usr/lib/X11/app-defaults" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Application Defaults</term> + <listitem> + <para> +The application defaults (app-defaults) file (normally in +/usr/lib/X11/app-defaults/<emphasis remap='I'>classname</emphasis>) for an application is loaded +whenever the application is started. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The resource specification has two colon-separated parts, a name, and +a value. The <emphasis remap='I'>value</emphasis> is a string whose format is dependent on the +resource specified by <emphasis remap='I'>name</emphasis>. <emphasis remap='I'>Name</emphasis> is constructed by +appending a resource name to a full widget name. +</para> +<para> +<!-- .LP --> +The full widget name is a list of the name of every ancestor of the +desired widget separated by periods (.). Each widget also has a class +associated with it. A class is a type of widget (e.g. Label or +Scrollbar or Box). Notice that class names, by convention, begin with +capital letters and instance names begin with lower case letters. The +class of any widget may be used in place of its name in a resource +specification. Here are a few examples: +<variablelist> + <varlistentry> + <term> + xman.form.button1 + </term> + <listitem> + <para> +This is a fully specified resource name, and will affect only widgets +called button1 that are children of widgets called form that are +children of +applications named xman. (Note that while typically two widgets that +are siblings will have different names, it is not prohibited.) + + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman.Form.Command + </term> + <listitem> + <para> +This will match any Command widget that is a child of a Form widget +that is itself a child of an application of class <emphasis remap='I'>Xman</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman.Form.button1 + </term> + <listitem> + <para> +This is a mixed resource name with both widget names and classes specified. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This syntax allows an application programmer to specify any widget +in the widget tree. To match more than one widget (for example a user +may want to make all Command buttons blue), use an asterisk (*) +instead of a period. When an asterisk is used, any number of widgets +(including zero) may exist between the two widget names. For example: +<variablelist> + <varlistentry> + <term> + Xman*Command + </term> + <listitem> + <para> +This matches all Command widgets in the Xman application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Foo*button1 + </term> + <listitem> + <para> +This matches any widget in the Foo application that is named <emphasis remap='I'>button1</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The root of all application widget trees is the widget returned by +<function>XtAppInitialize</function>. Even though this is actually an +ApplicationShell widget, the toolkit replaces its widget class with the +class name of the application. The name of this widget is either +the name used to invoke the application (<function>argv[0]</function>) or the name of +the application specified using the standard <emphasis remap='I'>-name</emphasis> command line +option supported by the Intrinsics. +</para> +<para> +<!-- .LP --> +The last step in constructing the resource name is to append the name of +the resource with either a period or asterisk to the full or partial +widget name already constructed. +<variablelist> + <varlistentry> + <term> + *foreground:Blue + </term> + <listitem> + <para> +Specifies that all widgets in all applications will have a foreground +color of blue. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + Xman*borderWidth:10 + </term> + <listitem> + <para> +Specifies that all widgets in an application whose class is Xman will +have a border width of 10 (pixels). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + xman.form.button1.label:Testing + </term> + <listitem> + <para> +Specifies that a particular widget in the xman application will have a +label named <emphasis remap='I'>Testing</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +An exclamation point (!) in the first column of a line indicates +that the rest of the line should be treated as a comment. +</para> +<para> +<!-- .LP --> +<function>Final Words</function> +</para> +<para> +<!-- .LP --> +The Resource manager is a powerful tool that can be used very +effectively to customize X Toolkit applications at run time by either the +application programmer or the user. Some final points to note: +</para> +<itemizedlist> + <listitem> + <para> +An application programmer may add new resources to their +application. These resources are associated with the global +application, and not any particular widget. The X Toolkit function used for +adding the application resources is <function>XtGetApplicationResources</function>. +<!-- .IN "XtGetApplicationResources" --> + </para> + </listitem> + <listitem> + <para> +Be careful when creating resource files. Since widgets will +ignore resources that they do not understand, any spelling +errors will cause a resource to have no effect. + </para> + </listitem> + <listitem> + <para> +Only one resource line will match any given resource. There is a set +of precedence rules, which take the following general stance. +<!-- .ta 10n --> + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para> +More specific overrides less specific, thus period always overrides asterisk. + </para> + </listitem> + <listitem> + <para> +Names on the left are more specific and override names on the right. + </para> + </listitem> + <listitem> + <para> +When resource specifications are exactly the same, user defaults +will override program defaults. + </para> + </listitem> + </itemizedlist> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +For a complete explanation of the rules of precedence, and +other specific topics see <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> and <emphasis remap='I'>Xlib - C Language Interface</emphasis>. +</para> +</sect4> +<sect4 id="Creating_Argument_Lists"> +<title>Creating Argument Lists</title> +<!-- .IN "argument lists" "" "@DEF@" --> +<para> +<!-- .LP --> +To set up an argument list for the inline specification of widget attributes, +you may use any of the four approaches discussed in this section. +Each resource name has a global symbol associated with it. This +global symbol has the form XtN<emphasis remap='I'>resource name</emphasis>. For example, the +symbol for ``foreground'' is <function>XtNforeground</function>. For further information, +see the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +<para> +<!-- .LP --> +Argument are specified by using the following structure: +<!-- .IN "ArgList" "" "@DEF@" --> +<!-- .IN "Arg" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 1.5i --> +<!-- .ta .5i 1.5i --> +typedef struct { + String name; + XtArgVal value; +} Arg, *ArgList; +</literallayout> +</para> +<para> +<!-- .LP --> +The first approach is to statically initialize the argument list. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) 300}, +}; +</literallayout> +</para> +<para> +<!-- .LP --> +This approach is convenient for lists that do not need to be computed +at runtime and makes adding or deleting new elements easy. +The +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +macro is used to compute the number of elements in the argument list, +preventing simple programming errors: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +XtCreateWidget(<emphasis remap='I'>name</emphasis>, <emphasis remap='I'>class</emphasis>, <emphasis remap='I'>parent</emphasis>, <emphasis remap='I'>arglist</emphasis>, XtNumber(<emphasis remap='I'>arglist</emphasis>)); +</literallayout> +<!-- .IN "XtSetArg" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +The second approach is to use the +<function>XtSetArg</function> +macro. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +Arg arglist[10]; +XtSetArg(arglist[1], XtNwidth, 400); +XtSetArg(arglist[2], XtNheight, 300); +</literallayout> +</para> +<para> +<!-- .LP --> +To make it easier to insert and delete entries, +you also can use a variable index: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +Arg arglist[10]; +Cardinal i=0; +XtSetArg(arglist[i], XtNwidth, 400); i++; +XtSetArg(arglist[i], XtNheight, 300); i++; +</literallayout> +</para> +<para> +<!-- .LP --> +The i variable can then be used as the argument list count in the widget +create function. +In this example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +would return 10, not 2, and therefore is not useful. +<!-- .NT --> +You should not use auto-increment or auto-decrement +within the first argument to +<function>XtSetArg .</function> +As it is currently implemented, +<function>XtSetArg</function> +is a macro that dereferences the first argument twice. +<!-- .NE --> +</para> +<para> +<!-- .LP --> +The third approach is to individually set the elements of the +argument list array: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +Arg arglist[10]; +arglist[0].name = XtNwidth; +arglist[0].value = (XtArgVal) 400; +arglist[1].name = XtNheight; +arglist[1].value = (XtArgVal) 300; +</literallayout> +</para> +<para> +<!-- .LP --> +Note that in this example, as in the previous example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +would return 10, not 2, and therefore would not be useful. +</para> +<para> +<!-- .LP --> +The fourth approach is to use a mixture of the first and third approaches: +you can statically define the argument list but modify some entries at runtime. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +static Arg arglist[] = { + {XtNwidth, (XtArgVal) 400}, + {XtNheight, (XtArgVal) NULL}, +}; +arglist[1].value = (XtArgVal) 300; +</literallayout> +</para> +<para> +<!-- .LP --> +In this example, +<!-- .IN "XtNumber" --> +<function>XtNumber</function> +can be used, as in the first approach, for easier code maintenance. +</para> +</sect4> +</sect3> +</sect2> +<sect2 id="Example_Programs"> +<title>Example Programs</title> +<!-- .XS --> +<!-- Example Programs --> +<!-- .XE --> +<!-- .IN "examples" --> +<para> +<!-- .LP --> +The best way to understand how to use any programming library is by +trying some simple examples. A collection of example programs that +introduces each of the widgets in that Athena widget set, as well as many +important toolkit programming concepts, is available in the X11R6 +release as distributed by the X Consortium. It can be found in the +distribution directory <function>contrib/examples/mit/Xaw</function>, but see your +site administrator for the exact location of these files on your system. +See the README file from that directory for a guide to the examples. +</para> +</sect2> +</sect1> +</chapter> diff --git a/libXaw/specs/CH3.xml b/libXaw/specs/CH3.xml new file mode 100644 index 000000000..8fdefcc7b --- /dev/null +++ b/libXaw/specs/CH3.xml @@ -0,0 +1,123 @@ +<chapter id="simple_widgets"> +<title>Simple Widgets</title> + +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH3.intro.xml"/> --> +<para> +Each of these widgets performs a specific user interface function. They +are <emphasis remap='I'>simple</emphasis> because they cannot have widget children\(emthey may only +be used as leaves of the widget tree. These widgets display information or +take user input. +</para> + +<variablelist> + <varlistentry> + <term><function>Command</function></term> + <listitem> + <para> +A push button that, when selected, may cause a specific action +to take place. This widget can display a multi-line string or a bitmap or pixmap image. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>Grip</function></term> + <listitem> + <para> +A rectangle that, when selected, will cause an action to take place. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>Label</function></term> + <listitem> + <para> +A rectangle that can display a multi-line string or a bitmap or pixmap image. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>List</function></term> + <listitem> + <para> +A list of text strings presented in row column format that may be +individually selected. When an element is selected an action may take +place. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>Panner</function></term> + <listitem> + <para> +A rectangular area containing a <emphasis remap='I'>slider</emphasis> that may be moved in two +dimensions. Notification of movement may be continuous or discrete. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>Repeater</function></term> + <listitem> + <para> +A push button that triggers an action at an increasing rate when selected. +This widget can display a multi-line string or a bitmap or pixmap image. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>Scrollbar</function></term> + <listitem> + <para> +A rectangular area containing a <emphasis remap='I'>thumb</emphasis> that when slid along one +dimension may cause a specific action to take place. The Scrollbar may +be oriented horizontally or vertically. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>Simple</function></term> + <listitem> + <para> +The base class for most of the simple widgets. Provides a rectangular +area with a settable mouse cursor and special border. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>StripChart</function></term> + <listitem> + <para> +A real time data graph that will automatically update and scroll. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><function>Toggle</function></term> + <listitem> + <para> +A push button that contains state information. Toggles +may also be used as "radio buttons" to implement a "one of many" or +"zero or one of many" group +of buttons. This widget can display a multi-line string or a bitmap or pixmap image. + </para> + </listitem> + </varlistentry> +</variablelist> +<!-- End of CH3.Intr --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Command.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Grip.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Label.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="List.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Panner.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Repeater.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Scrollbar.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Simple.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="StripChart.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Toggle.xml"/> +</chapter> diff --git a/libXaw/specs/CH4.xml b/libXaw/specs/CH4.xml new file mode 100644 index 000000000..00c89f78e --- /dev/null +++ b/libXaw/specs/CH4.xml @@ -0,0 +1,102 @@ +<chapter id="menus"> +<title>Menus</title> +<para> +The Athena widget set provides support for single paned non-hierarchical +popup and pulldown menus. Since menus are such a common user interface +tool, support for them must be provided in even the most basic widget +sets. In menuing as in other areas, the Athena Widget Set provides only +basic functionality. +</para> +<para> +Menus in the Athena widget set are implemented as a menu container (the +SimpleMenu widget) and a collection of objects that comprise the +menu entries. The SimpleMenu widget is itself a direct subclass of the +OverrideShell widget class, so no other shell is necessary when +creating a menu. The managed children of a SimpleMenu must be +subclasses of the Sme (Simple Menu Entry) object. +</para> +<para> +The Athena widget set provides three classes of Sme objects that may be +used to build menus. +</para> +<para> +<variablelist> + <varlistentry> + <term>Sme</term> + <listitem> + <para> +The base class of all menu entries. It may be used as a menu entry +itself to provide blank space in a menu. "Sme" means "Simple Menu +Entry." + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SmeBSB</term> + <listitem> + <para> +This menu entry provides a selectable entry containing a text string. +A bitmap may also be placed in the left and right margins. "BSB" means +"Bitmap String Bitmap." + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>SmeLine</term> + <listitem> + <para> +This menu entry provides an unselectable entry containing a separator line. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +The SimpleMenu widget informs the window manager that it should ignore +its window by setting the <function>Override Redirect</function> flag. This is the +correct behavior for the press-drag-release style of menu operation. If +click-move-click or "pinable" menus are desired it is the +responsibility of the application programmer, using the SimpleMenu +resources, to inform the window manager of the menu. +</para> +<para> +To allow easy creation of pulldown menus, a MenuButton widget is +also provided as part of the Athena widget set. +</para> +<sect1 id="Using_the_Menus"> +<title>Using the Menus</title> +<!-- .XS --> +<!-- Using the Menus --> +<!-- .XE --> +<!-- .IN "Menus" "using" --> +<para> +<!-- .LP --> +The default configuration for the menus is press-drag-release. +The menus will typically be +activated by clicking a pointer button while the pointer is over a +MenuButton, causing the menu to appear in a fixed location relative to +that button; this is a <function>pulldown</function> menu. Menus may also be activated +<!-- .IN "Menus" "pulldown" --> +when a specific pointer and/or key sequence is used anywhere in the +application; this is a <function>popup</function> menu (e.g. clicking Ctrl-<pointer +<!-- .IN "Menus" "popup" --> +button 1> in the common application <function>xterm</function>). In this +case the menu should be positioned under +the cursor. Typically menus will be placed so the pointer cursor is on +the first menu entry, or the last entry selected by the user. +</para> +<para> +<!-- .LP --> +The menu remains on the screen as long as the pointer button is held +down. Moving the pointer will highlight different menu items. +If the pointer leaves the menu, or moves over an entry that cannot +be selected then no menu entry will highlighted. When the desired menu +entry has been highlighted, releasing the pointer button removes the menu, +and causes any mechanism associated with this entry to be invoked. + +</para> +</sect1> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Sme.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SmeBSB.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SmeLine.xml"/> +</chapter> diff --git a/libXaw/specs/CH5.xml b/libXaw/specs/CH5.xml new file mode 100644 index 000000000..eb3f2fb3e --- /dev/null +++ b/libXaw/specs/CH5.xml @@ -0,0 +1,397 @@ +<chapter id="text_widgets"> +<title>Text Widgets</title> + +<para> +The Text widget provides a window that will allow an application +to display and edit one or more lines of text. Options are provided to +allow the user to add Scrollbars to its window, search for a specific +string, and modify the text in the buffer. +</para> +<para> +The Text widget is made up of a number of pieces; it was modularized to +ease customization. The AsciiText widget class (actually not limited to +ASCII but so named for compatibility) is be general enough to most +needs. If more flexibility, special features, or extra functionality is +needed, they can be added by implementing a new TextSource or TextSink, or +by subclassing the Text Widget (See Section 5.8 for customization +details.) <!-- xref --> +</para> +<para> +The words <emphasis remap='I'>insertion point</emphasis> are used in this chapter to refer to the text +caret. This is the symbol that is displayed between two characters in +the file. The insertion point marks the location where any new characters +will be added to the file. To avoid confusion the pointer cursor will +always be referred to as the <emphasis remap='I'>pointer</emphasis>. +</para> +<para> +The text widget supports three edit modes, controlling the types of +modifications a user is allowed to make: +</para> +<para> +<itemizedlist> + <listitem><para>Append-only</para></listitem> + <listitem><para>Editable</para></listitem> + <listitem><para>Read-only</para></listitem> +</itemizedlist> +</para> +<para> +Read-only mode does not allow the user or the programmer to modify the text +in the widget. While the entire string may be reset in +read-only mode with <function>XtSetValues</function>, it cannot be modified via +with <function>XawTextReplace</function>. Append-only and editable modes allow +the text at the insertion point to be modified. The only difference is +that text may only be added to or removed from the end of a buffer in +append-only mode. +</para> +<sect1 id="Text_Widget_for_Users"> +<title>Text Widget for Users</title> +<!-- .IN "Text widget" "User's Guide to the Text widget" --> +<!-- .XS --> +<!-- Text Widget for Users --> +<!-- .XE --> +<para> +<!-- .LP --> +The Text widget provides many of the common keyboard editing commands. +These commands allow users to move around and edit the buffer. If an +illegal operation is attempted, (such as deleting characters in a +read-only text widget), the X server will beep. +</para> +<sect2 id="Default_Key_Bindings"> +<title>Default Key Bindings</title> +<!-- .IN "Text widget" "default key bindings" --> +<para> +<!-- .LP --> +The default key bindings are patterned after those in the EMACS text editor: +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA 1.0i 3.0i 4.5i --> +<!-- .ta 1.0i 3.0i 4.5i --> +Ctrl-a Beginning Of Line Meta-b Backward Word +Ctrl-b Backward Character Meta-f Forward Word +Ctrl-d Delete Next Character Meta-i Insert File +Ctrl-e End Of Line Meta-k Kill To End Of Paragraph +Ctrl-f Forward Character Meta-q Form Paragraph +Ctrl-g Multiply Reset Meta-v Previous Page +Ctrl-h Delete Previous Character Meta-y Insert Current Selection +Ctrl-j Newline And Indent Meta-z Scroll One Line Down +Ctrl-k Kill To End Of Line Meta-d Delete Next Word +Ctrl-l Redraw Display Meta-D Kill Word +Ctrl-m Newline Meta-h Delete Previous Word +Ctrl-n Next Line Meta-H Backward Kill Word +Ctrl-o Newline And Backup Meta-< Beginning Of File +Ctrl-p Previous Line Meta-> End Of File +Ctrl-r Search/Replace Backward Meta-] Forward Paragraph +Ctrl-s Search/Replace Forward Meta-[ Backward Paragraph +Ctrl-t Transpose Characters +Ctrl-u Multiply by 4 Meta-Delete Delete Previous Word +Ctrl-v Next Page Meta-Shift Delete Kill Previous Word +Ctrl-w Kill Selection Meta-Backspace Delete Previous Word +Ctrl-y Unkill Meta-Shift Backspace Kill Previous Word +Ctrl-z Scroll One Line Up +Ctrl-\\ Reconnect to input method +Kanji Reconnect to input method +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +In addition, the pointer may be used to cut and paste text: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.0i --> +<!-- .ta .5i 2.0i --> + Button 1 Down Start Selection + Button 1 Motion Adjust Selection + Button 1 Up End Selection (cut) + + Button 2 Down Insert Current Selection (paste) + + Button 3 Down Extend Current Selection + Button 3 Motion Adjust Selection + Button 3 Up End Selection (cut) + +</literallayout> +</para> +<para> +<!-- .LP --> +Since all of these key and pointer bindings are set through the +translations and resource manager, the user and the application +programmer can modify them by changing the Text widget's +<function>translations</function> resource. +<!-- .\" --> +</para> +</sect2> +<sect2 id="Search_and_Replace"> +<title>Search and Replace</title> +<!-- .IN "Text widget" "search" --> +<!-- .IN "Text widget" "query replace" --> +<para> +<!-- .LP --> +The Text widget provides a search popup that can be used to search for a +string within the current Text widget. The popup can be activated by +typing either <emphasis remap='I'>Control-r</emphasis> or <emphasis remap='I'>Control-s</emphasis>. If <emphasis remap='I'>Control-s</emphasis> is +used the search will be forward in the file from the current location of the +insertion point; if <emphasis remap='I'>Control-r</emphasis> is used the search will be backward. The +activated popup is placed under the pointer. It has a number of buttons +that allow both text searches and text replacements to be performed. +</para> +<para> +<!-- .LP --> +At the top of the search popup are two toggle buttons labeled +<emphasis remap='I'>backward</emphasis> and <emphasis remap='I'>forward</emphasis>. One of these buttons will always be +highlighted; this is the direction in which the search will be +performed. The user can change the direction at any time by clicking on +the appropriate button. +</para> +<para> +<!-- .LP --> +Directly under the buttons there are two text areas, one labeled +<emphasis remap='I'>Search for:</emphasis> and the other labeled <emphasis remap='I'>Replace with:</emphasis>. If this is +a read-only Text widget the <emphasis remap='I'>Replace with:</emphasis> field will be insensitive +and no replacements will be allowed. After each of these labels will be +a text field. This field will allow the user to enter a string to +search for and the string to replace it with. Only one of these text +fields will have a window border around it; this is the active text +field. Any key presses that occur when the focus in in the search popup +will be directed to the active text field. There are also a few special +key sequences: +<literallayout class="monospaced"> +<!-- .TA 1.75i --> +<!-- .ta 1.75i --> +<function>Carriage Return</function>: Execute the action, and pop down the search widget. +<function>Tab</function>: Execute the action, then move to the next field. +<function>Shift Carriage Return</function>: Execute the action, then move to the next field. +<function>Control-q Tab</function>: Enter a Tab into a text field. +<function>Control-c</function>: Pop down the search popup. +</literallayout> +</para> +<para> +<!-- .LP --> +Using these special key sequences should allow simple +searches without ever removing one's hands from the keyboard. +</para> +<para> +<!-- .LP --> +Near the bottom of the search popup is a row of buttons. These buttons +allow the same actions to to be performed as the key sequences, but the +buttons will leave the popup active. This can be quite useful if many +searches are being performed, as the popup will be left on the display. +Since the search popup is a transient window, it may be picked +up with the window manager and pulled off to the side for use +at a later time. +</para> +<variablelist> + <varlistentry> + <term>Search</term> + <listitem> + <para> +Search for the specified string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Replace</term> + <listitem> + <para> +Replace the currently highlighted string with the string in the +<emphasis remap='I'>Replace with</emphasis> text field, and move onto the next occurrence of the +<emphasis remap='I'>Search for</emphasis> text field. The functionality is commonly referred to as +query-replace. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ReplaceAll</term> + <listitem> + <para> +Replace all occurrences of the search string with the replace string from +the current insertion point position to the end (or beginning) of the +file. There is no key sequence to perform this action. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ReplaceAll</term> + <listitem> + <para> +Remove the search popup from the screen. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +<!-- .LP --> +Finally, when <function>international</function> resource is <function>true</function>, there may be a +pre-edit buffer below the button row, for composing input. Its presence +is determined by the X locale in use and the VendorShell's <function>preeditType</function> +resource. +</para> +<para> +<!-- .LP --> +The widget hierarchy for the search popup is show below, all widgets +are listed by class and instance name. +<!-- .sp --> +<!-- .nf --> +<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> +<literallayout class="monospaced"> +Text <name of Text widget> + TransientShell search + Form form + Label label1 + Label label2 + Toggle backwards + Toggle forwards + Label searchLabel + Text searchText + Label replaceLabel + Text replaceText + Command search + Command replaceOne + Command replaceAll + Command cancel +</literallayout> +<!-- .fi --> +</para> +</sect2> +<sect2 id="File_Insertion"> +<title>File Insertion</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "file insertion" --> +To insert a file into a text widget, type the key sequence <emphasis remap='I'>Meta-i</emphasis>, +which will activate the file insert popup. This popup will appear under +the pointer, and any text typed while the focus is in this popup will be +redirected to the text field used for the filename. When the desired +filename has been entered, click on <emphasis remap='I'>Insert File</emphasis>, or type +<emphasis remap='I'>Carriage Return</emphasis>. The named file will then be inserted in the text +widget beginning at the insertion point position. If an error occurs when +opening the file, an error message will be printed, prompting the user +to enter the filename again. The file insert may be aborted by clicking +on <emphasis remap='I'>Cancel</emphasis>. If <emphasis remap='I'>Meta-i</emphasis> is typed at a text widget that is +read-only, it will beep, as no file insertion is allowed. +</para> +<para> +<!-- .LP --> +The widget hierarchy for the file insert popup is show below; all widgets +are listed by class and instance name. +<!-- .sp --> +<!-- .nf --> +<!-- .ta .5i 1.0i 1.5i 2.0i 2.5i --> +<literallayout class="monospaced"> +Text <name of Text widget> + TransientShell insertFile + Form form + Label label + Text text + Command insert + Command cancel +</literallayout> +<!-- .fi --> +</para> +</sect2> +<sect2 id="Text_Selections_for_Users"> +<title>Text Selections for Users</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "Text Selections for Users" --> +The text widgets have a text selection mechanism that allows +the user to copy pieces of the text into the <function>PRIMARY</function> selection, +and paste +into the text widget some text that another application (or text +widget) has put in the <function>PRIMARY</function> selection. +</para> +<para> +<!-- .LP --> +One method of selecting text is to press pointer button 1 +on the beginning of the text to be selected, drag the pointer until all +of the desired text is highlighted, and then release the button to +activate the selection. Another method is to click pointer button 1 at +one end of the text to be selected, then click pointer button 3 at the +other end. +</para> +<para> +<!-- .LP --> +To modify a currently active selection, press pointer button 3 near +either the end of the selection that you want to +adjust. This end of the selection may be moved while holding down pointer +button 3. When the proper area has been highlighted release the pointer +button to activate the selection. +</para> +<para> +<!-- .LP --> +The selected text may now be pasted into another application, and +will remain active until some other client makes a selection. +To paste text that some other application has +put into the <function>PRIMARY</function> selection use pointer button 2. +First place the insertion point where you would like the text to be inserted, +then click and release pointer button 2. +</para> +<para> +<!-- .LP --> +Rapidly clicking pointer button 1 the following number of times will adjust +the selection as described. +<variablelist> + <varlistentry> + <term> + <function>Two</function> + </term> + <listitem> + <para> +Select the word under the pointer. A word boundary is defined by the +Text widget to be a Space, Tab, or Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Three</function> + </term> + <listitem> + <para> +Select the line under the pointer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Four</function> + </term> + <listitem> + <para> +Select the paragraph under the pointer. A paragraph boundary is +defined by the text widget as two Carriage Returns in a row with only +Spaces or Tabs between them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Five</function> + </term> + <listitem> + <para> +Select the entire text buffer. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +To unset the text selection, click pointer button 1 without moving it. +</para> +</sect2> +</sect1> + +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_text_widget_actions.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextActions_default_translation_bindings.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextFuncs.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextCustom.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Text.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSink.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TextSource.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSink.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiSource.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AsciiText.xml"/> +</chapter> diff --git a/libXaw/specs/CH6.xml b/libXaw/specs/CH6.xml new file mode 100644 index 000000000..e8009afb6 --- /dev/null +++ b/libXaw/specs/CH6.xml @@ -0,0 +1,117 @@ +<chapter id="composite_and_constraint_widgets"> +<title>Composite and Constraint Widgets</title> +<para> +These widgets may contain arbitrary widget children. They implement a +policy for the size and location of their children. +</para> +<para> +<variablelist> + <varlistentry> + <term>Box</term> + <listitem> + <para> +This widget will pack its children as tightly as possible in non-overlapping rows. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Dialog</term> + <listitem> + <para> +An implementation of a commonly used interaction semantic to prompt for +auxiliary input from the user, such as a filename. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Form</term> + <listitem> + <para> +A more sophisticated layout widget that allows the children to specify +their positions relative to the other children, or to the edges of the Form. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Paned</term> + <listitem> + <para> +Allows children to be tiled vertically or horizontally. Controls are +also provided to allow the user to dynamically resize the individual panes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Porthole</term> + <listitem> + <para> +Allows viewing of a managed child which is as large as, or larger than its +parent, typically under control of a Panner widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Tree</term> + <listitem> + <para> +Provides geometry management of widgets arranged in a directed, acyclic graph. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Viewport</term> + <listitem> + <para> +Consists of a frame, one or two scrollbars, and an inner window. The +inner window can contain all the data that is to be displayed. This inner +window will be clipped by the frame with the scrollbars controlling +which section of the inner window is currently visible. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<note> +<para> +<!-- .LP --> +The geometry management semantics provided by the X Toolkit give full +control of the size and position of a widget to the parent of that +widget. While the children are allowed to request a certain size or +location, it is the parent who makes the final decision. Many of the +composite widgets here will deny any geometry request from their +children by default. If a child widget is not getting the expected size +or location, it is most likely the parent disallowing a request, or +implementing semantics slightly different than those expected by the +application programmer. +</para> +<para> +<!-- .LP --> +If the application wishes to change the size or location of +any widget it should make a call to <function>XtSetValues</function>. This will +<!-- .IN "XtSetValues" "" --> +allow the widget to ask its parent for the new size or location. +As noted above the parent is allowed to refuse this request, +and the child must live with the result. If the +application is unable to achieve the desired semantics, then perhaps it +should use a different composite widget. Under no circumstances +should an application programmer resort to <function>XtMoveWidget</function> or +<!-- .IN "XtMoveWidget" "" --> +<function>XtResizeWidget</function>; these functions are exclusively for the use of +<!-- .IN "XtResizeWidget" "" --> +Composite widget implementors. +</para> +<para> +<!-- .LP --> +For more information on geometry management consult the <emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. +</para> +</note> + +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Box.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Dialog.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Form.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Paned.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Porthole.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Tree.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Viewport.xml"/> + +</chapter> diff --git a/libXaw/specs/CH7.xml b/libXaw/specs/CH7.xml new file mode 100644 index 000000000..4c491704b --- /dev/null +++ b/libXaw/specs/CH7.xml @@ -0,0 +1,167 @@ +<chapter id="creating_new_widgets__subclassing_"> +<title>Creating New Widgets (Subclassing)</title> +<para> +Although the task of creating a new widget may at first appear a little +daunting, there is a basic simple pattern that all widgets follow. The +Athena Widget library contains a special widget called the +<emphasis remap='I'>Template</emphasis> widget that is intended to assist +the novice widget programmer in writing a custom widget. +</para> +<para> +Reasons for wishing to write a custom widget include: +</para> +<itemizedlist> + <listitem> + <para> +Providing a graphical interface not currently supported by any existing +widget set. + </para> + </listitem> + <listitem> + <para> +Convenient access to resource management procedures to obtain fonts, +colors, etc., even if user customization is not desired. + </para> + </listitem> + <listitem> + <para> +Convenient access to user input dispatch and translation management procedures. + </para> + </listitem> + <listitem> + <para> +Access to callback mechanism for building higher-level application libraries. + </para> + </listitem> + <listitem> + <para> +Customizing the interface or behavior of an existing widget to suit a +special application need. + </para> + </listitem> + <listitem> + <para> +Desire to allow user customization of resources such as fonts, colors, +etc., or to allow convenient re-binding of keys and buttons to internal +functions. + </para> + </listitem> + <listitem> + <para> +Converting a non-Toolkit application to use the Toolkit. + </para> + </listitem> +</itemizedlist> + +<para> +In each of these cases, the operation needed to create a new widget is +to "subclass" an existing one. If the desired semantics of the new +widget are similar to an existing one, then the implementation of the +existing widget should be examined to see how much work would be +required to create a subclass that will then be +able to share the existing class methods. Much time will be saved in +writing the new widget if an existing widget class Expose, Resize and/or +GeometryManager method can be used by the subclass. +</para> +<para> +Note that some trivial uses of a ``bare-bones'' widget may be achieved by +simply creating an instance of the Core +widget. The class variable to use when creating a Core widget is +<function>widgetClass</function>. +The geometry of the Core widget is determined entirely by the parent +widget. +</para> +<para> +It is very often the case than an application will have a special need +for a certain set of functions and that many copies of these functions +will be needed. For example, when converting an older application to use +the Toolkit, it may be desirable to have a "Window Widget" class that +might have the following semantics: +</para> +<itemizedlist> + <listitem> + <para> +Allocate 2 drawing colors in addition to a background color. + </para> + </listitem> + <listitem> + <para> +Allocate a text font. + </para> + </listitem> + <listitem> + <para> +Execute an application-supplied function to handle exposure events. + </para> + </listitem> + <listitem> + <para> +Execute an application-supplied function to handle user input events. + </para> + </listitem> +</itemizedlist> +<para> +It is obvious that a completely general-purpose WindowWidgetClass could +be constructed that would export all class methods as callbacks lists, +but such a widget would be very large and would have to choose some +arbitrary number of resources such as colors to allocate. An application +that used many instances of the general-purpose widget would therefore +un-necessarily waste many resources. +</para> +<para> +In this section, an outline will be given of the procedure to follow to +construct a special-purpose widget to address the items listed above. +The reader should refer to the appropriate sections of the +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis> +for complete details of the material outlined here. Section 1.4 of +the <emphasis remap='I'>Intrinsics</emphasis> should be read in +conjunction with this section. +</para> +<para> +All Athena widgets have three separate files associated with them: +</para> +<itemizedlist> + <listitem> + <para> +A "public" header file containing declarations needed by applications programmers + </para> + </listitem> + <listitem> + <para> +A "private" header file containing additional declarations needed by the +widget and any subclasses + </para> + </listitem> + <listitem> + <para> +A source code file containing the implementation of the widget + </para> + </listitem> +</itemizedlist> + +<para> +This separation of functions into three files is suggested for all +widgets, but nothing in the Toolkit actually requires this format. In +particular, a private widget created for a single application may easily +combine the "public" and "private" header files into a single file, or +merge the contents into another application header file. Similarly, the +widget implementation can be merged into other application code. +</para> + +<para> +In the following example, the public header file +<function>< X11/Xaw/Template.h ></function>, +the private header file +<function>< X11/Xaw/TemplateP.h ></function> +and the source code file +<function>< X11/Xaw/Template.c ></function> +will be modified to produce the "WindowWidget" described above. +In each case, the files have been designed so that a global string +replacement of "Template" and "template" +with the name of your new widget, using +the appropriate case, can be done. +</para> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_public_header_file.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_private_header_file.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template_widget_source_file.xml"/> +</chapter> 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> diff --git a/libXaw/specs/Dialog.xml b/libXaw/specs/Dialog.xml new file mode 100644 index 000000000..f77006c6a --- /dev/null +++ b/libXaw/specs/Dialog.xml @@ -0,0 +1,692 @@ +<sect1 id="Dialog_Widget"> +<title>Dialog Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Dialog Widget --> +<!-- .XE --> +<!-- .IN "Dialog widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Dialog.h> +<!-- .IN "Dialog.h" "" --> +Class Header file <X11/Xaw/DialogP.h> +<!-- .IN "DialogP.h" "" --> +Class dialogWidgetClass +<!-- .IN "dialogWidgetClass" "" --> +Class Name Dialog +<!-- .IN "Dialog widget" "class name" --> +Superclass Form +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Dialog widget implements a commonly used interaction semantic to +prompt for auxiliary input from a user. For example, you can use a +Dialog widget when an application requires a small piece of information, +such as a filename, from the user. A Dialog widget, which is simply a +special case of the Form widget, provides a convenient way to create a +preconfigured form. +</para> +<para> +<!-- .LP --> +The typical Dialog widget contains three areas. The first line +contains a description of the function of the Dialog widget, for +example, the string <emphasis remap='I'>Filename:</emphasis>. The second line contains an area +into which the user types input. The third line can contain buttons +that let the user confirm or cancel the Dialog input. Any of these +areas may be omitted by the application. +</para> +<sect2 id="dialog_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Dialog widget instance, the following resources are +retrieved from the argument list or the resource database: +<!-- .IN "Dialog 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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>defaultDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry>4</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>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</entry> + </row> + <row> + <entry>icon</entry> + <entry>Icon</entry> + <entry>Bitmap</entry> + <entry></entry> + <entry>None</entry> + </row> + <row> + <entry>label</entry> + <entry>Label</entry> + <entry>String</entry> + <entry></entry> + <entry>"label"</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>value</entry> + <entry>Value</entry> + <entry>String</entry> + <entry></entry> + <entry>no value widget</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dd --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<variablelist> + <varlistentry> + <term> + <function>icon</function> + </term> + <listitem> + <para> +A pixmap image to be displayed immediately to the left of the +Dialog widget's label. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>label</function> + </term> + <listitem> + <para> +A string to be displayed at the top of the Dialog widget. +<!-- .Mm --> +<!-- .Nc --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>value</function> + </term> + <listitem> + <para> +An initial value for the string field that the user will enter text +into. By default, no text entry field is available to the user. +Specifying an initial value for <function>value</function> activates the text entry +field. If string input is desired, but no initial value is to be +specified then set this resource to "" (empty string). +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Constraint_Resources"> +<title>Constraint Resources</title> +<para> +<!-- .LP --> +<!-- .IN "Dialog widget" "constraint resources" --> +Each child of the Dialog widget may request special layout resources +be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Dialog +widget's children to specify individual layout requirements. +</para> +<para> +<!-- .LP --> +<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>bottom</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>fromHoriz</entry> + <entry>Widget</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL (left edge of Dialog)</entry> + </row> + <row> + <entry>fromVert</entry> + <entry>Widget</entry> + <entry>Widget </entry> + <entry></entry> + <entry>NULL (top edge of Dialog)</entry> + </row> + <row> + <entry>horizDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + <row> + <entry>left</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>resizable</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>FALSE</entry> + </row> + <row> + <entry>right</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>top</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>vertDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<literallayout class="monospaced"> +bottom +left +right +top What to do with this edge of the child when + the parent is resized. This resource may be + any edgeType. See Layout Semantics for + details. + +fromHoriz +fromVert Which widget this child should be placed + underneath (or to the right of). If a value + of NULL is specified then this widget will be + positioned relative to the edge of the par- + ent. + +horizDistance +vertDistance The amount of space, in pixels, between this + child and its left or upper neighbor. + +resizable If this resource is False then the parent + widget will ignore all geometry request made + by this child. The parent may still resize + this child itself, however. +</literallayout> +<!-- .Bt --> +<!-- .Fh --> +<!-- .Hd --> +<!-- .Rl --> +</para> +</sect2> +<sect2 id="dialog_layout_semantics"> +<title>Layout Semantics</title> +<!-- .IN "Dialog widget" "layout semantics" --> +<para> +The Dialog widget uses two different sets of layout seman- +tics. One is used when initially laying out the children. +The other is used when the Dialog is resized. +</para> +<para> +The first layout method uses the <function>fromVert</function> mand <function>fromHoriz</function> +resources to place the children of the Dialog. A single +pass is made through the Dialog widget's children in the +order that they were created. Each child is then placed in +the Dialog widget below or to the right of the widget speci- +fied by the <function>fromVert</function> mand <function>fromHoriz</function> mresources. The distance +the new child is placed from its left or upper neighbor is +determined by the <function>horizDistance</function> mand <function>vertDistance</function> mresources. +This implies some things about how the order of creation +affects the possible placement of the children. The Form +widget registers a string to widget converter which does not +postpone conversion and does not cache conversion results. +</para> +<para> + +The second layout method is used when the Dialog is resized. +It does not matter what causes this resize, and it is possi- +ble for a resize to happen before the widget becomes visible +(due to constraints imposed by the parent of the Dialog). +This layout method uses the <function>bottom</function> , +<function>top</function> , <function>left</function> , and +<function>right</function> +resources. These resources are used to determine what will +happen to each edge of the child when the Dialog is resized. +If a value of <function>XawChain</function> +<emphasis remap='I'><something></emphasis> + is specified, the the edge +of the child will remain a fixed distance from the <emphasis remap='I'>chain</emphasis> +edge of the Dialog. For example if <function>XawChainLeft</function> +mis specified for the <function>right</function> mresource of a child +then the right edge +of that child will remain a fixed distance from the left +edge of the Dialog widget. If a value of <function>XawRubber</function> mis spec- +ified, that edge will grow by the same percentage that the +Dialog grew. For instance if the Dialog grows by 50% the +left edge of the child (if specified as <function>XawRubber</function> mwill be +50% farther from the left edge of the Dialog). One must be +very careful when specifying these resources, for when they +are specified incorrectly children may overlap or completely +occlude other children when the Dialog widget is resized. +</para> + +<para> +<!-- .LP --> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Edge Type</entry> + <entry>Resource Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>XawChainBottom</entry> + <entry>ChainBottom</entry> + <entry>Edge remains a fixed distance from bottom of Dialog</entry> + </row> + <row> + <entry>XawChainLeft</entry> + <entry>ChainLeft</entry> + <entry>Edge remains a fixed distance from left of Dialog</entry> + </row> + <row> + <entry>XawChainRight</entry> + <entry>ChainRight</entry> + <entry>Edge remains a fixed distance from right of Dialog</entry> + </row> + <row> + <entry>XawChainTop</entry> + <entry>ChainTop</entry> + <entry>Edge remains a fixed distance from top of Dialog</entry> + </row> + <row> + <entry>XawRubber</entry> + <entry>Rubber</entry> + <entry>Edges will move a proportional distance</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<sect3 id="Example"> +<title>Example</title> +<para> +<!-- .LP --> +If you wish to force the Dialog to never resize one or more of its children +then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and +<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause +the child to remain a fixed distance from the top and left +edges of the Dialog, and to never resize. +</para> +</sect3> +<sect3 id="Special_Considerations"> +<title>Special Considerations</title> +<!-- .IN "Dialog widget" "special considerations" --> +<para> +<!-- .LP --> +The Dialog widget automatically sets the <function>top</function> and <function>bottom</function> +resources for all Children that are subclasses of the Command widget, +as well as the widget children that are used to contain the <function>label</function>, +<function>value</function>, and <function>icon</function>. This policy allows the buttons at the +bottom of the Dialog to interact correctly with the predefined children, +and makes it possible for a client to simply create and manage a new +Command button without having to specify its constraints. +</para> +<para> +<!-- .LP --> +The Dialog will also set <function>fromLeft</function> to the last button in the +<!-- .IN "fromLeft" "" --> +Dialog for each new button added to the Dialog widget. +</para> +<para> +<!-- .LP --> +The automatically added constraints cannot be overridden, as they are +policy decisions of the Dialog widget. If a more flexible Dialog is +desired, the application is free to use the Form widget to create its +own Dialog policy. +</para> +</sect3> +</sect2> +<sect2 id="Automatically_Created_Children_"> +<title>Automatically Created Children.</title> +<!-- .IN "Dialog widget" "automatically created children" --> +<para> +<!-- .LP --> +The Dialog uses Label widgets to contain the <function>label</function> and <function>icon</function>. +These widgets are named <emphasis remap='I'>label</emphasis> and <emphasis remap='I'>icon</emphasis> respectively. The +Dialog <function>value</function> is contained in an AsciiText widget whose name is +<function>value</function>. Using <function>XtNameToWidget</function> the application can change +<!-- .IN "XtNameToWidget" "" --> +those resources associated with each of these widgets that are not +available through the Dialog widget itself. +</para> +<para> +<!-- .LP --> +</para> +</sect2> +<sect2 id="dialog_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .LP --> +To return the character string in the text field, use +<!-- .PN XawDialogGetValueString . --> +<!-- .IN "XawDialogGetValueString" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>String<function> XawDialogGetValueString</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Dialog widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns a copy of the value string of the Dialog +widget. This string is allocated by the AsciiText widget and will +remain valid and unchanged until another call to +<function>XawDialogGetValueString</function> or an <function>XtGetValues</function> call on the +<function>value</function> widget, when the string will be automatically freed, and +a new string is returned. This string may be freed earlier by calling +the function <function>XawAsciiSourceFreeString</function>. +<!-- .IN "XawAsciiSourceFreeString" "" --> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add a new button to the Dialog widget use +<function>XawDialogAddButton</function>. +<!-- .IN "XawDialogAddButton" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawDialogAddButton</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String<parameter> name</parameter></paramdef> + <paramdef>XtCallbackProc<parameter> func</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Dialog widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the new Command button to be added to the Dialog. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>func</emphasis> + </term> + <listitem> + <para> +Specifies a callback function to be called when this button is activated. If +NULL is specified then no callback is added. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the client_data to be passed to the <emphasis remap='I'>func</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function is merely a shorthand for the code sequence: +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .SM --> +<!-- .TA 1i 2i --> +<!-- .ta 1i 2i --> +{ + Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO); + XtAddCallback(button, XtNcallback, func, client_data); +} +<!-- .NL --> +</literallayout> +<!-- .sp --> + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Form.xml b/libXaw/specs/Form.xml new file mode 100644 index 000000000..13cc36a5a --- /dev/null +++ b/libXaw/specs/Form.xml @@ -0,0 +1,531 @@ +<sect1 id="Form_Widget"> +<title>Form Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Form Widget --> +<!-- .XE --> +<!-- .IN "Form widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Form.h> +<!-- .IN "Form.h" "" --> +Class Header file <X11/Xaw/FormP.h> +<!-- .IN "FormP.h" "" --> +Class formWidgetClass +<!-- .IN "formWidgetClass" "" --> +Class Name Form +<!-- .IN "Form widget" "class name" --> +Superclass Constraint +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Form widget can contain an arbitrary number of children or +subwidgets. The Form provides geometry management for its children, +which allows individual control of the position of each child. Any +combination of children can be added to a Form. The initial positions +of the children may be computed relative to the positions of previously +created children. When the Form is resized, it computes new positions and +sizes for its children. This computation is based upon information +provided when a child is added to the Form. +</para> +<para> +<!-- .LP --> +The default width of the Form is the minimum width needed to +enclose the children after computing their initial layout, with a +margin of <function>defaultDistance</function> +at the right and bottom edges. If a width and height is assigned +to the Form that is too small for the layout, the children will +be clipped by the right and bottom edges of the Form. +</para> +<sect2 id="form_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Form widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Form 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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>defaultDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry>4</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>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain all children</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dd Bold --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<!-- .Mm --> +<!-- .Nc --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> +</para> +</sect2> +<sect2 id="form_constraint_resources"> +<title>Constraint Resources</title> +<para> +<!-- .LP --> +<!-- .IN "Form widget" "constraint resources" --> +Each child of the Form widget may request special layout resources +be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Form +widget's children to specify individual layout requirements. +</para> +<para> +<!-- .LP --> +</para> +<para> +<!-- .LP --> +<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>bottom</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>fromHoriz</entry> + <entry>Widget</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL (left edge of Form)</entry> + </row> + <row> + <entry>fromVert</entry> + <entry>Widget</entry> + <entry>Widget </entry> + <entry></entry> + <entry>NULL (top edge of Form)</entry> + </row> + <row> + <entry>horizDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + <row> + <entry>left</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>resizable</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>FALSE</entry> + </row> + <row> + <entry>right</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>top</entry> + <entry>Edge</entry> + <entry>XawEdgeType</entry> + <entry></entry> + <entry>XawRubber</entry> + </row> + <row> + <entry>vertDistance</entry> + <entry>Thickness</entry> + <entry>int</entry> + <entry></entry> + <entry><function>defaultDistance</function> resource</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Bt Bold --> +<!-- .Fh Bold --> +<!-- .Hd Bold --> +<!-- .Rl Bold --> +</para> +<literallayout class="monospaced"> +bottom +left +right +top What to do with this edge of the child when + the parent is resized. This resource may be + any edgeType. See Layout Semantics for + details. + +fromHoriz +fromVert Which widget this child should be placed + underneath (or to the right of). If a value + of NULL is specified then this widget will be + positioned relative to the edge of the par- + ent. + +horizDistance +vertDistance The amount of space, in pixels, between this + child and its left or upper neighbor. + +resizable If this resource is False then the parent + widget will ignore all geometry request made + by this child. The parent may still resize + this child itself, however. +</literallayout> +<!-- .Bt --> +</sect2> +<sect2 id="form_layout_semantics"> +<title>Layout Semantics</title> +<para> +The Form widget uses two different sets of layout semantics. +One is used when initially laying out the children. The +other is used when the Form is resized. +</para> +<para> +The first layout method uses the <function>fromVert</function> +and <function>fromHoriz</function> +resources to place the children of the Form. A single pass +is made through the Form widget's children in the order that +they were created. Each child is then placed in the Form +widget below or to the right of the widget specified by the +<function>fromVert</function> and <function>fromHoriz</function> +resources. The distance the new +child is placed from its left or upper neighbor is deter- +mined by the <function>horizDistance</function> and +<function>vertDistance</function> resources. This +implies some things about how the order of creation affects +the possible placement of the children. The Form widget +registers a string to widget converter which does not post- +pone conversion and does not cache conversion results. +</para> +<para> +The second layout method is used when the Form is resized. +It does not matter what causes this resize, and it is possi- +ble for a resize to happen before the widget becomes visible +(due to constraints imposed by the parent of the Form). +This layout method uses the <function>bottom</function>, +<function>top</function>, <function>left</function>, and +<function>right</function> +resources. These resources are used to determine what will +happen to each edge of the child when the Form is resized. +If a value of <function>XawChain</function> +<<emphasis remap='I'>something</emphasis>> is specified, the the edge +of the child will remain a fixed distance from the +<emphasis remap='I'>chain</emphasis> +edge of the Form. For example if <function>XawChainLeft</function> is specified +for the <function>right</function> resource of a child then the right edge of +that child will remain a fixed distance from the left edge +of the Form widget. If a value of <function>XawRubber</function> is specified, +that edge will grow by the same percentage that the Form +grew. For instance if the Form grows by 50% the left edge +of the child (if specified as <function>XawRubber</function> will be 50% farther +from the left edge of the Form). One must be very careful +when specifying these resources, for when they are specified +incorrectly children may overlap or completely occlude other +children when the Form widget is resized. +<!-- .LP --> +<!-- .Lt Form --> +</para> +<para> +<!-- .LP --> +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Edge Type</entry> + <entry>Resource Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>XawChainBottom</entry> + <entry>ChainBottom</entry> + <entry>Edge remains a fixed distance from bottom of Form</entry> + </row> + <row> + <entry>XawChainLeft</entry> + <entry>ChainLeft</entry> + <entry>Edge remains a fixed distance from left of Form</entry> + </row> + <row> + <entry>XawChainRight</entry> + <entry>ChainRight</entry> + <entry>Edge remains a fixed distance from right of Form</entry> + </row> + <row> + <entry>XawChainTop</entry> + <entry>ChainTop</entry> + <entry>Edge remains a fixed distance from top of Form</entry> + </row> + <row> + <entry>XawRubber</entry> + <entry>Rubber</entry> + <entry>Edges will move a proportional distance</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<sect3 id="form_example"> +<title>Example</title> +<para> +<!-- .LP --> +If you wish to force the Form to never resize one or more of its +children, then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and +<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause the +child to remain a fixed distance from the top and left edges of the +Form, and never to resize. +</para> +</sect3> +</sect2> +<sect2 id="form_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .LP --> +To force or defer a re-layout of the Form, use +<!-- .PN XawFormDoLayout . --> +<!-- .IN "Form widget" "re-layout" --> +<!-- .IN "XawFormDoLayout" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawFormDoLayout</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> do_layout</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Form widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>do_layout</emphasis> + </term> + <listitem> + <para> +Specifies whether the layout of the Form widget is enabled (<function>True</function>) +or disabled (<function>False</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When making several changes to the children of a Form widget +after the Form has been realized, it is a good idea to disable +relayout until after all changes have been made. + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Grip.xml b/libXaw/specs/Grip.xml new file mode 100644 index 000000000..4e49d5ba0 --- /dev/null +++ b/libXaw/specs/Grip.xml @@ -0,0 +1,357 @@ +<sect1 id="Grip_Widget"> +<title>Grip Widget</title> +<!-- .XS --> +<!-- Grip Widget --> +<!-- .XE --> +<!-- .IN "Grip widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application header file <X11/Xaw/Grip.h> +<!-- .IN "Grip.h" "" --> +Class header file <X11/Xaw/GripP.h> +<!-- .IN "GripP.h" "" --> +Class gripWidgetClass +<!-- .IN "gripWidgetClass" "" --> +Class Name Grip +<!-- .IN "Grip widget" "class name" --> +Superclass Simple +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +The Grip widget provides a small rectangular region in which user input +events (such as ButtonPress or ButtonRelease) may be handled. The most +common use for the Grip widget is as an attachment point for visually +repositioning an object, such as the pane border in a Paned widget. +</para> +<sect2 id="grip_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Grip widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Grip 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>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>0</entry> + </row> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>Callback</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>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>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></entry> + <entry>8</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</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>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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>8</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> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<variablelist> + <varlistentry> + <term> + <function>callback</function> + </term> + <listitem> + <para> +All routines on this list are called whenever the <function>GripAction</function> +action routine is invoked. The <emphasis remap='I'>call_data</emphasis> contains all +information passed to the action routine. A detailed description +is given below in the <function>Grip Actions</function> section. +<!-- .Cm --> +<!-- .Cu --> +<!-- .Cn --> +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>foreground</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +used to flood fill the entire Grip widget. +<!-- .Hw --> +<!-- .Ib --> +<!-- .Ix --> +<!-- .Mm --> +<!-- .Pf --> +<!-- .Pb --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Grip_Actions"> +<title>Grip Actions</title> +<!-- .IN "Grip widget" "actions" --> +<para> +<!-- .LP --> +The Grip widget does not declare any default event translation bindings, +but it does declare a single action routine named <function>GripAction</function>. The +<!-- .IN "Grip widget" "GripAction routine" --> +client specifies an arbitrary event translation table, optionally giving +parameters to the <function>GripAction</function> routine. +</para> +<para> +<!-- .LP --> +The <function>GripAction</function> routine executes the callbacks on the +<function>callback</function> list, passing as <function>call_data</function> a pointer to a +<function>XawGripCallData</function> structure, defined in the Grip widget's application +header file. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> +<!-- .IN "XawGripCallData" "" "@DEF@" --> +<!-- .IN "XawGripCallDataRec" "" "@DEF@" --> +<!-- .sp --> +typedef struct _XawGripCallData { + XEvent *event; + String *params; + Cardinal num_params; +} XawGripCallDataRec, *XawGripCallData, + GripCallDataRec, *GripCallData; /* supported for R4 compatibility */ +<!-- .IN "XawGripCallDataRec" "" --> +<!-- .IN "XawGripCallData" "" --> +<!-- .IN "GripCallData" "" --> +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +In this structure, the <emphasis remap='I'>event</emphasis> is a pointer to the input event that +triggered the action. <emphasis remap='I'>params</emphasis> and <emphasis remap='I'>num_params</emphasis> give the string +parameters specified in the translation table for the particular event +binding. +<!-- .IN "Grip widget" "GripAction table" --> +</para> +<para> +<!-- .LP --> +The following is an example of a translation table that uses the GripAction: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> +<!-- .sp --> + <Btn1Down>: GripAction(press) + <Btn1Motion>: GripAction(move) + <Btn1Up>: GripAction(release) +<!-- .sp --> +</literallayout> +For a complete description of the format of translation tables, see the +<emphasis remap='I'>X Toolkit Intrinsics - C Language Interface</emphasis>. + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Label.xml b/libXaw/specs/Label.xml new file mode 100644 index 000000000..68962b5bd --- /dev/null +++ b/libXaw/specs/Label.xml @@ -0,0 +1,345 @@ +<sect1 id="Label_Widget"> +<title>Label Widget</title> +<!-- .XS --> +<!-- Label Widget --> +<!-- .XE --> +<!-- .IN "Label widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application header file <X11/Xaw/Label.h> +<!-- .IN "Label.h" "" --> +Class header file <X11/Xaw/LabelP.h> +<!-- .IN "LabelP.h" "" --> +Class labelWidgetClass +<!-- .IN "labelWidgetClass" "" --> +Class Name Label +<!-- .IN "Label widget" "class name" --> +Superclass Simple +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +A Label widget holds a graphic displayed within a +rectangular region of the screen. The graphic may be a +text string containing multiple lines of characters in an +8 bit or 16 bit character set (to be displayed with a +<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with a +<emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or +pixmap. The Label widget will allow its graphic to be +left, right, or center justified. Normally, this widget +can be neither selected nor directly edited by the user. +It is intended for use as an output device only. +</para> +<sect2 id="label_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Label widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Label 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>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</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>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>See above</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> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bm Bold --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Cm --> +<!-- .Cu --> +<!-- .Cn --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Le Bold --> +<!-- .Lf Bold --> +<!-- .Ls Bold --> +<!-- .Lg Bold --> +<!-- .Hw --> +<!-- .Ib --> +<!-- .Ih Bold --> +<!-- .In --> +<!-- .Ju Bold --> +<!-- .La Bold --> +<!-- .Ll Bold --> +<!-- .Mm --> +<!-- .Pf --> +<!-- .Pb --> +<!-- .Re Bold --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/List.xml b/libXaw/specs/List.xml new file mode 100644 index 000000000..0bad43dde --- /dev/null +++ b/libXaw/specs/List.xml @@ -0,0 +1,872 @@ +<sect1 id="List_Widget"> +<title>List Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- List Widget --> +<!-- .XE --> +<!-- .IN "List widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application header file <X11/Xaw/List.h> +<!-- .IN "List.h" "" --> +Class header file <X11/Xaw/ListP.h> +<!-- .IN "ListP.h" "" --> +Class listWidgetClass +<!-- .IN "listWidgetClass" "" --> +Class Name List +<!-- .IN "List widget" "class name" --> +Superclass Simple +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> + +The List widget contains a list of strings formatted into rows and +columns. When one of the strings is selected, it is highlighted, and the +List widget's <function>Notify</function> action is invoked, calling all routines on +its callback list. Only one string may be selected at a time. +</para> +<sect2 id="list_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a List widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "List 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>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>Callback</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>columnSpacing</entry> + <entry>Spacing</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>6</entry> + </row> + <row> + <entry>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_left_ptr</entry> + </row> + <row> + <entry>cursorName</entry> + <entry>Cursor</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>defaultColumns</entry> + <entry>Columns</entry> + <entry>int</entry> + <entry></entry> + <entry>2</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>font</entry> + <entry>Font</entry> + <entry>FontStruct</entry> + <entry></entry> + <entry>XtDefaultFont</entry> + </row> + <row> + <entry>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</entry> + </row> + <row> + <entry>forceColumns</entry> + <entry>Columns</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>Enough space to contain the list</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>list</entry> + <entry>List</entry> + <entry>Pointer</entry> + <entry></entry> + <entry>name of widget</entry> + </row> + <row> + <entry>longest</entry> + <entry>Longest</entry> + <entry>int</entry> + <entry>A</entry> + <entry>0</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numberStrings</entry> + <entry>NumberStrings</entry> + <entry>int</entry> + <entry>A</entry> + <entry>computed for NULL terminated list</entry> + </row> + <row> + <entry>pasteBuffer</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>rowSpacing</entry> + <entry>Spacing</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>2</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>See below</entry> + </row> + <row> + <entry>verticalList</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Enough space to contain the list</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<variablelist> + <varlistentry> + <term> + <function>callback</function> + </term> + <listitem> + <para> +All functions on this list are called whenever the <function>notify</function> action is +invoked. The <emphasis remap='I'>call_data</emphasis> argument contains information about the element +selected and is described in detail in the <function>List Callbacks</function> section. +<!-- .Cm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>columnSpacing</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>rowSpacing</function> + </term> + <listitem> + <para> +The amount of space, in pixels, between each of the rows and columns +in the list. +<!-- .Cu --> +<!-- .Cn --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>defaultColumns</function> + </term> + <listitem> + <para> +The default number of columns. This value is used when neither the +width nor the height of the List widget is specified or when +<function>forceColumns</function> is <function>True</function>. +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>font</function> + </term> + <listitem> + <para> +The text font to use when displaying the <function>list</function>, when the +<function>international</function> resource is <function>false</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>fontSet</function> + </term> + <listitem> + <para> +The text font set to use when displaying the <function>list</function>, when the +<function>international</function> resource is <function>true</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>forceColumns</function> + </term> + <listitem> + <para> +Forces the default number of columns to be used regardless of the +List widget's current size. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>foreground</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +used to paint the text of the list elements. +<!-- .Hw --> +<!-- .Ib --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + \fPinternalHeight\fP + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + \fPinternalWidth\fP + </term> + <listitem> + <para> +The margin, in pixels, between the edges of the list and the +corresponding edge of the List widget's window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>list</function> + </term> + <listitem> + <para> +An array of text strings displayed in the List widget. If +<function>numberStrings</function> is zero (the default) then the <function>list</function> must be +NULL terminated. If a value is not specified for the <function>list</function>, then +<function>numberStrings</function> is set to 1, and the name of the widget is used as +the <function>list</function>, and <function>longest</function> is set to the length of the name of the +widget. The <function>list</function> is used in place, and must be available +to the List widget for the lifetime of this widget, or until it is +changed with <function>XtSetValues</function> or <function>XawListChange</function>. +<!-- .In --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>longest</function> + </term> + <listitem> + <para> +Specifies the width, in pixels, of the longest string in the current +list. The List widget will compute this value if zero (the default) +is specified. If this resource is set by hand, entries longer than this +will be clipped to fit. +<!-- .Mm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>numberStrings</function> + </term> + <listitem> + <para> +The number of strings in the current list. If a value of zero (the +default) is specified, the List widget will compute it. When computing +the number of strings the List widget assumes that the <function>list</function> is NULL +terminated. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>pasteBuffer</function> + </term> + <listitem> + <para> +If this resource is set to <function>True</function> then the name of the currently +selected list element will be put into <function>CUT_BUFFER_0</function>. +<!-- .Pf --> +<!-- .Pb --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>verticalList</function> + </term> + <listitem> + <para> +If this resource is set to <function>True</function> then the list elements will be +presented in column major order. +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="List_Actions"> +<title>List Actions</title> +<!-- .IN "List widget" "actions" --> +<para> +<!-- .LP --> +The List widget supports the following actions: +</para> +<itemizedlist> + <listitem> + <para> +Highlighting and unhighlighting the list element under the +pointer with <function>Set</function> and <function>Unset</function> + </para> + </listitem> + <listitem> + <para> +Processing application callbacks with <function>Notify</function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The following is the default translation table used by the List Widget: +<!-- .IN "List widget" "default translation table" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> +<Btn1Down>,<Btn1Up>: Set(\|) Notify(\|) +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The full list of actions supported by List widget is: +<variablelist> + <varlistentry> + <term> + <function>Set</function>(\|) + </term> + <listitem> + <para> +<emphasis remap='I'>Sets</emphasis> the list element that is currently under the pointer. To +inform the user that this element is currently set, it is drawn with +foreground and background colors reversed. If this action is called when +there is no list element under the cursor, the currently <emphasis remap='I'>set</emphasis> +element will be <emphasis remap='I'>unset</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Unset</function>(\|) + </term> + <listitem> + <para> +Cancels the <emphasis remap='I'>set</emphasis> state of the element under the pointer, +and redraws it with normal foreground and background colors. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Notify</function>(\|) + </term> + <listitem> + <para> +Calls all callbacks on the List widget's callback list. Information +about the currently selected list element is passed in the +<emphasis remap='I'>call_data</emphasis> argument (see <function>List Callbacks</function> below). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="List_Callbacks"> +<title>List Callbacks</title> +<!-- .IN "List widget" "callbacks" --> +<para> +<!-- .LP --> +All procedures on the List widget's callback list will have a +<function>XawListReturnStruct</function> passed to them as <emphasis remap='I'>call_data</emphasis>. The +structure is defined in the List widget's application header file. +</para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> +<!-- .IN "XawListReturnStruct" "" "@DEF@" --> +typedef struct _XawListReturnStruct { + String string; /* string shown in the list. */ + int list_index; /* index of the item selected. */ +} XawListReturnStruct; +<!-- .IN "XawListReturnStruct" "" --> +<!-- .NT --> +</literallayout> +<note><para> +The <emphasis remap='I'>list_index</emphasis> item used to be called simply <emphasis remap='I'>index</emphasis>. +Unfortunately, this name collided with a global name defined on some +operating systems, and had to be changed. +</para></note> +<!-- .NE --> +</sect2> +<sect2 id="Changing_the_List"> +<title>Changing the List</title> +<para> +<!-- .LP --> +To change the list that is displayed, use +<function>XawListChange .</function> +<!-- .IN "XawListChange" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawListChange</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>String*<parameter> list</parameter></paramdef> + <paramdef>intnitems,<parameter> longest</parameter></paramdef> + <paramdef>Boolean<parameter> resize</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the List widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies the new list for the List widget to display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nitems</emphasis> + </term> + <listitem> + <para> +Specifies the number of items in the <emphasis remap='I'>list</emphasis>. If a value less than 1 +is specified, <emphasis remap='I'>list</emphasis> must be NULL terminated, and the number of +items will be calculated by the List widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>longest</emphasis> + </term> + <listitem> + <para> +Specifies the length of the longest item in the <emphasis remap='I'>list</emphasis> in pixels. +If a value less than 1 is specified, the List widget will calculate the +value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resize</emphasis> + </term> + <listitem> + <para> +Specifies a Boolean value that if <function>True</function> indicates that the +List widget should try to resize itself after making the change. +The constraints of the List widget's parent are always enforced, +regardless of the value specified here. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XawListChange</function> +will <emphasis remap='I'>unset</emphasis> all list elements that are currently <function>set</function> before +the list is actually changed. The <emphasis remap='I'>list</emphasis> is used in place, and must +remain usable for the lifetime of the List widget, or until <emphasis remap='I'>list</emphasis> +has been changed again with this function or with <function>XtSetValues</function>. +</para> +</sect2> +<sect2 id="Highlighting_an_Item"> +<title>Highlighting an Item</title> +<para> +<!-- .LP --> +To highlight an item in the list, use +<function>XawListHighlight .</function> +<!-- .IN "XawListHighlight" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawListHighlight</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>int<parameter> item</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the List widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>item</emphasis> + </term> + <listitem> + <para> +Specifies an index into the current list that indicates the item to be +highlighted. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Only one item can be highlighted at a time. +If an item is already highlighted when +<function>XawListHighlight</function> +is called, +the highlighted item is unhighlighted before the new item is highlighted. +</para> +</sect2> +<sect2 id="Unhighlighting_an_Item"> +<title>Unhighlighting an Item</title> +<para> +<!-- .LP --> +To unhighlight the currently highlighted item in the list, use +<function>XawListUnhighlight .</function> +<!-- .IN "XawListUnhighlight" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawListUnhighlight</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the List widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Retrieving_the_Currently_Selected_Item"> +<title>Retrieving the Currently Selected Item</title> +<para> +<!-- .LP --> +To retrieve the list element that is currently <emphasis remap='I'>set</emphasis>, use +<function>XawListShowCurrent .</function> +<!-- .IN "XawListShowCurrent" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>XawListReturnStruct<function> *XawListShowCurrent</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the List widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<function>XawListShowCurrent</function> +returns a pointer to an +<function>XawListReturnStruct</function> +structure, +containing the currently highlighted item. +If the value of the index member is XAW_LIST_NONE, +<!-- .IN "XAW_LIST_NONE" --> +the string member is undefined, and no item is currently selected. +</para> +</sect2> +<sect2 id="Restrictions"> +<title>Restrictions</title> +<para> +<!-- .LP --> +Many programmers create a ``scrolled list'' by putting a List +widget with many entries as a child of a Viewport widget. The +List continues to create a window as big as its contents, but +that big window is only visible where it intersects the parent +Viewport's window. (I.e., it is ``clipped.'') +</para> +<para> +<!-- .LP --> +While this is a useful technique, there is a serious drawback. +X does not support windows above 32,767 pixels in width or +height, but this height limit will be exceeded by a List's +window when the List has many entries (i.e., with a 12 point +font, about 3000 entries would be too many.) +</para> +<para> +<!-- .LP --> + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Makefile.am b/libXaw/specs/Makefile.am new file mode 100644 index 000000000..ebdbd729f --- /dev/null +++ b/libXaw/specs/Makefile.am @@ -0,0 +1,106 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +# DEALINGS IN THE SOFTWARE. +# + +if ENABLE_SPECS +doc_sources = libXaw.xml +dist_doc_DATA = $(doc_sources) \ + AsciiSink.xml \ + AsciiSource.xml \ + AsciiText.xml \ + Box.xml \ + CH1.xml \ + CH2.xml \ + CH3.xml \ + CH4.xml \ + CH5.xml \ + CH6.xml \ + CH7.xml \ + Command.xml \ + Dialog.xml \ + Form.xml \ + Grip.xml \ + Label.xml \ + List.xml \ + MenuButton.xml \ + Paned.xml \ + Panner.xml \ + Porthole.xml \ + Repeater.xml \ + Scrollbar.xml \ + SimpleMenu.xml \ + Simple.xml \ + SmeBSB.xml \ + SmeLine.xml \ + Sme.xml \ + StripChart.xml \ + Template_private_header_file.xml \ + Template_public_header_file.xml \ + Template_widget_source_file.xml \ + Template.xml \ + TextActions_default_translation_bindings.xml \ + TextActions_text_widget_actions.xml \ + TextActions.xml \ + TextCustom.xml \ + TextFuncs.xml \ + TextSink.xml \ + TextSource.xml \ + Text.xml \ + Toggle.xml \ + TPage_Credits.xml \ + Tree.xml \ + Viewport.xml + +if HAVE_XMLTO +doc_DATA = $(doc_sources:.xml=.html) + +if HAVE_FOP +doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) +endif + +if HAVE_XMLTO_TEXT +doc_DATA += $(doc_sources:.xml=.txt) +endif + +if HAVE_STYLESHEETS +XMLTO_FLAGS = -m $(XSL_STYLESHEET) \ + --stringparam html.stylesheet=$(STYLESHEET_SRCDIR)/xorg.css +endif + +CLEANFILES = $(doc_DATA) + +SUFFIXES = .xml .ps .pdf .txt .html + +%.txt: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< + +%.html: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< + +%.pdf: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< + +%.ps: %.xml $(dist_doc_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< + +endif HAVE_XMLTO +endif ENABLE_SPECS diff --git a/libXaw/specs/MenuButton.xml b/libXaw/specs/MenuButton.xml new file mode 100644 index 000000000..b907fefb5 --- /dev/null +++ b/libXaw/specs/MenuButton.xml @@ -0,0 +1,567 @@ +<sect2 id="MenuButton_Widget"> +<title>MenuButton Widget</title> +<!-- .XS --> +<!-- MenuButton Widget --> +<!-- .XE --> +<!-- .IN "MenuButton widget" "" "@DEF@" --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/MenuButton.h> +<!-- .IN "MenuButton.h" "" --> +Class Header file <X11/Xaw/MenuButtonP.h> +<!-- .IN "MenuButtonP.h" "" --> +Class menuButtonWidgetClass +<!-- .IN "menuButtonWidgetClass" "" --> +Class Name MenuButton +<!-- .IN "MenuButton widget" "class name" --> +Superclass Command +</literallayout> +<para> +<!-- .LP --> +<!-- .sp --> +The MenuButton widget is an area, often rectangular, +that displays a graphic. The graphic may be a text +string containing multiple lines of characters in an 8 +bit or 16 bit character set (to be displayed with a +<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with +a <emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or +pixmap. +</para> +<para> +<!-- .LP --> +When the pointer cursor is on a MenuButton widget, the +MenuButton becomes highlighted by drawing a rectangle +around its perimeter. This highlighting indicates +that the MenuButton is ready for selection. When a +pointer button is pressed, the MenuButton widget will +pop up the menu named in the <function>menuName</function> resource. +</para> +<sect3 id="Resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a MenuButton widget instance, +the following resources are retrieved from the argument list +or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "MenuButton 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>None</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>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>menuName</entry> + <entry>MenuName</entry> + <entry>String</entry> + <entry></entry> + <entry>"menu"</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>shapeStype</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bm --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Cb --> +<!-- .Cm --> +<!-- .Cr --> +<!-- .Cu --> +<!-- .Cn --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Lf --> +<!-- .Ls --> +<!-- .Lg --> +<!-- .Hw --> +<!-- .Ht --> +<!-- .Ib --> +<!-- .Ih --> +<!-- .In --> +<!-- .Ju --> +<!-- .La --> +<!-- .Mm --> +<variablelist> + <varlistentry> + <term> + <function>menuName</function> + </term> + <listitem> + <para> +The name of a popup shell to popup as a menu. The MenuButton +will search for this name using <function>XtNameToWidget</function> starting +with itself as the reference widget. If the search is +unsuccessful the widget will continue up the widget tree using +each of its ancestors as the reference widget passed to +<function>XtNameToWidget</function>. If no widget of called <function>menuName</function> is +found by this algorithm, the widget will print a warning message +and give up. When the menu is found it will be popped up +exclusive and spring_loaded. The MenuButton widget does not +copy the value of this resource into newly allocated memory. The +application programmer must pass the resource value in +nonvolatile memory. +<!-- .Pf --> +<!-- .Pb --> +<!-- .Re --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Ss --> +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="MenuButton_Actions"> +<title>MenuButton Actions</title> +<!-- .IN "MenuButton widget" "actions" --> +<para> +<!-- .LP --> +The MenuButton widget supports the following actions: +</para> +<itemizedlist> + <listitem> + <para> +Switching the button between the foreground and background +colors with <function>set</function> and <function>unset</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> + <listitem> + <para> +Popping up a menu with <function>PopupMenu</function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The following are the default translation bindings used by the +MenuButton widget: +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> + <EnterWindow>: highlight(\|) + <LeaveWindow>: reset(\|) + <BtnDown>: reset(\|) PopupMenu(\) +</literallayout> +</para> +</sect3> +<sect3 id="MenuButton_Actions_b"> +<title>MenuButton Actions_b</title> +<para> +<!-- .LP --> +The full list of actions supported by MenuButton 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>XtNforeground</function> +or <function>background</function> ) that matches the interior color of the +MenuButton 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 <function>set</function> or <function>highlight</function> and displays the interior of the +button in the <function>background</function> color, with the label 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 call_data argument in these callback functions is undefined. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>PopupMenu</function>(\|) + </term> + <listitem> + <para> +Pops up the menu specified by the <function>menuName</function> resource. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The MenuButton widget does not place a server grab on itself. +Instead, PopupMenu is registered as a grab action. +As a result, clients which popup menus without using XtMenuPopup +or MenuPopup or PopupMenu in translations will fail to have a grab active. +They should make a call to XtRegisterGrabAction on the appropriate action +in the application initialization routine, or use a different translation. +<!-- .bp --> + +</para> +</sect3> +</sect2> diff --git a/libXaw/specs/Paned.xml b/libXaw/specs/Paned.xml new file mode 100644 index 000000000..90c3809cc --- /dev/null +++ b/libXaw/specs/Paned.xml @@ -0,0 +1,1213 @@ +<sect1 id="Paned_Widget"> +<title>Paned Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Paned Widget --> +<!-- .XE --> +<!-- .IN "Paned widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Paned.h> +<!-- .IN "Paned.h" "" --> +Class Header file <X11/Xaw/PanedP.h> +<!-- .IN "PanedP.h" "" --> +Class panedWidgetClass +<!-- .IN "panedWidgetClass" "" --> +Class Name Paned +<!-- .IN "Paned widget" "class name" --> +Superclass Constraint +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Paned widget manages children in a vertically or horizontally +tiled fashion. The panes may be dynamically resized by the user by +using the <emphasis remap='I'>grips</emphasis> that appear near the right or bottom edge of the +border between two panes. +</para> +<para> +<!-- .LP --> +The Paned widget may accept any widget class as a pane <function>except</function> +Grip. Grip widgets have a special meaning for the Paned widget, and +adding a Grip as its own pane will confuse the Paned widget. +</para> +<sect2 id="Using_the_Paned_Widget"> +<title>Using the Paned Widget</title> +<!-- .IN "Paned widget" "using" --> +<para> +<!-- .LP --> +The grips allow the panes to be resized by the user. The semantics of +how these panes resize is somewhat complicated, and warrants further +explanation here. When the mouse pointer is positioned on a grip and +pressed, an arrow is displayed that indicates the pane that is to be to +be resized. While keeping the mouse button down, the user can move the +grip up and down (or left and right). This, in turn, changes the size +of the pane. The size of the Paned widget will not change. Instead, +it chooses another pane (or panes) to resize. For more details on which +pane it chooses to resize, see <function>Layout Semantics</function>. +</para> +<para> +<!-- .LP --> +One pointer binding allows the border between two panes to be moved, +without affecting any of the other panes. When this occurs the pointer +will change to an arrow that points along the pane border. +</para> +<para> +<!-- .LP --> +The default bindings for the Paned widget's grips are: +<informaltable> + <tgroup cols='3' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry>Mouse button</entry> + <entry>Pane to Resize - Vertical</entry> + <entry>Pane to Resize - Horizontal</entry> + </row> + </thead> + <tbody> + <row> + <entry>1 (left)</entry> + <entry>above the grip</entry> + <entry>left of the grip</entry> + </row> + <row> + <entry>2 (middle)</entry> + <entry>adjust border</entry> + <entry>adjust border</entry> + </row> + <row> + <entry>3 (right)</entry> + <entry>below the grip</entry> + <entry>right of the grip</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +</sect2> +<sect2 id="paned_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Paned widget instance, the following resources are +retrieved from the argument list or the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Paned 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>betweenCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry>A</entry> + <entry>Depends on orientation</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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>None</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>gripCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry>A</entry> + <entry>Depends on orientation</entry> + </row> + <row> + <entry>gripIndent</entry> + <entry>GripIndent</entry> + <entry>Position</entry> + <entry></entry> + <entry>10</entry> + </row> + <row> + <entry>gripTranslations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>see below</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Depends on orientation</entry> + </row> + <row> + <entry>horizontalBetweenCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_up_arrow</entry> + </row> + <row> + <entry>horizontalGripCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_h_double_arrow</entry> + </row> + <row> + <entry>internalBorderColor</entry> + <entry>BorderColor</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>internalBorderWidth</entry> + <entry>BorderWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + <row> + <entry>leftCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_left_arrow</entry> + </row> + <row> + <entry>lowerCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_down_arrow</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>orientation</entry> + <entry>Orientation</entry> + <entry>Orientation</entry> + <entry></entry> + <entry>XtorientVertical</entry> + </row> + <row> + <entry>refigureMode</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>rightCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_right_arrow</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>upperCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_up_arrow</entry> + </row> + <row> + <entry>verticalBetweenCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_left_arrow</entry> + </row> + <row> + <entry>verticalGripCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>sb_v_double_arrow</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Depends on orientation</entry> + </row> + <row> + <entry>x</entry> + <entry>Paned</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>y</entry> + <entry>Paned</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<variablelist> + <varlistentry> + <term> + <function>cursor</function> + </term> + <listitem> + <para> +The cursor to use when the mouse pointer is over the Paned widget, but +not in any of its children (children may also inherit this cursor). It +should be noted that the internal borders are actually part of the Paned +widget, not the children. +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>gripCursor</function> + </term> + <listitem> + <para> +The cursor to use when the grips are not active. The default value is +<function>verticalGripCursor</function> or <function>horizontalGripCursor</function> depending on +the orientation of the Paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>gripIndent</function> + </term> + <listitem> + <para> +The amount of space left between the right (or bottom) edge of the +Paned widget and all the grips. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>gripTranslation</function> + </term> + <listitem> + <para> +Translation table that will be applied to all grips. +<!-- .Hw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>horizontalBetweenCursor</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>verticalBetweenCursor</function> + </term> + <listitem> + <para> +The cursor to be used for the grip when changing the boundary between +two panes. These resources allow the cursors to be different +depending on the orientation of the Paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>horizontalGripCursor</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>verticalGripCursor</function> + </term> + <listitem> + <para> +The cursor to be used for the grips when they are not active. These +resources allow the cursors to be different depending on the +orientation of the Paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>internalBorderColor</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the internal +border color of the widget's window. The class name of this resource +allows <emphasis remap='I'>Paned*BorderColor: blue</emphasis> to set the internal border color +for the Paned widget. An optimization is invoked if +<function>internalBorderColor</function> and <function>background</function> are the same, and the +internal borders are not drawn. <function>internalBorderWidth</function> is still left +between the panes, however. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>internalBorderWidth</function> + </term> + <listitem> + <para> +The width of the internal borders. This is the amount of space left +between the panes. The class name of this resource allows +<emphasis remap='I'>Paned*BorderWidth: 3</emphasis> to set the internal border width for the +Paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>leftCursor</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>rightCursor</function> + </term> + <listitem> + <para> +The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize +when the Paned widget is oriented horizontally. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>lowerCursor</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>upperCursor</function> + </term> + <listitem> + <para> +The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize +when the Paned widget is oriented vertically. +<!-- .Mm --> +<!-- .Nc --> +This is not the same as the number of panes, since this also contains a +grip for some of the panes, use <function>XawPanedGetNumSub</function> to retrieve the +number of panes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>orientation</function> + </term> + <listitem> + <para> +The orientation to stack the panes. This value can be either +<function>XtorientVertical</function> or <function>XtorientHorizontal</function>. +<!-- .IN "XtorientVertical" "" --> +<!-- .IN "XtorientHorizontal" "" --> +<!-- .IN "conversions" "Orientation" --> +<!-- .Rs "vertical \fPand\fB horizontal" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>refigureMode</function> + </term> + <listitem> + <para> +This resource allows pane layout to be suspended. If this value is +<function>False</function>, then no layout actions will be taken. This may improve +efficiency when adding or removing more than one pane from the Paned +widget. +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="paned_constraint_resources"> +<title>Constraint Resources</title> +<para> +<!-- .LP --> +<!-- .IN "Paned widget" "constraint resources" --> +Each child of the Paned widget may request special layout resources +be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Paned +widget's children to specify individual layout requirements. +</para> +<para> +<!-- .LP --> +<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>allowResize</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>max</entry> + <entry>Max</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>Infinity</entry> + </row> + <row> + <entry>min</entry> + <entry>Min</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>Height of Grips</entry> + </row> + <row> + <entry>preferredPaneSize</entry> + <entry>PreferredPaneSize</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>ask child</entry> + </row> + <row> + <entry>resizeToPreferred</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>showGrip</entry> + <entry>ShowGrip</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>skipAdjust</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<variablelist> + <varlistentry> + <term> + <function>allowResize</function> + </term> + <listitem> + <para> +If this value is <function>False</function> the the Paned widget will disallow all +geometry requests from this child. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>max</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>min</function> + </term> + <listitem> + <para> +The absolute maximum or minimum size for this pane. These values will +never be overridden by the Paned widget. This may cause some panes to be +pushed off the bottom (or right) edge of the paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>preferredPaneSize</function> + </term> + <listitem> + <para> +Normally the paned widget makes a QueryGeometry call on a child to +determine the preferred size of the child's pane. There are times +when the application programmer or the user has a better idea of the +preferred size of a pane. Setting this resource causes the value +passed to be interpreted as the preferred size, in pixels, of this pane. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>resizeToPreferred</function> + </term> + <listitem> + <para> +Determines whether or not to resize each pane to its preferred size +when the Paned widget is resized. See <function>Layout Semantics</function> for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>showGrip</function> + </term> + <listitem> + <para> +If <function>True</function> then a grip will be shown for this pane. The grip +associated with a pane is either below or to the right of the pane. No +grip is ever shown for the last pane. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>skipAdjust</function> + </term> + <listitem> + <para> +This resource is used to determine which pane is forced to be resized. +Setting this value to <function>True</function> makes this pane less likely to be +forced to be resized. See <function>Layout Semantics</function> for details. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="paned_layout_semantics"> +<title>Layout Semantics</title> +<para> +<!-- .LP --> +<!-- .IN "Paned widget" "layout semantics" --> +In order to make effective use of the Paned widget it is helpful to know +the rules it uses to determine which child will be resized in any given +situation. There are three rules used to determine which child is +resized. While these rules are always the same, the panes that are +searched can change depending upon what caused the relayout. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<function>Layout Rules</function> +<variablelist> + <varlistentry> + <term> + <function>1</function> + </term> + <listitem> + <para> +Do not let a pane grow larger than its <function>max</function> or smaller than its +<function>min</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>2</function> + </term> + <listitem> + <para> +Do not adjust panes with <function>skipAdjust</function> set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>3</function> + </term> + <listitem> + <para> +Do not adjust panes away from their preferred size, although moving one +closer to its preferred size is fine. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When searching the children the Paned widget looks for panes that +satisfy all the rules, and if unsuccessful then it eliminates rule 3 +and then 2. Rule 1 is always enforced. +</para> +<para> +<!-- .LP --> +If the relayout is due to a resize or change in management then the +panes are searched from bottom to top. If the relayout is due to grip +movement then they are searched from the grip selected in the direction +opposite the pane selected. +</para> +<sect3 id="Resizing_Panes_from_a_Grip_Action"> +<title>Resizing Panes from a Grip Action</title> +<para> +<!-- .LP --> +The pane above the grip is resized by invoking the GripAction with +<function>UpLeftPane</function> specified. The panes below the grip are each checked +against all rules, then rules 2 and 1 and finally against rule 1 only. +No pane above the chosen pane will ever be resized. +</para> +<para> +<!-- .LP --> +The pane below the grip is resized by invoking the GripAction with +<function>LowRightPane</function> specified. The panes above the grip are each +checked in this case. No pane below the chosen pane will ever be resized. +</para> +<para> +<!-- .LP --> +Invoking GripAction with <function>ThisBorderOnly</function> specified just moves the +border between the panes. No other panes are ever resized. +</para> +</sect3> +<sect3 id="Resizing_Panes_after_the_Paned_widget_is_resized_"> +<title>Resizing Panes after the Paned widget is resized.</title> +<para> +<!-- .LP --> +When the Pane widget is resized it must determine a new size for each +pane. There are two methods of doing this. The Paned widget can either +give each pane its preferred size and then resize the panes to fit, or +it can use the current sizes and then resize the panes to fit. The +<function>resizeToPreferred</function> resource allows the application to tell the +Paned widget whether to query the child about its preferred size +(subject to the the <function>preferredPaneSize</function>) or to use the current size +when refiguring the pane locations after the pane has been resized. +</para> +<para> +<!-- .LP --> +There is one special case. All panes assume they should resize to +their preferred size until the Paned widget becomes visible to the user. +</para> +</sect3> +<sect3 id="Managing_Children_and_Geometry_Management"> +<title>Managing Children and Geometry Management</title> +<para> +<!-- .LP --> +The Paned widget always resizes its children to their preferred sizes when +a new child is managed, or a geometry management request is honored. +The Paned widget will first attempt to resize itself to contain its +panes exactly. If this is not possible then it will hunt through the +children, from bottom to top (right to left), for a pane to resize. +</para> +</sect3> +<sect3 id="paned_special_considerations"> +<title>Special Considerations</title> +<para> +<!-- .LP --> +When a user resizes a pane with the grips, the Paned widget assumes that +this new size is the preferred size of the pane. +</para> +</sect3> +</sect2> +<sect2 id="Grip_Translations"> +<title>Grip Translations</title> +<para> +<!-- .LP --> +The Paned widget has no action routines of its own, as all actions are +handled through the grips. The grips are each assigned a default +Translation table. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> + <Btn1Down>: GripAction(Start, UpLeftPane) +<!-- .IN "GripAction" "" --> + <Btn2Down>: GripAction(Start, ThisBorderOnly) + <Btn3Down>: GripAction(Start, LowRightPane) + <Btn1Motion>: GripAction(Move, UpLeftPane) + <Btn2Motion>: GripAction(Move, ThisBorderOnly) + <Btn3Motion>: GripAction(Move, LowRightPane) + Any<BtnUp>: GripAction(Commit) +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The Paned widget interprets the <function>GripAction</function> as taking two arguments. +<!-- .IN "GripAction" "" --> +The first argument may be any of the following: +<variablelist> + <varlistentry> + <term> + <function>Start</function> + </term> + <listitem> + <para> +Sets up the Paned widget for resizing and changes the cursor of the +grip. The second argument determines which pane will be resized, and +can take on any of the three values shown above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Move</function> + </term> + <listitem> + <para> +The internal borders are drawn over the current pane locations to +animate where the borders would actually be placed if you were to move +this border as shown. The second argument must match the second argument +that was passed to the <function>Start</function> action, that began this process. If +these arguments are not passed, the behavior is undefined. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Commit</function> + </term> + <listitem> + <para> +This argument causes the Paned widget to commit the changes selected +by the previously started action. The cursor is changed back to the +grip's inactive cursor. No second argument is needed in this case. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="paned_convenience_routines"> +<title>Convenience Routines</title> +<para> +<!-- .LP --> +<!-- .IN "Paned widget" "enable pane resizing" --> +<!-- .IN "Paned widget" "disable pane resizing" --> +To enable or disable a child's request for pane resizing, +use +<function>XawPanedAllowResize :</function> +<!-- .IN "XawPanedAllowResize" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawPanedAllowResize</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> allow_resize</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the child pane. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>allow_resize</emphasis> + </term> + <listitem> + <para> +Specifies whether or not resizing requests for this child will be +granted by the Paned widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +If allow_resize is <function>True</function>, the Paned widget allows geometry +requests from the child to change the pane's height. If allow_resize +is <function>False</function>, the Paned widget ignores geometry requests from the +child to change the pane's height. The default state is <function>True</function> +before the Pane is realized and <function>False</function> after it is realized. +This procedure is equivalent to changing the <function>allowResize</function> +constraint resource for the child. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "Paned widget" "change height settings" --> +To change the minimum and maximum height settings for a pane, use +<function>XawPanedSetMinMax :</function> +<!-- .IN "XawPanedSetMinMax" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawPanedSetMinMax</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>intmin,<parameter> max</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the child pane. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>min</emphasis> + </term> + <listitem> + <para> +Specifies the new minimum height of the child, expressed in pixels. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>max</emphasis> + </term> + <listitem> + <para> +Specifies new maximum height of the child, expressed in pixels. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This procedure is equivalent to setting the <function>min</function> and <function>max</function> +constraint resources for the child. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "Paned widget" "get height settings" --> +To retrieve the minimum and maximum height settings for a pane, use +<function>XawPanedGetMinMax :</function> +<!-- .IN "XawPanedGetMinMax" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawPanedGetMinMax</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>int*min_return,<parameter> *max_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the child pane. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>min_return</emphasis> + </term> + <listitem> + <para> +Returns the minimum height of the child, expressed in pixels. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>max_return</emphasis> + </term> + <listitem> + <para> +Returns the maximum height of the child, expressed in pixels. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This procedure is equivalent to getting the <function>min</function> and <function>max</function> +resources for this child child. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "Paned widget" "enable auto-reconfiguring" --> +<!-- .IN "Paned widget" "disable auto-reconfiguring" --> +To enable or disable automatic recalculation of pane sizes and positions, +use +<function>XawPanedSetRefigureMode :</function> +<!-- .IN "XawPanedSetRefigureMode" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawPanedSetRefigureMode</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Paned widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies whether the layout of the Paned widget is enabled (<function>True</function>) +or disabled (<function>False</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +When making several changes to the children of a Paned widget +after the Paned has been realized, it is a good idea to disable +relayout until after all changes have been made. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "Paned widget" "getting the number of children" --> +To retrieve the number of panes in a paned widget use +<function>XawPanedGetNumSub</function>: +<!-- .IN "XawPanedGetNumSub" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XawPanedGetNumSub</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Paned widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns the number of panes in the Paned widget. This is +<function>not</function> the same as the number of children, since the grips are also +children of the Paned widget. + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Panner.xml b/libXaw/specs/Panner.xml new file mode 100644 index 000000000..a04bb1a96 --- /dev/null +++ b/libXaw/specs/Panner.xml @@ -0,0 +1,734 @@ +<sect1 id="Panner_Widget"> +<title>Panner Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Panner Widget --> +<!-- .XE --> +<!-- .IN "Panner widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application header file <X11/Xaw/Panner.h> +<!-- .IN "Panner.h" "" --> +Class header file <X11/Xaw/PannerP.h> +<!-- .IN "PannerP.h" "" --> +Class pannerWidgetClass +<!-- .IN "pannerWidgetClass" "" --> +Class Name Panner +<!-- .IN "Panner widget" "class name" --> +Superclass Simple +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +A Panner widget is a rectangle, called the +``canvas,'' on which another rectangle, the ``slider,'' moves in two +dimensions. It is often used with a Porthole widget to move, or +``scroll,'' a third widget in two dimensions, in which case the +slider's size and position gives feedback as to what portion of +the third widget is visible. +</para> +<para> +<!-- .LP --> +The slider may be scrolled around the canvas by pressing, +dragging, and releasing Button1; the default translation also +enables scrolling via arrow keys and some other keys. While +scrolling is in progress, the application receives notification +through callback procedures. Notification may be done either +continuously whenever the slider moves or discretely whenever the +slider has been given a new location. +</para> +<sect2 id="panner_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Panner widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Panner 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>allowOff</entry> + <entry>AllowOff</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>backgroundStipple</entry> + <entry>BackgroundStipple</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</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>canvasHeight</entry> + <entry>CanvasHeight</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>canvasWidth</entry> + <entry>CanvasWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</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>defaultScale</entry> + <entry>DefaultScale</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>8</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>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>depends on orientation</entry> + </row> + <row> + <entry>internalSpace</entry> + <entry>InternalSpace</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>lineWidth</entry> + <entry>LineWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</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>reportCallback</entry> + <entry>ReportCallback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>resize</entry> + <entry>Resize</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>rubberBand</entry> + <entry>RubberBand</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>shadowColor</entry> + <entry>ShadowColor</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>shadowThickness</entry> + <entry>ShadowThickness</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>sliderX</entry> + <entry>SliderX</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>sliderY</entry> + <entry>SliderY</entry> + <entry>Position</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>sliderHeight</entry> + <entry>SliderHeight</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>sliderWidth</entry> + <entry>SliderWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</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>depends on orientation</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> + </tbody> + </tgroup> +</informaltable> +</para> +<!-- .Ac --> +<variablelist> + <varlistentry> + <term> + <function>allowOff</function> + </term> + <listitem> + <para> +Whether to allow the edges of the slider to go off the edges of the canvas. +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>backgroundStipple</function> + </term> + <listitem> + <para> +The name of a bitmap pattern to be used as the background for +the area representing the canvas. +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>canvasHeight</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>canvasWidth</function> + </term> + <listitem> + <para> +The size of the canvas. +<!-- .Cm --> +<!-- .Cu --> +<!-- .Cn --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>defaultScale</function> + </term> + <listitem> + <para> +The percentage size that the Panner widget should have relative +to the size of the canvas. +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>foreground</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +used to draw the slider. +<!-- .Hw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>internalSpace</function> + </term> + <listitem> + <para> +The width of internal border in pixels between a slider representing the +full size of the canvas +and the edge of the Panner widget. +<!-- .Ix --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>lineWidth</function> + </term> + <listitem> + <para> +The width of the lines in the rubberbanding rectangle when rubberbanding +is in effect instead of continuous scrolling. The default is 0. +<!-- .Mm --> +<!-- .Pf --> +<!-- .Pb --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>reportCallback</function> + </term> + <listitem> + <para> +All functions on this callback list are called when the +<function>notify</function> action is invoked. See the <function>Panner Actions</function> section +for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>resize</function> + </term> + <listitem> + <para> +Whether or not to resize the panner whenever the canvas size is changed so +that the <function>defaultScale</function> is maintained. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>rubberBand</function> + </term> + <listitem> + <para> +Whether or not scrolling should be discrete (only moving a rubberbanded +rectangle until the scrolling is done) or continuous (moving the slider +itself). This controls whether or not the <function>move</function> action procedure also +invokes the <function>notify</function> action procedure. +<!-- .Sc --> +<!-- .Se --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>shadowColor</function> + </term> + <listitem> + <para> +The color of the shadow underneath the slider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>shadowThickness</function> + </term> + <listitem> + <para> +The width of the shadow underneath the slider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>sliderX</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>sliderY</function> + </term> + <listitem> + <para> +The location of the slider in the coordinates of the canvas. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>sliderHeight</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>sliderWidth</function> + </term> + <listitem> + <para> +The size of the slider. +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +<sect2 id="Panner_Actions"> +<title>Panner Actions</title> +<!-- .IN "Panner widget" "actions" --> +<para> +<!-- .LP --> +The actions supported by the Panner widget are: +</para> +<variablelist> + <varlistentry> + <term> + <function>start</function>() + </term> + <listitem> + <para> +This action begins movement of the slider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>stop</function>() + </term> + <listitem> + <para> +This action ends movement of the slider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>abort</function>() + </term> + <listitem> + <para> +This action ends movement of the slider and restores it to the position it +held when the <function>start</function> action was invoked. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>move</function>() + </term> + <listitem> + <para> +This action moves the outline of the slider (if the <function>rubberBand</function> resource +is True) or the slider itself (by invoking the <function>notify</function> +action procedure). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>page</function>(<function>xamount</function>,<function>yamount</function>) + </term> + <listitem> + <para> +This action moves the slider by the specified amounts. The format +for the amounts is a signed or unsigned floating-point number (e.g., +1.0 +or \-.5) followed +by either <function>p</function> indicating pages (slider sizes), or <function>c</function> indicating +canvas sizes. Thus, <emphasis remap='I'>page(+0,+.5p)</emphasis> represents vertical movement down +one-half the height of the slider and <emphasis remap='I'>page(0,0)</emphasis> represents moving to +the upper left corner of the canvas. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>notify</function>() + </term> + <listitem> + <para> +This action informs the application of the slider's current position by +invoking the <function>reportCallback</function> functions registered by the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>set</function>(<function>what</function>,<function>value</function>) + </term> + <listitem> + <para> +This action changes the behavior of the Panner. The <emphasis remap='I'>what</emphasis> argument +must currently be the string <function>rubberband</function> and controls the value of +the <function>rubberBand</function> resource. The <function>value</function> argument +may have one of the values <function>on</function>, <function>off</function>, or <function>toggle</function>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +<!-- .sp --> +The default bindings for Panner are: +<!-- .IN "Panner widget" "default translation table" --> +</para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 1.75i --> +<!-- .ta .5i 1.75i --> + <Btn1Down>: start(\|) + <Btn1Motion>: move(\|) + <Btn1Up>: notify(\|) stop(\|) + <Btn2Down>: abort(\|) + <Key>KP_Enter: set(rubberband,toggle) + <Key>space: page(+1p,+1p) + <Key>Delete: page(\-1p,\-1p) + <Key>BackSpace: page(\-1p,\-1p) + <Key>Left: page(\-.5p,+0) + <Key>Right: page(+.5p,+0) + <Key>Up: page(+0,\-.5p) + <Key>Down: page(+0,+.5p) + <Key>Home: page(0,0) +</literallayout> +</sect2> + +<sect2 id="Panner_Callbacks"> +<title>Panner Callbacks</title> +<!-- .IN "Panner widget" "callbacks" --> +<para> +<!-- .LP --> +The functions registered on the <function>reportCallback</function> list are invoked by +the <function>notify</function> action as follows: +<!-- .IN "ReportProc" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> ReportProc</function></funcdef> + <paramdef>Widget<parameter> panner</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> report</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> + </para> +<para> +<variablelist> + <varlistentry> + <term>panner</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>panner</emphasis> 1i --> +Specifies the Panner widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>panner</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>client_data</emphasis> 1i --> +Specifies the client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>panner</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>report</emphasis> 1i --> +Specifies a pointer to an <function>XawPannerReport</function> structure containing +the location and size of the slider and the size of the canvas. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Porthole.xml b/libXaw/specs/Porthole.xml new file mode 100644 index 000000000..beda434ee --- /dev/null +++ b/libXaw/specs/Porthole.xml @@ -0,0 +1,306 @@ +<sect1 id="Porthole_Widget"> +<title>Porthole Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Porthole Widget --> +<!-- .XE --> +<!-- .IN "Porthole widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Porthole.h> +<!-- .IN "Porthole.h" "" --> +Class Header file <X11/Xaw/PortholeP.h> +<!-- .IN "PortholeP.h" "" --> +Class portholeWidgetClass +<!-- .IN "portholeWidgetClass" "" --> +Class Name Porthole +<!-- .IN "Porthole widget" "class name" --> +Superclass Composite +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Porthole widget provides geometry management of a list of arbitrary +widgets, only one of which may be managed at any particular time. +The managed child widget is reparented within the porthole and is moved around +by the application (typically under the control of a Panner widget). +</para> +<sect2 id="porthole_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Porthole widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Porthole 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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>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>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</function></entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>reportCallback</entry> + <entry>ReportCallback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</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> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<!-- .Mm --> +<!-- .Nc --> +<variablelist> + <varlistentry> + <term> + <function>reportCallback</function> + </term> + <listitem> + <para> +A list of functions to invoke whenever the managed child widget changes +size or position. + </para> + </listitem> + </varlistentry> +</variablelist> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> +</para> +</sect2> +<sect2 id="porthold_layout_semantics"> +<title>Layout Semantics</title> +<!-- .IN "Porthole widget" "layout semantics" --> +<para> +<!-- .LP --> +The Porthole widget allows its managed child to request any size +that is as large +or larger than the Porthole itself and any location so long as the child +still obscures all of the Porthole. This widget typically is used with a +Panner widget. +</para> +</sect2> +<sect2 id="Porthole_Callbacks"> +<title>Porthole Callbacks</title> +<!-- .IN "Porthole widget" "callbacks" --> +<para> +<!-- .LP --> +The functions registered on the <function>reportCallback</function> list are invoked whenever +the managed child changes size or position: +<!-- .IN "ReportProc" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> ReportProc</function></funcdef> + <paramdef>Widget<parameter> porthole</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> report</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +</para> +<variablelist> + <varlistentry> + <term>porthole</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>porthole</emphasis> 1i --> +Specifies the Porthole widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>client_data</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>client_data</emphasis> 1i --> +Specifies the client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>report</term> + <listitem> + <para> +<!-- .IP <emphasis remap='I'>report</emphasis> 1i --> +Specifies a pointer to an <function>XawPannerReport</function> structure containing +the location and size of the slider and the size of the canvas. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> diff --git a/libXaw/specs/Repeater.xml b/libXaw/specs/Repeater.xml new file mode 100644 index 000000000..35cd69aee --- /dev/null +++ b/libXaw/specs/Repeater.xml @@ -0,0 +1,558 @@ +<sect1 id="Repeater_Widget"> +<title>Repeater Widget</title> +<!-- .XS --> +<!-- Repeater Widget --> +<!-- .XE --> +<!-- .IN "Repeater widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application header file <X11/Xaw/Repeater.h> +<!-- .IN "Repeater.h" "" --> +Class header file <X11/Xaw/RepeaterP.h> +<!-- .IN "RepeaterP.h" "" --> +Class repeaterWidgetClass +<!-- .IN "repeaterWidgetClass" "" --> +Class Name Repeater +<!-- .IN "Repeater widget" "class name" --> +Superclass Command +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +The Repeater widget is a subclass of the Command widget; see the <!-- xref --> +Command documentation for details. The difference is that the Repeater can call its +registered callbacks repeatedly, at an increasing rate. The default translation +does so for the duration the user holds down pointer button 1 while the pointer +is on the Repeater. +</para> +<sect2 id="repeater_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Repeater widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Repeater 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>decay</entry> + <entry>Decay</entry> + <entry>Int</entry> + <entry></entry> + <entry>5</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>flash</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>font</entry> + <entry>Font</entry> + <entry>XFontStruct</entry> + <entry></entry> + <entry>XtDefaultFont</entry> + </row> + <row> + <entry>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>initialDelay</entry> + <entry>Delay</entry> + <entry>Int</entry> + <entry></entry> + <entry>200</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>minimumDelay</entry> + <entry>MinimumDelay</entry> + <entry>Int</entry> + <entry></entry> + <entry>10</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>repeatDelay</entry> + <entry>Delay</entry> + <entry>Int</entry> + <entry></entry> + <entry>50</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>Pointer</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>startCallback</entry> + <entry>StartCallback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>stopCallback</entry> + <entry>StopCallback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</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> + </tbody> + </tgroup> +</informaltable> +\" Resource Descriptions +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bm --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Cb --> +<!-- .Cm --> +<!-- .Cr --> +<!-- .Cu --> +<!-- .Cn --> +<variablelist> + <varlistentry> + <term> + <function>decay</function> + </term> + <listitem> + <para> +The number of milliseconds that should be subtracted from each succeeding +interval while the Repeater button is being held down until the interval +has reached <function>minimumDelay</function> milliseconds. +<!-- .Dp --> +<!-- .Dc --> +<!-- .Le --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>flash</function> + </term> + <listitem> + <para> +Whether or not to flash the Repeater button whenever the timer goes off. +<!-- .Lf --> +<!-- .Ls --> +<!-- .Lg --> +<!-- .Hw --> +<!-- .Ht --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>initialDelay</function> + </term> + <listitem> + <para> +The number of milliseconds between the beginning of the Repeater button +being held down and the first invocation of the <function>callback</function> function. +<!-- .Ib --> +<!-- .Ih --> +<!-- .In --> +<!-- .Ju --> +<!-- .La --> +<!-- .Ll --> +<!-- .Mm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>minimumDelay</function> + </term> + <listitem> + <para> +The minimum time between callbacks in milliseconds. +<!-- .Pf --> +<!-- .Pb --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>repeatDelay</function> + </term> + <listitem> + <para> +The number of milliseconds between each callback after the first (minus an +increasing number of <function>decay</function>s). +<!-- .Re --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Ss --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>startCallback</function> + </term> + <listitem> + <para> +The list of functions to invoke by the <function>start</function> action (typically +when the Repeater button is first pressed). The callback data parameter +is set to NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>stopCallback</function> + </term> + <listitem> + <para> +The list of functions to invoke by the <function>stop</function> action (typically +when the Repeater button is released). The callback data parameter +is set to NULL. +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Repeater_Actions"> +<title>Repeater Actions</title> +<!-- .IN "Repeater widget" "actions" --> +<para> +<!-- .LP --> +The Repeater widget supports the following actions beyond those of the Command +button: +<variablelist> + <varlistentry> + <term> + <function>start</function>() + </term> + <listitem> + <para> +This invokes the functions on the <function>startCallback</function> and <function>callback</function> lists +and sets a timer to go off in <function>initialDelay</function> milliseconds. The timer +will cause the <function>callback</function> functions to be invoked with increasing +frequency until the <function>stop</function> action occurs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>stop</function>() + </term> + <listitem> + <para> +This invokes the functions on the <function>stopCallback</function> list and prevents any +further timers from occuring until the next <function>start</function> action. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<!-- .IN "Repeater widget" "translation bindings" --> +The following are the default translation bindings used by the +Repeater widget: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> + <EnterWindow>: highlight(\|) + <LeaveWindow>: unhighlight(\|) + <Btn1Down>: set(\|) start(\|) + <Btn1Up>: stop(\|) unset(\|) +</literallayout> +</para> +<para> +<!-- .LP --> + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/Scrollbar.xml b/libXaw/specs/Scrollbar.xml new file mode 100644 index 000000000..87f6d68eb --- /dev/null +++ b/libXaw/specs/Scrollbar.xml @@ -0,0 +1,884 @@ +<sect1 id="Scrollbar_Widget"> +<title>Scrollbar Widget</title> + +<literallayout class="monospaced"> +Application header file <X11/Xaw/Scrollbar.h> +Class header file <X11/Xaw/ScrollbarP.h> +Class scrollbarWidgetClass +Class Name Scrollbar +Superclass Simple +</literallayout> + +<para> +A Scrollbar widget is a rectangle, called the ``canvas,'' on +which another rectangle, the ``thumb,'' moves in one +dimension, either vertically or horizontally. A Scrollbar +can be used alone, as a value generator, or it can be used +within a composite widget (for example, a Viewport). When a +Scrollbar is used to move, or ``scroll,'' the contents of +another widget, the size and the position of the thumb usually give +feedback as to what portion of the other widget's contents +are visible. +</para> + +<para> +Each pointer button invokes a specific action. Pointer +buttons 1 and 3 do not move the thumb automatically. +Instead, they return the pixel position of the cursor on the +scroll region. When pointer button 2 is clicked, the thumb +moves to the current pointer position. When pointer button +2 is held down and the pointer is moved, the thumb follows +the pointer. +</para> + +<para> +The pointer cursor in the scroll region changes depending on the current +action. When no pointer button is pressed, the cursor appears as a +double-headed arrow that points in the direction that scrolling can +occur. When pointer button 1 or 3 is pressed, the cursor appears as a +single-headed arrow that points in the logical direction that the thumb +will move. When pointer button 2 is pressed, the cursor +appears as an arrow that points to the top or the left of the thumb. +</para> + +<para> +When the user scrolls, the application receives notification +through callback procedures. For both discrete scrolling actions, the +callback returns the Scrollbar widget, the client_data, and the pixel +position of the pointer when the button was released. For continuous +scrolling, the callback routine returns the scroll bar widget, the +client data, and the current relative position of the thumb. When the +thumb is moved using pointer button 2, the callback procedure is invoked +continuously. When either button 1 or 3 is pressed, the callback +procedure is invoked only when the button is released and the client +callback procedure is responsible for moving the thumb. +</para> + +<sect2 id="scrollbar_resources"> +<title>Resources</title> + +<para> +When creating a Scrollbar widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> + +<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>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>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>parent's Colormap</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>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>depends on orientation</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</entry> + </row> + <row> + <entry>jumpProc</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>length</entry> + <entry>Length</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>minimumThumb</entry> + <entry>MinimumThumb</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>7</entry> + </row> + <row> + <entry>orientation</entry> + <entry>Orientation</entry> + <entry>Orientation</entry> + <entry></entry> + <entry>XtorientVertical (vertical)</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>screen</entry> + <entry>Screen</entry> + <entry>Screen</entry> + <entry>R</entry> + <entry>parent's Screen</entry> + </row> + <row> + <entry>scrollDCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_down_arrow</entry> + </row> + <row> + <entry>scrollHCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_h_double_arrow</entry> + </row> + <row> + <entry>scrollLCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_left_arrow</entry> + </row> + <row> + <entry>scrollProc</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>scrollRCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_right_arrow</entry> + </row> + <row> + <entry>scrollUCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_up_arrow</entry> + </row> + <row> + <entry>scrollVCursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_sb_v_arrow</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>shown</entry> + <entry>Shown</entry> + <entry>Float</entry> + <entry></entry> + <entry>0.0</entry> + </row> + <row> + <entry>thickness</entry> + <entry>Thickness</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>14</entry> + </row> + <row> + <entry>thumb</entry> + <entry>Thumb</entry> + <entry>Bitmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>thumbProc</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>topOfThumb</entry> + <entry>TopOfThumb</entry> + <entry>Float</entry> + <entry></entry> + <entry>0.0</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>depends on orientation</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> + </tbody> + </tgroup> +</informaltable> + +<variablelist> + <varlistentry> + <term> + <function>foreground</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +used to draw the thumb. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>jumpProc</function> + </term> + <listitem> + <para> +All functions on this callback list are called when the +<function>NotifyThumb</function> action is invoked. See the <function>Scrollbar +Actions</function> section for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>length</function> + </term> + <listitem> + <para> +The height of a vertical scrollbar or the width of a horizontal scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>minimumThumb</function> + </term> + <listitem> + <para> +The smallest size, in pixels, to which the thumb can shrink. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>orientation</function> + </term> + <listitem> + <para> +The orientation is the direction that the thumb will be allowed to move. +This value can be either <function>XtorientVertical</function> or +<function>XtorientHorizontal</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollDCursor</function> + </term> + <listitem> + <para> +This cursor is used when scrolling backward in a vertical scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollHCursor</function> + </term> + <listitem> + <para> +This cursor is used when a horizontal scrollbar is inactive. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollLCursor</function> + </term> + <listitem> + <para> +This cursor is used when scrolling forward in a horizontal scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollProc</function> + </term> + <listitem> + <para> +All functions on this callback list may be called when the +<function>NotifyScroll</function> action is invoked. See the \fBScrollbar +Actions\fP section for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollRCursor</function> + </term> + <listitem> + <para> +This cursor is used when scrolling backward in a horizontal scrollbar, +or when thumbing a vertical scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollUCursor</function> + </term> + <listitem> + <para> +This cursor is used when scrolling forward in a vertical scrollbar, or when +thumbing a horizontal scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>scrollVCursor</function> + </term> + <listitem> + <para> +This cursor is used when a vertical scrollbar is inactive. +<!-- .Se --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>shown</function> + </term> + <listitem> + <para> +This is the size of the thumb, expressed as a percentage (0.0 - 1.0) +of the length of the scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>thickness</function> + </term> + <listitem> + <para> +The width of a vertical scrollbar or the height of a horizontal scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>thumb</function> + </term> + <listitem> + <para> +This pixmap is used to tile (or stipple) the thumb of the scrollbar. If +no tiling is desired, then set this resource to <function>None</function>. This +resource will accept either a bitmap or a pixmap that is the same depth +as the window. The resource converter for this resource constructs +bitmaps from the contents of files. (See <function>Converting Bitmaps</function> for +details.) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>topOfThumb</function> + </term> + <listitem> + <para> +The location of the top of the thumb, as a percentage (0.0 - 1.0) +of the length of the scrollbar. This resource was called <function>top</function> in +previous versions of the Athena widget set. The name collided with the +a Form widget constraint resource, and had to be changed. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2 id="Scrollbar_Actions"> +<title>Scrollbar Actions</title> +<para> +<!-- .LP --> +The actions supported by the Scrollbar widget are: +</para> +<variablelist> + <varlistentry> + <term> + <function>StartScroll</function>(<emphasis remap='I'>value</emphasis>) + </term> + <listitem> + <para> +The possible <emphasis remap='I'>values</emphasis> are Forward, Backward, or Continuous. +This must be the first action to begin a new movement. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>NotifyScroll</function>(<emphasis remap='I'>value</emphasis>) + </term> + <listitem> + <para> +The possible <emphasis remap='I'>values</emphasis> are Proportional or FullLength. If the +argument to StartScroll was Forward or Backward, NotifyScroll executes +the <function>scrollProc</function> callbacks and passes either; the position of the +pointer, if <emphasis remap='I'>value</emphasis> is Proportional, or the full length of the +scroll bar, if <emphasis remap='I'>value</emphasis> is FullLength. If the argument to +StartScroll was Continuous, NotifyScroll returns without executing any +callbacks. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>EndScroll</function>(\^) + </term> + <listitem> + <para> +This must be the last action after a movement is complete. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>MoveThumb</function>(\^) + </term> + <listitem> + <para> +Repositions the Scrollbar's thumb to the current pointer location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>NotifyThumb</function>(\^)\ + </term> + <listitem> + <para> +Calls the +<!-- .PN jumpProc --> +callbacks and passes the relative position of the +pointer as a percentage of the scroll bar length. + </para> + </listitem> + </varlistentry> +</variablelist> +<para> +The default bindings for Scrollbar are: +<!-- .IN "Scrollbar widget" "default translation table" --> +</para> + +<literallayout class="monospaced"> + <Btn1Down>: StartScroll(Forward) + <Btn2Down>: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|) + <Btn3Down>: StartScroll(Backward) + <Btn2Motion>: MoveThumb(\|) NotifyThumb(\|) + <BtnUp>: NotifyScroll(Proportional) EndScroll(\|) +</literallayout> + +<para> +Examples of additional bindings a user might wish to specify in a +resource file are: +</para> + +<literallayout class="monospaced"> +*Scrollbar.Translations: \\ + ~Meta<Key>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ + Meta<Key>space: StartScroll(Backward) NotifyScroll(FullLength) \\n\\ + EndScroll(\|) +</literallayout> + +</sect2> + +<sect2 id="Scrollbar_Callbacks"> +<title>Scrollbar Callbacks</title> +<!-- .IN "Scrollbar widget" "callbacks" --> +<para> +<!-- .LP --> +There are two callback lists provided by the Scrollbar widget. +The procedural interface for these functions is described here. +</para> + +<para> +<!-- .LP --> +The calling interface to the <function>scrollProc</function> callback procedure is: +<!-- .IN "ScrollProc" "" "@DEF@" --> +</para> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> ScrollProc</function></funcdef> + <paramdef>Widget<parameter> scrollbar</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> position</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>scrollbar</emphasis> + </term> + <listitem> + <para> +Specifies the Scrollbar widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>position</emphasis> + </term> + <listitem> + <para> +Specifies a pixel position in integer form. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The <function>scrollProc</function> callback is used for incremental scrolling +and is called by the <function>NotifyScroll</function> action. +The position argument is a signed quantity and should be cast to an int +when used. Using the default button bindings, button 1 returns a +positive value, and button 3 returns a negative value. In both cases, +the magnitude of the value is the distance of the pointer in +pixels from the top (or left) of the Scrollbar. The value will never +be greater than the length of the Scrollbar. +</para> + +<para> +The calling interface to the <function>jumpProc</function> callback procedure is: +</para> +<!-- .IN "jumpProc" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> JumpProc</function></funcdef> + <paramdef>Widget<parameter> scrollbar</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> percent_ptr</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>scrollbar</emphasis> + </term> + <listitem> + <para> +Specifies the ID of the scroll bar widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>percent_ptr</emphasis> + </term> + <listitem> + <para> +Specifies the floating point position of the thumb (0.0 \- 1.0). + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The <function>jumpProc</function> callback is used to implement smooth scrolling and +is called by the <function>NotifyThumb</function> action. Percent_ptr must be cast +to a pointer to float before use; i.e. +</para> + +<literallayout class="monospaced"> + float percent = *(float*)percent_ptr; +</literallayout> + +<para> +With the default button bindings, button 2 moves the thumb interactively, +and the <function>jumpProc</function> is called on each new position of the pointer, +while the pointer button remains down. The value specified by +<emphasis remap='I'>percent_ptr</emphasis> is the current location of the thumb (from the top or +left of the Scrollbar) expressed as a percentage of the length of the +Scrollbar. +</para> + +</sect2> + +<sect2 id="Convenience_Routines"> +<title>Convenience Routines</title> +<para> +<!-- .IN "Scrollbar widget" "setting thumb values" --> +To set the position and length of a Scrollbar thumb, use +<!-- .PN XawScrollbarSetThumb . --> +<!-- .IN "XawScrollbarSetThumb" "" "@DEF@" --> +</para> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawScrollbarSetThumb</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>float<parameter> top</parameter></paramdef> + <paramdef>float<parameter> shown</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Scrollbar widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>top</emphasis> + </term> + <listitem> + <para> +Specifies the position of the top of the thumb as a fraction of the +length of the Scrollbar. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>shown</emphasis> + </term> + <listitem> + <para> +Specifies the length of the thumb as a fraction of the total length +of the Scrollbar. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XawScrollbarThumb</function> +moves the visible thumb to a new position (0.0 \- 1.0) and length (0.0 \- 1.0). +Either the top or shown arguments can be specified as \-1.0, +in which case the current value is left unchanged. +Values greater than 1.0 are truncated to 1.0. +</para> + +<para> +If called from <function>jumpProc</function>, <function>XawScrollbarSetThumb</function> has no effect. +</para> + +</sect2> + +<sect2 id="Setting_Float_Resources"> +<title>Setting Float Resources</title> +<!-- .IN "float resources" "setting" --> +<para> +The <function>shown</function> and <function>topOfThumb</function> resources are of type +<emphasis remap='I'>float</emphasis>. These resources can be difficult to get into an +argument list. The reason is that C performs an automatic cast of +the float value to an integer value, usually truncating the important +information. The following code fragment is one portable method of +getting a float into an argument list. +</para> +<literallayout class="monospaced"> + top = 0.5; + if (sizeof(float) > sizeof(XtArgVal)) { + /* + \ * If a float is larger than an XtArgVal then pass this + \ * resource value by reference. + \ */ + XtSetArg(args[0], XtNshown, &top); + } + else { + /* + \ * Convince C not to perform an automatic conversion, which + \ * would truncate 0.5 to 0. + \ */ + XtArgVal * l_top = (XtArgVal *) &top; + XtSetArg(args[0], XtNshown, *l_top); + } +</literallayout> + +</sect2> +</sect1> diff --git a/libXaw/specs/Simple.xml b/libXaw/specs/Simple.xml new file mode 100644 index 000000000..a21bc64f5 --- /dev/null +++ b/libXaw/specs/Simple.xml @@ -0,0 +1,252 @@ +<sect1 id="Simple_Widget"> +<title>Simple Widget</title> +<!-- .XS --> +<!-- Simple Widget --> +<!-- .XE --> +<!-- .IN "Simple widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <Xaw/Simple.h> +<!-- .IN "Simple.h" "" --> +Class Header file <Xaw/SimpleP.h> +<!-- .IN "SimpleP.h" "" --> +Class simpleWidgetClass +<!-- .IN "simpleWidgetClass" --> +Class Name Simple +<!-- .IN "Simple widget" "class name" --> +Superclass Core +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +The Simple widget is not very useful by itself, as it has no semantics +of its own. It main purpose is to be used as a common superclass for +the other <emphasis remap='I'>simple</emphasis> Athena widgets. This widget adds six resources +to the resource list provided by the Core widget and its superclasses. +</para> +<sect2 id="simple_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Simple widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Simple 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>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>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</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>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</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>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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</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> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Cm --> +<!-- .Cu Bold --> +<!-- .Cn Bold --> +<!-- .Dp --> +<!-- .Dc --> +<!-- .Hw --> +<!-- .Ib Bold --> +<!-- .Ix Bold --> +<!-- .Mm --> +<!-- .Pf Bold --> +<!-- .Pb Bold --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/SimpleMenu.xml b/libXaw/specs/SimpleMenu.xml new file mode 100644 index 000000000..84ba039e7 --- /dev/null +++ b/libXaw/specs/SimpleMenu.xml @@ -0,0 +1,790 @@ +<sect2 id="SimpleMenu_Widget"> +<title>SimpleMenu Widget</title> +<!-- .XS --> +<!-- SimpleMenu Widget --> +<!-- .XE --> +<!-- .IN "SimpleMenu widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/SimpleMenu.h> +<!-- .IN "SimpleMenu.h" "" --> +Class Header file <X11/Xaw/SimpleMenP.h> +<!-- .IN "SimpleMenP.h" "" --> +Class simpleMenuWidgetClass +<!-- .IN "simpleMenuWidgetClass" "" --> +Class Name SimpleMenu +<!-- .IN "SimpleMenu widget" "class name" --> +Superclass OverrideShell +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +The SimpleMenu widget is a container for the menu entries. It is a +direct subclass of shell, and is should be created with +<function>XtCreatePopupShell</function>, not <function>XtCreateManagedWidget</function>. This is the +only part of the menu that +actually is associated with a window. The SimpleMenu serves as the glue to bind +the individual menu entries together into a menu. +</para> +<sect3 id="Resources"> +<title>Resources</title> +<para> +<!-- .LP --> +<!-- .IN "SimpleMenu widget" "resources" --> +</para> +<para> +<!-- .LP --> +The resources associated with the SimpleMenu widget control aspects +that will affect the entire menu. +<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>allowShellResize</entry> + <entry>AllowShellResize</entry> + <entry>Boolean</entry> + <entry></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>backingStore</entry> + <entry>BackingStore</entry> + <entry>BackingStore</entry> + <entry></entry> + <entry>see below</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>bottomMargin</entry> + <entry>VerticalMargins</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</entry> + <entry>NULL</entry> + </row> + <row> + <entry>createPopupChildProc</entry> + <entry>CreatePopupChildProc</entry> + <entry>Function</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>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>None</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>geometry</entry> + <entry>Geometry</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>Enough space to contain all entries</entry> + </row> + <row> + <entry>label</entry> + <entry>Label</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>labelClass</entry> + <entry>LabelClass</entry> + <entry>Pointer</entry> + <entry></entry> + <entry>SmeBSBObjectClass</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>menuOnScreen</entry> + <entry>MenuOnScreen</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>overrideRedirect</entry> + <entry>OverrideRedirect</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>popdownCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>popupCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>popupOnEntry</entry> + <entry>PopupOnEntry</entry> + <entry>Widget</entry> + <entry>A</entry> + <entry>Label or first entry</entry> + </row> + <row> + <entry>rowHeight</entry> + <entry>RowHeight</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>saveUnder</entry> + <entry>SaveUnder</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>topMargin</entry> + <entry>VerticalMargins</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>See below</entry> + </row> + <row> + <entry>visual</entry> + <entry>Visual</entry> + <entry>Visual</entry> + <entry></entry> + <entry>CopyFromParent</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>Width of widest entry</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> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<variablelist> + <varlistentry> + <term> + <function>backingStore</function> + </term> + <listitem> + <para> +<!-- .IN "conversions" "BackingStore" --> +Determines what type of backing store will be used for the menu. Legal +values for this resource are <function>NotUseful</function>, <function>WhenMapped</function>, and +<function>Always</function>. These values are the backing-store integers defined in +<X11/X.h>. +<!-- .Rs "notUseful, whenMapped, always, \fPand\fP default" --> +If <function>default</function> is specified (the default behavior) the server will use +whatever it thinks is appropriate. +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>bottomMargin</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>topMargin</function> + </term> + <listitem> + <para> +The amount of space between the top or bottom of the menu and the menu entry +closest to that edge. +<!-- .Ch --> +<!-- .Cm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>cursor</function> + </term> + <listitem> + <para> +The shape of the mouse pointer whenever it is in this widget. +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + geometry + </term> + <listitem> + <para> +If this resource is specified it will override the x, y, width and +height of this widget. The format of this string is +[<<emphasis remap='I'>width</emphasis>>x<<emphasis remap='I'>height</emphasis>>][{+ -} <<emphasis remap='I'>xoffset</emphasis>> {+ -}<<emphasis remap='I'>yoffset</emphasis>>]. +<!-- .Hw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>label</function> + </term> + <listitem> + <para> +This label will be placed at the top of the SimpleMenu, and may not be +highlighted. The name of the +label object is <function>menuLabel</function>. Using this name it is possible to +modify the label's attributes through the resource database. When the label +is created, the <function>label</function> is hard coded to the value of <function>label</function>, and +<function>justify</function> is hard coded as <function>XtJustifyCenter</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>labelClass</function> + </term> + <listitem> + <para> +Specifies the type of Sme object created as the menu label. +<!-- .Mm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>menuOnScreen</function> + </term> + <listitem> + <para> +If the menu is automatically positioned under the cursor with the +<function>XawPositionSimpleMenu</function> action, and this resource is <function>True</function>, +then the menu will always be fully visible on the screen. +<!-- .Nc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + overrideRedirect + </term> + <listitem> + <para> +Determines the value of the override_redirect attribute of the +SimpleMenu's window. The override_redirect attribute of a window +determines whether or not a window manager may interpose itself between +this window and the root window of the display. For more information +see the <emphasis remap='I'>Interclient Communications Conventions Manual</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + popdownCallback + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + popupCallback + </term> + <listitem> + <para> +These callback functions are called by the Xt Intrinsics whenever the +shell is popped up or down (See <emphasis remap='I'>(xT</emphasis> for details). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>popupOnEntry</function> + </term> + <listitem> + <para> +The <function>XawPositionSimpleMenu</function> action will, by default, popup the +SimpleMenu with its label (or first entry) directly under the +pointer. To popup the menu under +another entry, set this resource to the menu entry that should be +under the pointer, when the menu is popped up. This allows the +application to offer the user a default menu entry that can be selected +with out moving the pointer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>rowHeight</function> + </term> + <listitem> + <para> +If this resources is zero (the default) then each menu entry will be +given its desired height. If this resource has any other value then +all menu entries will be forced to be <function>rowHeight</function> pixels high. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + saveUnder + </term> + <listitem> + <para> +If this is <function>True</function> then save unders will be active on the menu's window. +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="SimpleMenu_Actions"> +<title>SimpleMenu Actions</title> +<!-- .IN "SimpleMenu widget" "actions" --> +<para> +<!-- .LP --> +The SimpleMenu widget supports the following actions: +</para> +<itemizedlist> + <listitem> + <para> +Switching the entry under the mouse pointer between +the foreground and background colors with <function>highlight</function> +and <function>unhighlight</function> + </para> + </listitem> + <listitem> + <para> +Processing menu entry callbacks with <function>notify</function> +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<!-- .IN "SimpleMenu widget" "default translations" --> +The following are the default translation bindings used +by the SimpleMenu widget: +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> + <EnterWindow>: highlight(\|) + <LeaveWindow>: unhighlight(\|) + <BtnMotion>: highlight(\|) + <BtnUp>: MenuPopdown(\|) notify(\|) unhighlight(\|) +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +<!-- .IN "SimpleMenu widget" "MenuPopdown routine" --> +The user can pop down the menu without activating any of the callback +functions by releasing the pointer button when no menu item is +highlighted. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The full list of actions supported by SimpleMenu is: +<variablelist> + <varlistentry> + <term> + <function>highlight</function>() + </term> + <listitem> + <para> +Highlight the menu entry that is currently under the pointer. +Only a item that is highlighted will be notified when the <function>notify</function> +action is invoked. The look of a highlighted entry is determined by +the menu entry. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>unhighlight</function>(\|) + </term> + <listitem> + <para> +Unhighlights the currently highlighted menu item, and returns it to +its normal look. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>notify</function>(\|) + </term> + <listitem> + <para> +Notifies the menu entry that is currently highlighted that is has been +selected. It is the responsibility of the menu entry to take the +appropriate action. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>MenuPopdown</function>(<emphasis remap='I'>menu</emphasis>) + </term> + <listitem> + <para> +This action is defined in <emphasis remap='I'>(xT</emphasis>. +<!-- .IN "SimpleMenu widget" "MenuPopdown routine" --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Positioning_the_SimpleMenu"> +<title>Positioning the SimpleMenu</title> +<!-- .IN "XawPositionSimpleMenu" "" "@DEF@" --> +<!-- .IN "SimpleMenu widget" "positioning" "@DEF@" --> +<para> +<!-- .LP --> +If the SimpleMenu widget is to be used as a pulldown menu then the +MenuButton widget, or some other outside means should be used to place +the menu when it is popped up. +</para> +<para> +<!-- .LP --> +If popup menus are desired it will be necessary to add the +<function>XawPositionSimpleMenu</function> and <function>MenuPopup</function> actions to the +translation table of the widget that will be popping up the menu. The +<function>MenuPopup</function> action is described in <emphasis remap='I'>(xT</emphasis>. +<function>XawPositionSimpleMenu</function> is a global action procedure registered by +the SimpleMenu widget when the first one is created or the convenience +routine <function>XawSimpleMenuAddGlobalActions</function> is called. +</para> +<para> +<!-- .LP --> +Translation writers should be aware that Xt does not register grabs on +``don't care'' modifiers, and therefore the left hand side of the +production should be written to exclude unspecified modifiers. +For example these are the translations needed to popup some of +<function>xterm's</function> menus: +<!-- .sp --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.25i --> +<!-- .ta .5i 2.25i --> + !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm) + !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes) +</literallayout> +<!-- .sp 1 --> +</para> +<para> +<!-- .LP --> +<variablelist> + <varlistentry> + <term> + <function>XawPositionSimpleMenu</function>(<emphasis remap='I'>menu</emphasis>) + </term> + <listitem> + <para> +The <function>XawPositionSimpleMenu</function> routine will search for the menu name +passed to it using <function>XtNameToWidget</function> starting with the widget +invoking the action as the reference widget. If it is unsuccessful it +will continue up the widget tree using each of the invoking widget's +ancestors as the reference widget. If it is still unsuccessful it will +print a warning message and give up. <function>XawPositionSimpleMenu</function> will +position the menu directly under the pointer cursor. The menu will be +placed so that the pointer cursor is centered on the entry named by the +<function>popupOnEntry</function> resource. If the <function>menuOnScreen</function> resource is +<function>True</function> then the menu will always be fully visible on the screen. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Convenience_Routines"> +<title>Convenience Routines</title> +<sect4 id="Registering_the_Global_Action_Routines"> +<title>Registering the Global Action Routines</title> +<para> +<!-- .LP --> +<!-- .IN "XawPositionSimpleMenu" "" --> +The <function>XawPositionSimpleMenu</function> action routine may often be invoked +before any menus have been created. This can occur when an +application uses dynamic menu creation. In these cases an application will +need to register this global action routine by calling +<function>XawSimpleMenuAddGlobalActions</function>: +<!-- .IN "XawSimpleMenuAddGlobalActions" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawSimpleMenuAddGlobalActions</function></funcdef> + <paramdef>XtAppContext<parameter> app_con</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_con</emphasis> + </term> + <listitem> + <para> +Specifies the application context in which this action should be registered. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function need only be called once per application and must be +called before any widget that uses <function>XawPositionSimpleMenu</function> action +is realized. +</para> +</sect4> +<sect4 id="Getting_and_Clearing_the_Current_Menu_Entry"> +<title>Getting and Clearing the Current Menu Entry</title> +<para> +<!-- .LP --> +To get the currently highlighted menu entry use +<function>XawSimpleMenuGetActiveEntry</function>: +<!-- .IN "XawSimpleMenuGetActiveEntry" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XawSimpleMenuGetActiveEntry</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the SimpleMenu widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns the menu entry that is +currently highlighted, or NULL if no entry is highlighted. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To clear the SimpleMenu widget's internal information about the +currently highlighted menu entry use +<function>XawSimpleMenuClearActiveEntry</function>: +<!-- .IN "XawSimpleMenuClearActiveEntry" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XawSimpleMenuClearActiveEntry</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the SimpleMenu widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function unsets all internal references to the currently +highlighted menu entry. It does not <emphasis remap='I'>unhighlight</emphasis> or otherwise +alter the appearance of the active entry. This function is primarily +for use by implementors of menu entries. + +</para> +</sect4> +</sect3> +</sect2> diff --git a/libXaw/specs/Sme.xml b/libXaw/specs/Sme.xml new file mode 100644 index 000000000..2d3d2f5f7 --- /dev/null +++ b/libXaw/specs/Sme.xml @@ -0,0 +1,207 @@ +<sect1 id="Sme_Object"> +<title>Sme Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Sme Object --> +<!-- .XE --> +<!-- .IN "Sme object" "" "@DEF@" --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/Sme.h> +<!-- .IN "Sme.h" "" --> +Class Header file <X11/Xaw/SmeP.h> +<!-- .IN "SmeP.h" "" --> +Class smeObjectClass +<!-- .IN "smeObjectClass" "" --> +Class Name Sme +<!-- .IN "Sme object" "class name" --> +Superclass RectObj +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The Sme object is the base class for all menu entries. While this +object is mainly intended to be subclassed, it may be used in a menu to +add blank space between menu entries. +</para> +<sect2 id="sme_resources"> +<title>Resources</title> +<!-- .IN "SmeLine object" "resources" --> +<para> +<!-- .LP --> +The resources associated with the SmeLine object are defined in this +section, and affect only the single menu entry specified by this object. +There are no new resources added for this class, as it picks up all its +resources from the RectObj class. +</para> +<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>ancestorSensitive</entry> + <entry>AncestorSensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .As --> +<!-- .Dc --> +<!-- .Hw --> + +<para> +Keep in mind that the SimpleMenu widget will force all menu items to +be the width of the widest entry. +<!-- .Ix Bold --> +<!-- .Se --> +</para> +</sect2> +<sect2 id="Subclassing_the_Sme_Object"> +<title>Subclassing the Sme Object</title> +<!-- .IN "Sme object" "subclassing" "@DEF" --> +<para> +<!-- .LP --> +<!-- .sp --> +To Create a new Sme object <emphasis remap='I'>class</emphasis> you will need to define three class methods. +These methods allow the SimpleMenu to highlight and unhighlight the +menu entry as the pointer cursor moves over it, as well as notify the +entry when the user has selected it. All of +these methods may be inherited from the Sme object, although the default +semantics are not very interesting. +</para> +<para> +<variablelist> + <varlistentry> + <term> + <function>Highlight</function>(\|) + </term> + <listitem> + <para> +<!-- .IN "Sme object" "Highlight method" --> +Called to put the menu entry into the highlighted state. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Unhighlight</function>(\|) + </term> + <listitem> + <para> +<!-- .IN "Sme object" "Unhighlight method" --> +Called to return the widget to its normal (unhighlighted) state. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>Notify</function>(\|) + </term> + <listitem> + <para> +<!-- .IN "Sme object" "Notify method" --> +Called when the user selects this menu entry. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .sp --> +Other then these methods, creating a new object +is straight forward. Here is some information that may help you +avoid some common mistakes. +</para> +<orderedlist> + <listitem><para>Objects can be zero pixels high.</para></listitem> + <listitem> + <para> +Objects draw on their parent's window, therefore the Drawing dimensions +are different from those of widgets. For instance, y locations vary +from <function>y</function> to <function>y + height</function>, not <function>0</function> to <function>height</function>. + </para> + </listitem> + <listitem> + <para> +<!-- .IP 3) 3n --> +XtSetValues calls may come from the application while the Sme is highlighted, +and if the SetValues method returns True, will result in an expose event. +The SimpleMenu may later call the menu entry's <function>unhighlight</function> +procedure. However, due to the asynchronous nature of +X, the expose event generated by <function>XtSetValues</function> will come <emphasis remap='I'>after</emphasis> +this unhighlight. + </para> + </listitem> + <listitem> + <para> +Remember that your subclass of the Sme does not own the +window. Share the space with other menu entries, and refrain +from drawing outside the subclass's own section of the menu. + </para> + </listitem> +</orderedlist> +</sect2> +</sect1> diff --git a/libXaw/specs/SmeBSB.xml b/libXaw/specs/SmeBSB.xml new file mode 100644 index 000000000..539bdcb03 --- /dev/null +++ b/libXaw/specs/SmeBSB.xml @@ -0,0 +1,310 @@ +<sect1 id="SmeBSB_Object"> +<title>SmeBSB Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- SmeBSB Object --> +<!-- .XE --> +<!-- .IN "SmeBSB object" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/SmeBSB.h> +<!-- .IN "SmeBSB.h" "" --> +Class Header file <X11/Xaw/SmeBSBP.h> +<!-- .IN "SmeBSBP.h" "" --> +Class smeBSBObjectClass +<!-- .IN "smeBSBObjectClass" "" --> +Class Name SmeBSB +<!-- .IN "SmeBSB object" "class name" --> +Superclass Sme +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The SmeBSB object is used to create a menu entry that contains a string, +and optional bitmaps in its left and right margins. Since each menu +entry is an independent object, the application is able to change the +font, color, height, and other attributes of the menu entries, on an +entry by entry basis. The format of the string may either be the encoding +of the 8 bit <function>font</function> utilized, or in a multi-byte encoding for use with a +<function>fontSet</function>. +</para> +<sect2 id="smebsb_resources"> +<title>Resources</title> +<!-- .IN "SmeBSB object" "resources" --> +<para> +<!-- .LP --> +The resources associated with the SmeBSB object are defined in this section, +and affect only the single menu entry specified by this object. +<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>ancestorSensitive</entry> + <entry>AncestorSensitive</entry> + <entry>Boolean</entry> + <entry>D</entry> + <entry>True</entry> + </row> + <row> + <entry>callback</entry> + <entry>Callback</entry> + <entry>Callback</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>font</entry> + <entry>Font</entry> + <entry>FontStruct</entry> + <entry></entry> + <entry>XtDefaultFont</entry> + </row> + <row> + <entry>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>Font height + <function>vertSpace</function></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>XtjustifyLeft</entry> + </row> + <row> + <entry>label</entry> + <entry>Label</entry> + <entry>String</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>leftBitmap</entry> + <entry>LeftBitmap</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>leftMargin</entry> + <entry>leftMargin</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>rightBitmap</entry> + <entry>RightBitmap</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>rightMargin</entry> + <entry>rightMargin</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>vertSpace</entry> + <entry>VertSpace</entry> + <entry>int</entry> + <entry></entry> + <entry>25</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>TextWidth + margins</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .As --> +<variablelist> + <varlistentry> + <term>callback</term> + <listitem> + <para> +All callback functions on this list are called when the SimpleMenu +<emphasis remap='I'>notifies</emphasis> this entry that the user has selected it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>font</term> + <listitem> + <para> +The text font to use when displaying the <function>label</function>, when the +<function>international</function> resource is <function>false</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>fontSet</term> + <listitem> + <para> +The text font set to use when displaying the <function>label</function>, when the +<function>international</function> resource is <function>true</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>foreground</term> + <listitem> + <para> +A pixel value which indexes the SimpleMenu's colormap to derive the +foreground color of the menu entry's window. This color is also +used to render all 1's in the left and right <function>bitmaps</function>. +<!-- .Hw --> +Keep in mind that the SimpleMenu widget will force the width of all +menu entries to be the width of the longest entry. +<!-- .In --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>justify</term> + <listitem> + <para> +<!-- .IP <function>justify</function> 1.5i --> +How the label is to be rendered between the left and right margins when +the space is wider than the actual text. This resource may be +specified with the values <function>XtJustifyLeft</function>, <function>XtJustifyCenter</function>, +or <function>XtJustifyRight</function>. When specifying the justification from a +resource file the values <function>left</function>, <function>center</function>, or <function>right</function> may be +used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>label</term> + <listitem> + <para> +This is a the string that will be displayed in the menu entry. The +exact location of this string within the bounds of the menu entry is +controlled by the <function>leftMargin</function>, <function>rightMargin</function>, <function>vertSpace</function>, +and <function>justify</function> resources. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>leftBitmap</term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>rightBitmap</term> + <listitem> + <para> +<!-- .IP <function>rightBitmap</function> 1.5i --> +This is a name of a bitmap to display in the left or right margin of the +menu entry. All 1's in the bitmap will be rendered in the foreground +color, and all 0's will be drawn in the background color of the +SimpleMenu widget. It is the +programmers' responsibility to make sure that the menu entry is tall +enough, and the appropriate margin wide enough to accept the bitmap. +If care is not taken the bitmap may extend into another menu entry, or +into this entry's label. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>leftMargin</term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>rightMargin</term> + <listitem> + <para> +This is the amount of space (in pixels) that will be left between the +edge of the menu entry and the label string. +<!-- .Se --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>vertSpace</term> + <listitem> + <para> +This is the amount of vertical padding, expressed as a percentage of +the height of the font, that is to be placed around the label of a +menu entry.. The label and bitmaps are always centered vertically +within the menu. The default value for this +resource (25) causes the default height to be 125% of the height of the +font. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/SmeLine.xml b/libXaw/specs/SmeLine.xml new file mode 100644 index 000000000..e53728c61 --- /dev/null +++ b/libXaw/specs/SmeLine.xml @@ -0,0 +1,148 @@ +<sect1 id="SmeLine_Object"> +<title>SmeLine Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- SmeLine Object --> +<!-- .XE --> +<!-- .IN "SmeLine object" "" "@DEF@" --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/SmeLine.h> +<!-- .IN "SmeLine.h" "" --> +Class Header file <X11/Xaw/SmeLineP.h> +<!-- .IN "SmeLineP.h" "" --> +Class smeLineObjectClass +<!-- .IN "smeLineObjectClass" "" --> +Class Name SmeLine +<!-- .IN "SmeLine object" "class name" --> +Superclass Sme +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The SmeLine object is used to add a horizontal line or menu separator to +a menu. Since each SmeLine is an independent object, the application +is able to change the color, height, and other attributes of the SmeLine +objects on an entry by entry basis. This object is not selectable, and +will not highlight when the pointer cursor is over it. +</para> +<sect2 id="smeline_resources"> +<title>Resources</title> +<!-- .IN "SmeLine object" "resources" --> +<para> +<!-- .LP --> +The resources associated with the SmeLine object are defined in this section, +and affect only the single menu entry specified by this object. +<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>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</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></entry> + <entry><function>lineWidth</function></entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</entry> + </row> + <row> + <entry>lineWidth</entry> + <entry>LineWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + <row> + <entry>stipple</entry> + <entry>Stipple</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>XtUnspecifiedPixmap</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>1</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Dc --> +<variablelist> + <varlistentry> + <term>foreground</term> + <listitem> + <para> +A pixel value which indexes the SimpleMenu's colormap to derive the +foreground color used to draw the separator line. +<!-- .Hw --> +Keep in mind that the SimpleMenu widget will force all menu items to +be the width of the widest entry. Thus, setting the width is generally not +very important. +<!-- .Ix --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>lineWidth</term> + <listitem> + <para> +The width of the horizontal line that is to be displayed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>stipple</term> + <listitem> + <para> +If a bitmap is specified for this resource, the line will be stippled +through it. This allows the menu separator to be rendered as something +more exciting than just a line. For instance, if you define a stipple +that is a chain link, then your menu separators will look like chains. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/StripChart.xml b/libXaw/specs/StripChart.xml new file mode 100644 index 000000000..f51f6fc83 --- /dev/null +++ b/libXaw/specs/StripChart.xml @@ -0,0 +1,435 @@ +<sect1 id="StripChart_Widget"> +<title>StripChart Widget</title> +<!-- .XS --> +<!-- StripChart Widget --> +<!-- .XE --> +<!-- .IN "StripChart widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <Xaw/StripChart.h> +<!-- .IN "StripChart.h" "" --> +Class Header file <Xaw/StripCharP.h> +<!-- .IN "StripCharP.h" "" --> +Class stripChartWidgetClass +<!-- .IN "stripChartWidgetClass" "" --> +Class Name StripChart +<!-- .IN "StripChart widget" "class name" --> +Superclass Simple +<!-- .sp --> +</literallayout> +<para> +<!-- .LP --> +The StripChart widget is used to provide a roughly real +time graphical chart of a single value. For example, +it is used by the common client program <function>xload</function> +to provide a graph of processor load. The StripChart +reads data from an application, and updates the chart +at the <function>update</function> interval specified. +</para> +<sect2 id="stripchart_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a StripChart widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "StripChart 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>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>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</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>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>getValue</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>120</entry> + </row> + <row> + <entry>highlight</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>international</entry> + <entry>International</entry> + <entry>Boolean</entry> + <entry>C</entry> + <entry>False</entry> + </row> + <row> + <entry>jumpScroll</entry> + <entry>JumpScroll</entry> + <entry>int</entry> + <entry>A</entry> + <entry>half the width of the widget</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>minScale</entry> + <entry>Scale</entry> + <entry>int</entry> + <entry></entry> + <entry>1</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>screen</entry> + <entry>Screen</entry> + <entry>Pointer</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>update</entry> + <entry>Interval</entry> + <entry>int</entry> + <entry></entry> + <entry>10</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>120</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> + </tbody> + </tgroup> +</informaltable> +<!-- .Ac --> +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Cm --> +<!-- .Cu --> +<!-- .Cn --> +<!-- .Dp --> +<!-- .Dc --> +<variablelist> + <varlistentry> + <term> + <function>foreground</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +that will be used to draw the graph. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>getValue</function> + </term> + <listitem> + <para> +A list of callback functions to call every <function>update</function> seconds. +This list should contain one function, which returns the +value to be graphed by the StripChart widget. The following +section describes the procedural interface. Behavior when this list has +more than one function is undefined. +<!-- .Hw --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>highlight</function> + </term> + <listitem> + <para> +A pixel value which indexes the widget's colormap to derive the color +that will be used to draw the scale lines on the graph. +<!-- .Ib --> +<!-- .Ix --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>jumpScroll</function> + </term> + <listitem> + <para> +When the graph reaches the right edge of the window it must be +scrolled to the left. This resource specifies the number of pixels +it will jump. Smooth scrolling can be achieved by setting this resource +to 1. +<!-- .Mm --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>minScale</function> + </term> + <listitem> + <para> +The minimum scale for the graph. The number of divisions on the graph +will always be greater than or equal to this value. +<!-- .Pf --> +<!-- .Pb --> +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>update</function> + </term> + <listitem> + <para> +The number of seconds between graph updates. Each update is +represented on the graph as a 1 pixel wide line. Every <function>update</function> seconds +the <function>getValue</function> procedure will be used to get a new graph point, +and this point will be added to the right end of the StripChart. +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Getting_the_StripChart_Value"> +<title>Getting the StripChart Value</title> +<!-- .IN "StripChart widget" "getting the value" --> +<para> +<!-- .LP --> +The StripChart widget will call the application routine passed to it +as the <function>getValue</function> callback function every <function>update</function> seconds to +obtain another point for the StripChart graph. +</para> +<para> +<!-- .LP --> +The calling interface for the <function>getValue</function> callback is: +<!-- .IN "StripChart widget" "getValue callback" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef><function> void</function>(*getValueProc)</funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XtPointer<parameter> client_data</parameter></paramdef> + <paramdef>XtPointer<parameter> value</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the StripChart widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the client data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Returns a pointer to a double. The application should set the address +pointed to by this argument to a double containing the value to be +graphed on the StripChart. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function is used by the StripChart to call an application routine. +The routine will pass the value to be graphed back to the the StripChart +in the <function>value</function> field of this routine. + +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/TPage_Credits.xml b/libXaw/specs/TPage_Credits.xml new file mode 100644 index 000000000..bc07351ab --- /dev/null +++ b/libXaw/specs/TPage_Credits.xml @@ -0,0 +1,90 @@ +<chapter> +<title>Acknowledgments</title> + +<para> +Many thanks go to Ralph Swick (Project Athena / Digital) who has +contributed much time and effort to this widget set. Previous +versions of the widget set are largely due to his time and effort. +Many of the improvements that I have been able to make are because he +provided a solid foundation to build upon. While much of the effort +has been Ralph's, many other people have contributed to the code. +</para> + +<literallayout class="monospaced"> +Mark Ackerman (formerly Project Athena) +Donna Converse (MIT X Consortium) +Jim Fulton (formerly MIT X Consortium) +Loretta Guarino-Reid (Digital WSL) +Charles Haynes (Digital WSL) +Rich Hyde (Digital WSL) +Mary Larson (Digital UEG) +Joel McCormack (Digital WSL) +Ron Newman (formerly Project Athena) +Jeanne Rich (Digital WSL) +Terry Weissman (formerly Digital WSL) +</literallayout> + +<para> +While not much remains of the X10 toolkit, many of the ideas for this +widget set come from that original version. The design and +implementation of the X10 toolkit were done by: +</para> + +<literallayout class="monospaced"> +Mike Gancarz (formerly Digital UEG) +Charles Haynes (Digital WSL) +Phil Karlton (formerly Digital WSL) +Kathleen Langone (Digital UEG) +Mary Larson (Digital UEG) +Ram Rao (Digital UEG) +Smokey Wallace (formerly Digital WSL) +Terry Weissman (formerly Digital WSL) +</literallayout> + +<para> +I have used the formatting ideas, and some of the words from previous +versions of this document. The X11R3 Athena widget document was written by: +</para> + +<literallayout class="monospaced"> +Ralph R. Swick (Project Athena/ Digital) +Terry Weissman (formerly Digital WSL) +Al Mento (Digital UEG) +</literallayout> + +<para> +Putting this manual together was a major task in and of itself. I +would like to thank Ralph Swick, Donna Converse, and Jim Fulton for +taking the time to help convert my technical knowledge into legible +text. A special thanks to Jean Diaz (O'Reilly and Associates) for +spending nearly a month with me working out all the annoying little +details. +</para> + +<literallayout class="monospaced"> +Chris D. Peterson +MIT X Consortium 1989 +</literallayout> + +<para> +The R5 edition of this document has been edited by the research staff of +the MIT X Consortium, with significant contributions by Jim Fulton (NCD). +</para> + +<literallayout class="monospaced"> +Donna Converse +MIT X Consortium 1991 +</literallayout> + +<para> +The R6 edition of this document has been edited to reflect changes +brought about by research staff of the Omron Corporation, with special +recognition to Li Yuhong, Seiji Kuwari, and Hiroshi Kuribayashi for +the X11R5/contrib/lib/Xaw internationalization that inspired this version. +</para> +<literallayout class="monospaced"> +Frank Sheeran +Omron Corporation 1994 +</literallayout> + +</chapter> diff --git a/libXaw/specs/Template.xml b/libXaw/specs/Template.xml new file mode 100644 index 000000000..2d94ca829 --- /dev/null +++ b/libXaw/specs/Template.xml @@ -0,0 +1,407 @@ +<sect2 id="Public_Header_File"> +<title>Public Header File</title> +<para> +The public header file contains declarations that will be required by any +application module that needs to refer to the widget; whether to create +an instance of the class, to perform an +<function>XtSetValues</function> +operation, or to call a public routine implemented by the widget class. +</para> +<para> +<!-- .LP --> +The contents of the Template public header file, +<function>< X11/Xaw/Template.h >, </function> +are: +</para> +<literallayout class="monospaced"> +.. +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/Template.h --> +/* Copyright (c) X Consortium 1987, 1988 */ + +#ifndef _Template_h +#define _Template_h + +/**************************************************************** + * + * Template widget + * + ****************************************************************/ + +/* Resources: + + Name Class RepType Default Value + ---- ----- ------- ------------- + background Background Pixel XtDefaultBackground + border BorderColor Pixel XtDefaultForeground + borderWidth BorderWidth Dimension 1 + destroyCallback Callback Pointer NULL + height Height Dimension 0 + mappedWhenManaged MappedWhenManaged Boolean True + sensitive Sensitive Boolean True + width Width Dimension 0 + x Position Position 0 + y Position Position 0 + +*/ + +/* define any special resource names here that are not in <X11/StringDefs.h> */ + +#define XtNtemplateResource "templateResource" + +#define XtCTemplateResource "TemplateResource" + +/* declare specific TemplateWidget class and instance datatypes */ + +typedef struct _TemplateClassRec* TemplateWidgetClass; +typedef struct _TemplateRec* TemplateWidget; + +/* declare the class constant */ + +extern WidgetClass templateWidgetClass; + +#endif /* _Template_h */ +<!-- .CE --> +</literallayout> +<para> +<!-- .LP --> +<!-- .sp --> +You will notice that most of this file is documentation. The crucial +parts are the last 8 lines where macros for any private resource names +and classes are defined and where the widget class datatypes and class +record pointer are declared. +</para> +<para> +<!-- .LP --> +For the "WindowWidget", we want 2 drawing colors, a callback list for +user input and an +<function>exposeCallback</function> callback list, and we will declare three +convenience procedures, so we need to add +</para> +<literallayout class="monospaced"> +<!-- .LP --> +<!-- .sp --> +<!-- .CB --> +/* Resources: + ... + callback Callback Callback NULL + drawingColor1 Color Pixel XtDefaultForeground + drawingColor2 Color Pixel XtDefaultForeground + exposeCallback Callback Callback NULL + font Font XFontStruct* XtDefaultFont + ... + */ + +#define XtNdrawingColor1 "drawingColor1" +#define XtNdrawingColor2 "drawingColor2" +#define XtNexposeCallback "exposeCallback" + +extern Pixel WindowColor1(\|/* Widget */\|); +extern Pixel WindowColor2(\|/* Widget */\|); +extern Font\ \ WindowFont(\|/* Widget */\|); +<!-- .CE --> +</literallayout> +<para> +<!-- .LP --> +Note that we have chosen to call the input callback list by the generic +name, <function>callback</function>, rather than a specific name. If widgets that define +a single user-input action all choose the same resource name then there +is greater possibility for an application to switch between widgets of +different types. +</para> +</sect2> +<sect2 id="Private_Header_File"> +<title>Private Header File</title> +<para> +<!-- .LP --> +The private header file contains the complete declaration of the class +and instance structures for the widget and any additional private data +that will be required by anticipated subclasses of the widget. +Information in the private header file is normally hidden from the +application and is designed to be accessed only through other public +procedures; e.g. +<function>XtSetValues .</function> +</para> +<para> +<!-- .LP --> +The contents of the Template private header file, +<function>< X11/Xaw/TemplateP.h >, </function> +are: +</para> +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/TemplateP.h --> +<literallayout class="monospaced"> +/* Copyright (c) X Consortium 1987, 1988 + */ + +#ifndef _TemplateP_h +#define _TemplateP_h + +#include <X11/Xaw/Template.h> +/* include superclass private header file */ +#include <X11/CoreP.h> + +/* define unique representation types not found in <X11/StringDefs.h> */ + +#define XtRTemplateResource "TemplateResource" + +typedef struct { + int empty; +} TemplateClassPart; + +typedef struct _TemplateClassRec { + CoreClassPart core_class; + TemplateClassPart template_class; +} TemplateClassRec; + +extern TemplateClassRec templateClassRec; + +typedef struct { + /* resources */ + char* resource; + /* private state */ +} TemplatePart; + +typedef struct _TemplateRec { + CorePart core; + TemplatePart template; +} TemplateRec; + +#endif /* _TemplateP_h */ +<!-- .CE --> +</literallayout> +<para> +The private header file includes the private header file of its +superclass, thereby exposing the entire internal structure of the widget. +It may not always be advantageous to do this; your own project +development style will dictate the appropriate level of detail to expose +in each module. +</para> +<para> +The "WindowWidget" needs to declare two fields in its instance structure to +hold the drawing colors, a resource field for the font and a field for the +expose and user input callback lists: +</para> + +<literallayout class="monospaced"> +typedef struct { + /* resources */ + Pixel color_1; + Pixel color_2; + XFontStruct* font; + XtCallbackList expose_callback; + XtCallbackList input_callback; + /* private state */ + /* (none) */ +} WindowPart; +</literallayout> + +</sect2> +<sect2 id="Widget_Source_File"> +<title>Widget Source File</title> +<para> +<!-- .LP --> +The source code file implements the widget class itself. The unique +part of this file is the declaration and initialization of the +widget class record structure and the declaration of all resources and +action routines added by the widget class. +</para> +<para> +<!-- .LP --> +The contents of the Template implementation file, +<function>< X11/Xaw/Template.c >,</function> +are: +</para> +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/Template.c --> +<literallayout class="monospaced"> +/* Copyright (c) X Consortium 1987, 1988 + */ + +#include <X11/IntrinsicP.h> +#include <X11/StringDefs.h> +#include "TemplateP.h" + +static XtResource resources[] = { +#define offset(field) XtOffsetOf(TemplateRec, template.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, + sizeof(char*), offset(resource), XtRString, (XtPointer) "default" }, +#undef offset +}; + +static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"template", TemplateAction}, +}; + +static char translations[] = +" <Key>: template(\|) \\n\\ +"; + +TemplateClassRec templateClassRec = { + { /* core fields */ + /* superclass */ (WidgetClass) &widgetClassRec, + /* class_name */ "Template", + /* widget_size */ sizeof(TemplateRec), + /* class_initialize */ NULL, + /* class_part_initialize */ NULL, + /* class_inited */ FALSE, + /* initialize */ NULL, + /* initialize_hook */ NULL, + /* realize */ XtInheritRealize, + /* actions */ actions, + /* num_actions */ XtNumber(actions), + /* resources */ resources, + /* num_resources */ XtNumber(resources), + /* xrm_class */ NULLQUARK, + /* compress_motion */ TRUE, + /* compress_exposure */ TRUE, + /* compress_enterleave */ TRUE, + /* visible_interest */ FALSE, + /* destroy */ NULL, + /* resize */ NULL, + /* expose */ NULL, + /* set_values */ NULL, + /* set_values_hook */ NULL, + /* set_values_almost */ XtInheritSetValuesAlmost, + /* get_values_hook */ NULL, + /* accept_focus */ NULL, + /* version */ XtVersion, + /* callback_private */ NULL, + /* tm_table */ translations, + /* query_geometry */ XtInheritQueryGeometry, + /* display_accelerator */ XtInheritDisplayAccelerator, + /* extension */ NULL + }, + { /* template fields */ + /* empty */ 0 + } +}; + +WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; +</literallayout> +<!-- .CE --> +<para> +The resource list for the "WindowWidget" might look like the following: +</para> +<!-- .CB --> +<literallayout class="monospaced"> +static XtResource resources[] = { +#define offset(field) XtOffsetOf(WindowWidgetRec, window.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_1), XtRString, XtDefaultForeground }, + { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_2), XtRString, XtDefaultForeground }, + { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + offset(font), XtRString, XtDefaultFont }, + { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(expose_callback), XtRCallback, NULL }, + { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(input_callback), XtRCallback, NULL }, +#undef offset +}; +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +The user input callback will be implemented by an action procedure which +passes the event pointer as call_data. The action procedure +is declared as: +<!-- .CB --> +</para> +<literallayout class="monospaced"> +/* ARGSUSED */ +static void InputAction(w, event, params, num_params) + Widget w; + XEvent *event; + String *params; /* unused */ + Cardinal *num_params; /* unused */ +{ + XtCallCallbacks(w, XtNcallback, (XtPointer)event); +} + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"input", InputAction}, +}; +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +and the default input binding will be to execute the input callbacks on +<function>KeyPress</function> and <function>ButtonPress : </function> +</para> +<literallayout class="monospaced"> +static char translations[] = +" <Key>: input(\|) \\n\\ + <BtnDown>: input(\|) \\ +"; +</literallayout> +<!-- .CE --> +<para> +In the class record declaration and initialization, the only field that +is different from the Template is the expose procedure: +</para> +<!-- .CB --> +<literallayout class="monospaced"> +/* ARGSUSED */ +static void Redisplay(w, event, region) + Widget w; + XEvent *event; /* unused */ + Region region; +{ + XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region); +} + +WindowClassRec windowClassRec = { + + ... + + /* expose */ Redisplay, +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +<!-- .sp --> +The "WindowWidget" will also declare three public procedures to return the +drawing colors and the font id, saving the application the effort of +constructing an argument list for a call to +<function>XtGetValues :</function> +</para> +<!-- .LP --> +<!-- .CB --> +<literallayout class="monospaced"> +Pixel WindowColor1(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_1; +} + +Pixel WindowColor2(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_2; +} + +Font WindowFont(w) + Widget w; +{ + return ((WindowWidget)w)->window.font->fid; +} +</literallayout> + +<para> +The "WindowWidget" is now complete. The application can retrieve the two +drawing colors from the widget instance by calling either +<function>XtGetValues ,</function> +or the <function>WindowColor</function> functions. The actual window created for the +"WindowWidget" is available by calling the +<function>XtWindow</function> function. +</para> +</sect2> diff --git a/libXaw/specs/Template_private_header_file.xml b/libXaw/specs/Template_private_header_file.xml new file mode 100644 index 000000000..a26e92eef --- /dev/null +++ b/libXaw/specs/Template_private_header_file.xml @@ -0,0 +1,87 @@ +<sect1 id="Private_Header_File"> +<title>Private Header File</title> +<para> +<!-- .LP --> +The private header file contains the complete declaration of the class +and instance structures for the widget and any additional private data +that will be required by anticipated subclasses of the widget. +Information in the private header file is normally hidden from the +application and is designed to be accessed only through other public +procedures; e.g. +<function>XtSetValues .</function> +</para> +<para> +<!-- .LP --> +The contents of the Template private header file, +<function>< X11/Xaw/TemplateP.h >, </function> +are: +</para> +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/TemplateP.h --> +<literallayout class="monospaced"> +/* Copyright (c) X Consortium 1987, 1988 + */ + +#ifndef _TemplateP_h +#define _TemplateP_h + +#include <X11/Xaw/Template.h> +/* include superclass private header file */ +#include <X11/CoreP.h> + +/* define unique representation types not found in <X11/StringDefs.h> */ + +#define XtRTemplateResource "TemplateResource" + +typedef struct { + int empty; +} TemplateClassPart; + +typedef struct _TemplateClassRec { + CoreClassPart core_class; + TemplateClassPart template_class; +} TemplateClassRec; + +extern TemplateClassRec templateClassRec; + +typedef struct { + /* resources */ + char* resource; + /* private state */ +} TemplatePart; + +typedef struct _TemplateRec { + CorePart core; + TemplatePart template; +} TemplateRec; + +#endif /* _TemplateP_h */ +<!-- .CE --> +</literallayout> +<para> +The private header file includes the private header file of its +superclass, thereby exposing the entire internal structure of the widget. +It may not always be advantageous to do this; your own project +development style will dictate the appropriate level of detail to expose +in each module. +</para> +<para> +The "WindowWidget" needs to declare two fields in its instance structure to +hold the drawing colors, a resource field for the font and a field for the +expose and user input callback lists: +</para> + +<literallayout class="monospaced"> +typedef struct { + /* resources */ + Pixel color_1; + Pixel color_2; + XFontStruct* font; + XtCallbackList expose_callback; + XtCallbackList input_callback; + /* private state */ + /* (none) */ +} WindowPart; +</literallayout> + +</sect1> diff --git a/libXaw/specs/Template_public_header_file.xml b/libXaw/specs/Template_public_header_file.xml new file mode 100644 index 000000000..b17379677 --- /dev/null +++ b/libXaw/specs/Template_public_header_file.xml @@ -0,0 +1,112 @@ +<sect1 id="Public_Header_File"> +<title>Public Header File</title> +<para> +The public header file contains declarations that will be required by any +application module that needs to refer to the widget; whether to create +an instance of the class, to perform an +<function>XtSetValues</function> +operation, or to call a public routine implemented by the widget class. +</para> +<para> +<!-- .LP --> +The contents of the Template public header file, +<function>< X11/Xaw/Template.h >, </function> +are: +</para> +<literallayout class="monospaced"> +.. +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/Template.h --> +/* Copyright (c) X Consortium 1987, 1988 */ + +#ifndef _Template_h +#define _Template_h + +/**************************************************************** + * + * Template widget + * + ****************************************************************/ + +/* Resources: + + Name Class RepType Default Value + ---- ----- ------- ------------- + background Background Pixel XtDefaultBackground + border BorderColor Pixel XtDefaultForeground + borderWidth BorderWidth Dimension 1 + destroyCallback Callback Pointer NULL + height Height Dimension 0 + mappedWhenManaged MappedWhenManaged Boolean True + sensitive Sensitive Boolean True + width Width Dimension 0 + x Position Position 0 + y Position Position 0 + +*/ + +/* define any special resource names here that are not in <X11/StringDefs.h> */ + +#define XtNtemplateResource "templateResource" + +#define XtCTemplateResource "TemplateResource" + +/* declare specific TemplateWidget class and instance datatypes */ + +typedef struct _TemplateClassRec* TemplateWidgetClass; +typedef struct _TemplateRec* TemplateWidget; + +/* declare the class constant */ + +extern WidgetClass templateWidgetClass; + +#endif /* _Template_h */ +<!-- .CE --> +</literallayout> +<para> +<!-- .LP --> +<!-- .sp --> +You will notice that most of this file is documentation. The crucial +parts are the last 8 lines where macros for any private resource names +and classes are defined and where the widget class datatypes and class +record pointer are declared. +</para> +<para> +<!-- .LP --> +For the "WindowWidget", we want 2 drawing colors, a callback list for +user input and an +<function>exposeCallback</function> callback list, and we will declare three +convenience procedures, so we need to add +</para> +<literallayout class="monospaced"> +<!-- .LP --> +<!-- .sp --> +<!-- .CB --> +/* Resources: + ... + callback Callback Callback NULL + drawingColor1 Color Pixel XtDefaultForeground + drawingColor2 Color Pixel XtDefaultForeground + exposeCallback Callback Callback NULL + font Font XFontStruct* XtDefaultFont + ... + */ + +#define XtNdrawingColor1 "drawingColor1" +#define XtNdrawingColor2 "drawingColor2" +#define XtNexposeCallback "exposeCallback" + +extern Pixel WindowColor1(\|/* Widget */\|); +extern Pixel WindowColor2(\|/* Widget */\|); +extern Font\ \ WindowFont(\|/* Widget */\|); +<!-- .CE --> +</literallayout> +<para> +<!-- .LP --> +Note that we have chosen to call the input callback list by the generic +name, <function>callback</function>, rather than a specific name. If widgets that define +a single user-input action all choose the same resource name then there +is greater possibility for an application to switch between widgets of +different types. +</para> +</sect1> diff --git a/libXaw/specs/Template_widget_source_file.xml b/libXaw/specs/Template_widget_source_file.xml new file mode 100644 index 000000000..62ad1b69c --- /dev/null +++ b/libXaw/specs/Template_widget_source_file.xml @@ -0,0 +1,208 @@ +<sect1 id="Widget_Source_File"> +<title>Widget Source File</title> +<para> +<!-- .LP --> +The source code file implements the widget class itself. The unique +part of this file is the declaration and initialization of the +widget class record structure and the declaration of all resources and +action routines added by the widget class. +</para> +<para> +<!-- .LP --> +The contents of the Template implementation file, +<function>< X11/Xaw/Template.c >,</function> +are: +</para> +<!-- .CB --> +<!-- .\".so ../../lib/Xaw/Template.c --> +<literallayout class="monospaced"> +/* Copyright (c) X Consortium 1987, 1988 + */ + +#include <X11/IntrinsicP.h> +#include <X11/StringDefs.h> +#include "TemplateP.h" + +static XtResource resources[] = { +#define offset(field) XtOffsetOf(TemplateRec, template.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, + sizeof(char*), offset(resource), XtRString, (XtPointer) "default" }, +#undef offset +}; + +static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"template", TemplateAction}, +}; + +static char translations[] = +" <Key>: template(\|) \\n\\ +"; + +TemplateClassRec templateClassRec = { + { /* core fields */ + /* superclass */ (WidgetClass) &widgetClassRec, + /* class_name */ "Template", + /* widget_size */ sizeof(TemplateRec), + /* class_initialize */ NULL, + /* class_part_initialize */ NULL, + /* class_inited */ FALSE, + /* initialize */ NULL, + /* initialize_hook */ NULL, + /* realize */ XtInheritRealize, + /* actions */ actions, + /* num_actions */ XtNumber(actions), + /* resources */ resources, + /* num_resources */ XtNumber(resources), + /* xrm_class */ NULLQUARK, + /* compress_motion */ TRUE, + /* compress_exposure */ TRUE, + /* compress_enterleave */ TRUE, + /* visible_interest */ FALSE, + /* destroy */ NULL, + /* resize */ NULL, + /* expose */ NULL, + /* set_values */ NULL, + /* set_values_hook */ NULL, + /* set_values_almost */ XtInheritSetValuesAlmost, + /* get_values_hook */ NULL, + /* accept_focus */ NULL, + /* version */ XtVersion, + /* callback_private */ NULL, + /* tm_table */ translations, + /* query_geometry */ XtInheritQueryGeometry, + /* display_accelerator */ XtInheritDisplayAccelerator, + /* extension */ NULL + }, + { /* template fields */ + /* empty */ 0 + } +}; + +WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; +</literallayout> +<!-- .CE --> +<para> +The resource list for the "WindowWidget" might look like the following: +</para> +<!-- .CB --> +<literallayout class="monospaced"> +static XtResource resources[] = { +#define offset(field) XtOffsetOf(WindowWidgetRec, window.field) + /* {name, class, type, size, offset, default_type, default_addr}, */ + { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_1), XtRString, XtDefaultForeground }, + { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), + offset(color_2), XtRString, XtDefaultForeground }, + { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), + offset(font), XtRString, XtDefaultFont }, + { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(expose_callback), XtRCallback, NULL }, + { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), + offset(input_callback), XtRCallback, NULL }, +#undef offset +}; +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +The user input callback will be implemented by an action procedure which +passes the event pointer as call_data. The action procedure +is declared as: +<!-- .CB --> +</para> +<literallayout class="monospaced"> +/* ARGSUSED */ +static void InputAction(w, event, params, num_params) + Widget w; + XEvent *event; + String *params; /* unused */ + Cardinal *num_params; /* unused */ +{ + XtCallCallbacks(w, XtNcallback, (XtPointer)event); +} + +static XtActionsRec actions[] = +{ + /* {name, procedure}, */ + {"input", InputAction}, +}; +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +and the default input binding will be to execute the input callbacks on +<function>KeyPress</function> and <function>ButtonPress : </function> +</para> +<literallayout class="monospaced"> +static char translations[] = +" <Key>: input(\|) \\n\\ + <BtnDown>: input(\|) \\ +"; +</literallayout> +<!-- .CE --> +<para> +In the class record declaration and initialization, the only field that +is different from the Template is the expose procedure: +</para> +<!-- .CB --> +<literallayout class="monospaced"> +/* ARGSUSED */ +static void Redisplay(w, event, region) + Widget w; + XEvent *event; /* unused */ + Region region; +{ + XtCallCallbacks(w, XtNexposeCallback, (XtPointer)region); +} + +WindowClassRec windowClassRec = { + + ... + + /* expose */ Redisplay, +</literallayout> +<!-- .CE --> +<para> +<!-- .LP --> +<!-- .sp --> +The "WindowWidget" will also declare three public procedures to return the +drawing colors and the font id, saving the application the effort of +constructing an argument list for a call to +<function>XtGetValues :</function> +</para> +<!-- .LP --> +<!-- .CB --> +<literallayout class="monospaced"> +Pixel WindowColor1(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_1; +} + +Pixel WindowColor2(w) + Widget w; +{ + return ((WindowWidget)w)->window.color_2; +} + +Font WindowFont(w) + Widget w; +{ + return ((WindowWidget)w)->window.font->fid; +} +</literallayout> + +<para> +The "WindowWidget" is now complete. The application can retrieve the two +drawing colors from the widget instance by calling either +<function>XtGetValues ,</function> +or the <function>WindowColor</function> functions. The actual window created for the +"WindowWidget" is available by calling the +<function>XtWindow</function> function. +</para> +</sect1> diff --git a/libXaw/specs/Text.xml b/libXaw/specs/Text.xml new file mode 100644 index 000000000..3daf7d3e4 --- /dev/null +++ b/libXaw/specs/Text.xml @@ -0,0 +1,326 @@ +<sect1 id="Text_Widget_"> +<title>Text Widget</title> + +<literallayout class="monospaced"> +Application Header file <X11/Xaw/Text.h> +Class Header file <X11/Xaw/TextP.h> +Class textWidgetClass +Class Name Text +Superclass Simple +</literallayout> + + +<para> +The Text widget is the glue that binds all the other pieces together, it +maintains the internal state of the displayed text, and acts as a +mediator between the source and sink. +</para> + +<para> +This section lists the resources that are actually part of the +Text widget, and explains the functionality provided by each. +</para> +<sect2 id="Resources_"> +<title>Resources</title> + +<para> +When creating a Text widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> + +<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>autoFill</entry> + <entry>AutoFill</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>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>bottomMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>colormap</entry> + <entry>Colormap</entry> + <entry>Colormap</entry> + <entry></entry> + <entry>Parent's Colormap</entry> + </row> + <row> + <entry>cursor</entry> + <entry>Cursor</entry> + <entry>Cursor</entry> + <entry></entry> + <entry>XC_xterm</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>displayCaret</entry> + <entry>Output</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>displayPosition</entry> + <entry>TextPosition</entry> + <entry>XawTextPosition</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>Font height + margins</entry> + </row> + <row> + <entry>insensitiveBorder</entry> + <entry>Insensitive</entry> + <entry>Pixmap</entry> + <entry></entry> + <entry>GreyPixmap</entry> + </row> + <row> + <entry>insertPosition</entry> + <entry>TextPosition</entry> + <entry>int</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>leftMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</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>XawTextResizeMode</entry> + <entry></entry> + <entry>XawtextResizeNever</entry> + </row> + <row> + <entry>rightMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>screen</entry> + <entry>Screen</entry> + <entry>Pointer</entry> + <entry>R</entry> + <entry>Parent's Screen</entry> + </row> + <row> + <entry>scrollHorizontal</entry> + <entry>Scroll</entry> + <entry>ScrollMode</entry> + <entry></entry> + <entry>XawtextScrollNever</entry> + </row> + <row> + <entry>scrollVertical</entry> + <entry>Scroll</entry> + <entry>XawTextScrollMode</entry> + <entry></entry> + <entry>XawtextScrollNever</entry> + </row> + <row> + <entry>selectTypes</entry> + <entry>SelectTypes</entry> + <entry>XawTextSelectType*</entry> + <entry></entry> + <entry>See above</entry> + </row> + <row> + <entry>sensitive</entry> + <entry>Sensitive</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>textSink</entry> + <entry>TextSink</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>textSource</entry> + <entry>TextSource</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>topMargin</entry> + <entry>Margin</entry> + <entry>Position</entry> + <entry></entry> + <entry>2</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>See above</entry> + </row> + <row> + <entry>unrealizeCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>100</entry> + </row> + <row> + <entry>wrap</entry> + <entry>Wrap</entry> + <entry>WrapMode</entry> + <entry></entry> + <entry>XawtextWrapNever</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> + </tbody> + </tgroup> +</informaltable> + +</sect2> +</sect1> diff --git a/libXaw/specs/TextActions.xml b/libXaw/specs/TextActions.xml new file mode 100644 index 000000000..0af3bec48 --- /dev/null +++ b/libXaw/specs/TextActions.xml @@ -0,0 +1,976 @@ +<sect2 id="Text_Widget_Actions"> +<title>Text Widget Actions</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "actions" --> +<!-- .XS --> +<!-- Actions Supported by all Text Widgets --> +<!-- .XE --> +<!-- .IN "Text widget" "actions" "@DEF@" --> + +All editing functions are performed by translation manager actions that may +be specified through the <function>translations</function> resource in the Text widget. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i 3i --> +<!-- .ta .5i 2.5i 3i --> +Insert Point Movement Delete + forward-character delete-next-character + backward-character delete-previous-character + forward-word delete-next-word + backward-word delete-previous-word + forward-paragraph delete-selection + backward-paragraph + beginning-of-line + end-of-line Selection + next-line select-word + previous-line select-all + next-page select-start + previous-page select-adjust + beginning-of-file select-end + end-of-file extend-start + scroll-one-line-up extend-adjust + scroll-one-line-down extend-end + insert-selection + + +Miscellaneous New Line + redraw-display newline-and-indent + insert-file newline-and-backup + insert-char newline + insert-string + display-caret + focus-in Kill + focus-in kill-word + search backward-kill-word + multiply kill-selection + form-paragraph kill-to-end-of-line + transpose-characters kill-paragraph + no-op kill-to-end-of-paragraph + XawWMProtocols + reconnect-im +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +Most of the actions take no arguments, and unless otherwise noted you +may assume this to be the case. +</para> +<para> +<!-- .LP --> +</para> +<sect3 id="Cursor_Movement_Actions_fP"> +<title>Cursor Movement Actions\fP</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + forward-character() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-character() + </term> + <listitem> + <para> +These actions move the insert point forward or backward one character in +the buffer. If the insert point is at the end or beginning of a line +this action will move the insert point to the next (or previous) line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + forward-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-word() + </term> + <listitem> + <para> +These actions move the insert point to the next or previous word boundary. +A word boundary is defined as a Space, Tab or Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + forward-paragraph() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-paragraph() + </term> + <listitem> + <para> +These actions move the insert point to the next or previous paragraph boundary. +A paragraph boundary is defined as two Carriage Returns in a row with only +Spaces or Tabs between them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + beginning-of-line() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + end-of-line() + </term> + <listitem> + <para> +These actions move to the beginning or end of the current line. If the +insert point is already at the end or beginning of the line then no action is taken. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + next-line() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + previous-line() + </term> + <listitem> + <para> +These actions move the insert point up or down one line. If the insert +point is currently N characters from the beginning of the line then it +will be N characters from the beginning of the next or previous line. +If N is past the end of the line, the insert point is placed at the end +of the line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + next-page() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + previous-page() + </term> + <listitem> + <para> +These actions move the insert point up or down one page in the file. +One page is defined as the current height of the text widget. The +insert point is always placed at the first character of the top line by +this action. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + beginning-of-file() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + end-of-file() + </term> + <listitem> + <para> +These actions place the insert point at the beginning or end of the +current text buffer. The text widget is then scrolled the minimum +amount necessary to make the new insert point location visible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + scroll-one-line-up() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + scroll-one-line-down() + </term> + <listitem> + <para> +These actions scroll the current text field up or down by one line. +They do not move the insert point. Other than the scrollbars this is +the only way that the insert point may be moved off of the visible text +area. The widget will be scrolled so that the insert point is back on +the screen as soon as some other action is executed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Delete_Actions"> +<title>Delete Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + delete-next-character() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-previous-character() + </term> + <listitem> + <para> +These actions remove the character immediately before or after the +insert point. If a Carriage Return is removed then the next line is +appended to the end of the current line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-next-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-previous-word() + </term> + <listitem> + <para> +These actions remove all characters between the insert point location and +the next word boundary. A word boundary is defined as a Space, Tab or +Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-selection() + </term> + <listitem> + <para> +This action removes all characters in the current selection. +The selection can be set with the selection actions. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Selection_Actions"> +<title>Selection Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + select-word() + </term> + <listitem> + <para> +This action selects the word in which the insert point is currently located. +If the insert point is between words then it will select the previous word. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-all() + </term> + <listitem> + <para> +This action selects the entire text buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-start() + </term> + <listitem> + <para> +This action sets the insert point to the current pointer location (if +triggered by a button event) or text cursor location (if triggered by +a key event). It +will then begin a selection at this location. If many of these +selection actions occur quickly in succession then the selection count +mechanism will be invoked (see the section titled \fBText Selections for +Application Programmers\fP for details). <!-- xref --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-adjust() + </term> + <listitem> + <para> +This action allows a selection started with the <emphasis remap='I'>select-start</emphasis> +action to be modified, as described above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action ends a text selection that began with the <emphasis remap='I'>select-start</emphasis> +action, and asserts ownership of the selection or selections specified. +A <emphasis remap='I'>name</emphasis> can be a selection (e.g., <function>PRIMARY</function>) or a cut buffer +(e.g., <function>CUT_BUFFER0</function>). Note that case is important. If no +<emphasis remap='I'>names</emphasis> are specified, <function>PRIMARY</function> is asserted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-start() + </term> + <listitem> + <para> +This action finds the nearest end of the current selection, and moves it +to the current pointer location (if triggered by a button event) or text +cursor location (if triggered by a key event). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-adjust() + </term> + <listitem> + <para> +This action allows a selection started with an <emphasis remap='I'>extend-start</emphasis> action +to be modified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action ends a text selection that began with the <emphasis remap='I'>extend-start</emphasis> +action, and asserts ownership of the selection or selections specified. +A <emphasis remap='I'>name</emphasis> can be a selection (e.g. <function>PRIMARY</function>) or a cut buffer +(e.g <function>CUT_BUFFER0</function>). Note that case is important. If no names are +given, <function>PRIMARY</function> is asserted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-selection(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action retrieves the value of the first (left-most) named selection +that exists or the cut buffer that is not empty and inserts it into the +Text widget at the current insert point location. A <emphasis remap='I'>name</emphasis> can be a +selection (e.g. <function>PRIMARY</function>) or a cut buffer (e.g <function>CUT_BUFFER0</function>). +Note that case is important. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="The_New_Line_Actions"> +<title>The New Line Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + newline-and-indent() + </term> + <listitem> + <para> +This action inserts a newline into the text and adds spaces to +that line to indent it to match the previous line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + newline-and-backup() + </term> + <listitem> + <para> +This action inserts a newline into the text <emphasis remap='I'>after</emphasis> the insert point. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + newline() + </term> + <listitem> + <para> +This action inserts a newline into the text <emphasis remap='I'>before</emphasis> the insert point. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Kill_and_Actions"> +<title>Kill and Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + kill-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-kill-word() + </term> + <listitem> + <para> +These actions act exactly like the <emphasis remap='I'>delete-next-word</emphasis> and +<emphasis remap='I'>delete-previous-word</emphasis> actions, but they stuff the word that was +killed into the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-selection() + </term> + <listitem> + <para> +This action deletes the current selection and stuffs the deleted text into +the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-to-end-of-line() + </term> + <listitem> + <para> +This action deletes the entire line to the right of the insert point position, +and stuffs the deleted text into the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-paragraph() + </term> + <listitem> + <para> +This action deletes the current paragraph, if between paragraphs it deletes +the paragraph above the insert point, and stuffs the deleted text into +the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-to-end-of-paragraph() + </term> + <listitem> + <para> +This action deletes everything between the current insert point location and +the next paragraph boundary, and stuffs the deleted text into the kill +buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Miscellaneous_Actions"> +<title>Miscellaneous Actions</title> +<para> +<!-- .LP --> +<!-- .sp 1 --> +<variablelist> + <varlistentry> + <term> + redraw-display() + </term> + <listitem> + <para> +This action recomputes the location of all the text lines on the +display, scrolls the text to vertically center the line containing the insert point +on the screen, clears the entire screen, and redisplays it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-file([<emphasis remap='I'>filename</emphasis>]) + </term> + <listitem> + <para> +This action activates the insert file popup. The <emphasis remap='I'>filename</emphasis> +option specifies the default filename to put in the filename buffer of +the popup. If no <emphasis remap='I'>filename</emphasis> is specified the buffer is empty +at startup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-char() + </term> + <listitem> + <para> +This action may only be attached to a key event. When the +<function>international</function> resource is <function>false</function>, this action +calls XLookupString to translate the event into a (rebindable) Latin-1 +character (sequence) and inserts it into the text at the +insert point. When the <function>international</function> resource is <function>true</function>, +characters are passed to the input method via XwcLookupString, and any +committed string returned is inserted into the text at the insert point. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-string(<emphasis remap='I'>string</emphasis>[,<emphasis remap='I'>string</emphasis>,...]) + </term> + <listitem> + <para> +This action inserts each <emphasis remap='I'>string</emphasis> into the text +at the insert point location. Any <emphasis remap='I'>string</emphasis> +beginning with the characters "0x" followed by an even +number of hexadecimal digits is +interpreted as a hexadecimal constant and the +corresponding string is inserted instead. This +hexadecimal string may represent up to 50 8-bit characters. + When the<function>international</function> resource is +<function>true</function>, a hexadecimal string is intrepeted as +being in a multi-byte encoding, and a hexadecimal +or regular string will result in an error message +if it is not legal in the current locale. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + display-caret(<emphasis remap='I'>state</emphasis>,<emphasis remap='I'>when</emphasis>) + </term> + <listitem> + <para> +This action allows the insert point to be turned on and off. +The <emphasis remap='I'>state</emphasis> argument specifies the desired state of the insert point. +This value may be any of the string +values accepted for Boolean resources (e.g. <function>on</function>, <function>True</function>, +<function>off</function>, <function>False</function>, etc.). If no arguments are specified, the +default value is <function>True</function>. +The <emphasis remap='I'>when</emphasis> argument specifies, for <function>EnterNotify</function> or <function>LeaveNotify</function> +events whether or not the focus field in the event is to be examined. +If the second argument is not specified, or specified as something other +than <function>always</function> then if the action is bound to an <function>EnterNotify</function> +or <function>LeaveNotify</function> event, the action will be taken only if the focus +field is <function>True</function>. An augmented binding that might be useful is: + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i 2.5i 4.0i --> +<!-- .ta 2.0i 2.5i 4.0i --> + *Text.Translations: #override \\ + <FocusIn>: display-caret(on) \\n\\ + <FocusOut>: display-caret(off) +</literallayout> +<variablelist> + <varlistentry> + <term> + focus-in() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + focus-out() + </term> + <listitem> + <para> +These actions do not currently do anything. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + search(<emphasis remap='I'>direction</emphasis>,[<emphasis remap='I'>string</emphasis>]) + </term> + <listitem> + <para> +This action activates the search popup. The <emphasis remap='I'>direction</emphasis> must be +specified as either <function>forward</function> or <function>backward</function>. The string is +optional and is used as an initial value for the <emphasis remap='I'>Search for</emphasis>: string. +For further explanation of the search widget see the section on +<function>Text Searches</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + multiply(<emphasis remap='I'>value</emphasis>) + </term> + <listitem> + <para> +The multiply action allows the user to multiply the effects of many of +the text actions. Thus the following action sequence +<emphasis remap='I'>multiply(10) delete-next-word()</emphasis> will delete 10 words. It does not +matter whether these actions take place in one event or many events. +Using the default translations the key sequence \fIControl-u, +Control-d\fP will delete 4 characters. +Multiply actions can be chained, thus \fImultiply(5) +multiply(5)\fP is the same as <emphasis remap='I'>multiply(25)</emphasis>. If the string +<function>reset</function> is passed to the multiply action the effects of all previous +multiplies are removed and a beep is sent to the display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + form-paragraph() + </term> + <listitem> + <para> +This action removes all the Carriage Returns from the current +paragraph and reinserts them so that each line is as long as possible, while +still fitting on the current screen. Lines are broken at word boundaries if +at all possible. This action currently works only on Text widgets +that use ASCII text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + transpose-characters() + </term> + <listitem> + <para> +This action will swap the position of the character to the left of the +insert point with the character to the right of the insert point. The insert point will then +be advanced one character. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + no-op([<emphasis remap='I'>action</emphasis>]) + </term> + <listitem> + <para> +The no-op action makes no change to the text widget, and is mainly used +to override translations. This action takes one optional argument. If +this argument is <emphasis remap='I'>RingBell</emphasis> then a beep is sent to the display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + XawWMProtocols([<emphasis remap='I'>wm_protocol_name</emphasis>]) + </term> + <listitem> + <para> +<!-- .IN "XawWMProtocols" --> +<!-- .sp --> +This action is written specifically for the file insertion and the search +and replace +dialog boxes. This action is attached to those shells by the Text widget, +in order to handle ClientMessage events with the WM_PROTOCOLS atom in the +detail field. This action supports WM_DELETE_WINDOW on the Text widget +popups, and may support other window manager protocols if necessary in +the future. The popup will be dismissed if the window manager sends +a WM_DELETE_WINDOW request and there are no parameters in the action +call, which is the default. The popup will also be dismissed if the +parameters include the string ``wm_delete_window,'' and the event is a +ClientMessage event requesting dismissal or is not a ClientMessage event. +This action is not sensitive to the case of the strings passed as parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + reconnect-im() + </term> + <listitem> + <para> +<!-- .IN "Input Method" --> +When the <function>international</function> resource is <function>true</function>, +input is usually passed to an input method, a separate +process, for composing. Sometimes the connection to +this process gets severed; this action will attempt to +reconnect it. Causes for severage include network +trouble, and the user explicitly killing one input +method and starting a new one. This action may also +establish first connection when the application is +started before the input method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect3> +<sect3 id="Text_Selections_for_Application_Programmers"> +<title>Text Selections for Application Programmers</title> +<!-- .IN "Text widget" "Text Selections for Application Programmers" --> +<para> +<!-- .LP --> +The default behavior of the text selection array is described in the +section called <function>Text Selections for Users</function>. To modify the selections +a programmer must construct a <function>XawTextSelectType</function> array (called the +selection array), containing the selections desired, and pass this as +the new value for the <function>selectionTypes</function> resource. The selection +array may also be modified using the <function>XawTextSetSelectionArray</function> +<!-- .IN "XawTextSetSelectionArray" "" --> +function. All selection arrays must end with the value +<function>XawselectNull</function>. The <function>selectionTypes</function> resource has no converter +registered and cannot be modified through the resource manager. +</para> +<para> +<!-- .LP --> +The array contains a list of entries that will be called when the user +attempts to select text in rapid succession with the <emphasis remap='I'>select-start</emphasis> +action (usually by clicking a pointer button). The first entry in the +selection array will be used when the <emphasis remap='I'>select-start</emphasis> action is +initially called. The next entry will be used when <emphasis remap='I'>select-start</emphasis> +is called again, and so on. If a timeout value (1/10 of a second) is +exceeded, the the next <emphasis remap='I'>select-start</emphasis> action will begin at the top +of the selection array. When <function>XawselectNull</function> is reached the array +is recycled beginning with the first element. + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XawselectAll</function></entry> + <entry>Selects the contents of the entire buffer.</entry> + </row> + <row> + <entry><function>XawselectChar</function></entry> + <entry>Selects text characters as the pointer moves over them.</entry> + </row> + <row> + <entry><function>XawselectLine</function></entry> + <entry>Selects the entire line.</entry> + </row> + <row> + <entry><function>XawselectNull</function></entry> + <entry>Indicates the end of the selection array.</entry> + </row> + <row> + <entry><function>XawselectParagraph</function></entry> + <entry>Selects the entire paragraph.</entry> + </row> + <row> + <entry><function>XawselectPosition</function></entry> + <entry>Selects the current pointer position.</entry> + </row> + <row> + <entry><function>XawselectWord</function></entry> + <entry>Selects whole words as the pointer moves onto them.</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<para> +<!-- .LP --> +The default selectType array is: +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull} +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The selection array is not copied by the text widgets. The +application must allocate space for the array and cannot deallocate or +change it until the text widget is destroyed or until a new selection +array is set. +</para> +</sect3> +</sect2> +<sect2 id="Default_Translation_Bindings"> +<title>Default Translation Bindings</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Default Translation Bindings --> +<!-- .XE --> +<!-- .IN "Text widget" "default translations" --> +The following translations are defaults built into every Text widget. +They can be overridden, or replaced by specifying a new value for the +Text widget's <function>translations</function> resource. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> + Ctrl<Key>A: beginning-of-line() \\n\\ + Ctrl<Key>B: backward-character() \\n\\ + Ctrl<Key>D: delete-next-character() \\n\\ + Ctrl<Key>E: end-of-line() \\n\\ + Ctrl<Key>F: forward-character() \\n\\ + Ctrl<Key>G: multiply(Reset) \\n\\ + Ctrl<Key>H: delete-previous-character() \\n\\ + Ctrl<Key>J: newline-and-indent() \\n\\ + Ctrl<Key>K: kill-to-end-of-line() \\n\\ + Ctrl<Key>L: redraw-display() \\n\\ + Ctrl<Key>M: newline() \\n\\ + Ctrl<Key>N: next-line() \\n\\ + Ctrl<Key>O: newline-and-backup() \\n\\ + Ctrl<Key>P: previous-line() \\n\\ + Ctrl<Key>R: search(backward) \\n\\ + Ctrl<Key>S: search(forward) \\n\\ + Ctrl<Key>T: transpose-characters() \\n\\ + Ctrl<Key>U: multiply(4) \\n\\ + Ctrl<Key>V: next-page() \\n\\ + Ctrl<Key>W: kill-selection() \\n\\ + Ctrl<Key>Y: insert-selection(CUT_BUFFER1) \\n\\ + Ctrl<Key>Z: scroll-one-line-up() \\n\\ + Ctrl<Key>\\: reconnect-im() \\n\\ + Meta<Key>B: backward-word() \\n\\ + Meta<Key>F: forward-word() \\n\\ + Meta<Key>I: insert-file() \\n\\ + Meta<Key>K: kill-to-end-of-paragraph() \\n\\ + Meta<Key>Q: form-paragraph() \\n\\ + Meta<Key>V: previous-page() \\n\\ + Meta<Key>Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ + Meta<Key>Z: scroll-one-line-down() \\n\\ + :Meta<Key>d: delete-next-word() \\n\\ + :Meta<Key>D: kill-word() \\n\\ + :Meta<Key>h: delete-previous-word() \\n\\ + :Meta<Key>H: backward-kill-word() \\n\\ + :Meta<Key>\\<: beginning-of-file() \\n\\ + :Meta<Key>\\>: end-of-file() \\n\\ + :Meta<Key>]: forward-paragraph() \\n\\ + :Meta<Key>[: backward-paragraph() \\n\\ + ~Shift Meta<Key>Delete: delete-previous-word() \\n\\ + \ Shift Meta<Key>Delete: backward-kill-word() \\n\\ + ~Shift Meta<Key>Backspace: delete-previous-word() \\n\\ + \ Shift Meta<Key>Backspace: backward-kill-word() \\n\\ + <Key>Right: forward-character() \\n\\ + <Key>Left: backward-character() \\n\\ + <Key>Down: next-line() \\n\\ + <Key>Up: previous-line() \\n\\ + <Key>Delete: delete-previous-character() \\n\\ + <Key>BackSpace: delete-previous-character() \\n\\ + <Key>Linefeed: newline-and-indent() \\n\\ + <Key>Return: newline() \\n\\ + <Key>: insert-char() \\n\\ + <Key>Kanji: reconnect-im() \\n\\ + <FocusIn>: focus-in() \\n\\ + <FocusOut>: focus-out() \\n\\ + <Btn1Down>: select-start() \\n\\ + <Btn1Motion>: extend-adjust() \\n\\ + <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\ + <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ + <Btn3Down>: extend-start() \\n\\ + <Btn3Motion>: extend-adjust() \\n\\ + <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n +</literallayout> + + +</para> +</sect2> diff --git a/libXaw/specs/TextActions_default_translation_bindings.xml b/libXaw/specs/TextActions_default_translation_bindings.xml new file mode 100644 index 000000000..731881104 --- /dev/null +++ b/libXaw/specs/TextActions_default_translation_bindings.xml @@ -0,0 +1,85 @@ +<sect1 id="Default_Translation_Bindings"> +<title>Default Translation Bindings</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Default Translation Bindings --> +<!-- .XE --> +<!-- .IN "Text widget" "default translations" --> +The following translations are defaults built into every Text widget. +They can be overridden, or replaced by specifying a new value for the +Text widget's <function>translations</function> resource. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> + Ctrl<Key>A: beginning-of-line() \\n\\ + Ctrl<Key>B: backward-character() \\n\\ + Ctrl<Key>D: delete-next-character() \\n\\ + Ctrl<Key>E: end-of-line() \\n\\ + Ctrl<Key>F: forward-character() \\n\\ + Ctrl<Key>G: multiply(Reset) \\n\\ + Ctrl<Key>H: delete-previous-character() \\n\\ + Ctrl<Key>J: newline-and-indent() \\n\\ + Ctrl<Key>K: kill-to-end-of-line() \\n\\ + Ctrl<Key>L: redraw-display() \\n\\ + Ctrl<Key>M: newline() \\n\\ + Ctrl<Key>N: next-line() \\n\\ + Ctrl<Key>O: newline-and-backup() \\n\\ + Ctrl<Key>P: previous-line() \\n\\ + Ctrl<Key>R: search(backward) \\n\\ + Ctrl<Key>S: search(forward) \\n\\ + Ctrl<Key>T: transpose-characters() \\n\\ + Ctrl<Key>U: multiply(4) \\n\\ + Ctrl<Key>V: next-page() \\n\\ + Ctrl<Key>W: kill-selection() \\n\\ + Ctrl<Key>Y: insert-selection(CUT_BUFFER1) \\n\\ + Ctrl<Key>Z: scroll-one-line-up() \\n\\ + Ctrl<Key>\\: reconnect-im() \\n\\ + Meta<Key>B: backward-word() \\n\\ + Meta<Key>F: forward-word() \\n\\ + Meta<Key>I: insert-file() \\n\\ + Meta<Key>K: kill-to-end-of-paragraph() \\n\\ + Meta<Key>Q: form-paragraph() \\n\\ + Meta<Key>V: previous-page() \\n\\ + Meta<Key>Y: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ + Meta<Key>Z: scroll-one-line-down() \\n\\ + :Meta<Key>d: delete-next-word() \\n\\ + :Meta<Key>D: kill-word() \\n\\ + :Meta<Key>h: delete-previous-word() \\n\\ + :Meta<Key>H: backward-kill-word() \\n\\ + :Meta<Key>\\<: beginning-of-file() \\n\\ + :Meta<Key>\\>: end-of-file() \\n\\ + :Meta<Key>]: forward-paragraph() \\n\\ + :Meta<Key>[: backward-paragraph() \\n\\ + ~Shift Meta<Key>Delete: delete-previous-word() \\n\\ + \ Shift Meta<Key>Delete: backward-kill-word() \\n\\ + ~Shift Meta<Key>Backspace: delete-previous-word() \\n\\ + \ Shift Meta<Key>Backspace: backward-kill-word() \\n\\ + <Key>Right: forward-character() \\n\\ + <Key>Left: backward-character() \\n\\ + <Key>Down: next-line() \\n\\ + <Key>Up: previous-line() \\n\\ + <Key>Delete: delete-previous-character() \\n\\ + <Key>BackSpace: delete-previous-character() \\n\\ + <Key>Linefeed: newline-and-indent() \\n\\ + <Key>Return: newline() \\n\\ + <Key>: insert-char() \\n\\ + <Key>Kanji: reconnect-im() \\n\\ + <FocusIn>: focus-in() \\n\\ + <FocusOut>: focus-out() \\n\\ + <Btn1Down>: select-start() \\n\\ + <Btn1Motion>: extend-adjust() \\n\\ + <Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\ + <Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ + <Btn3Down>: extend-start() \\n\\ + <Btn3Motion>: extend-adjust() \\n\\ + <Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n +</literallayout> + + +</para> +</sect1> diff --git a/libXaw/specs/TextActions_text_widget_actions.xml b/libXaw/specs/TextActions_text_widget_actions.xml new file mode 100644 index 000000000..238727698 --- /dev/null +++ b/libXaw/specs/TextActions_text_widget_actions.xml @@ -0,0 +1,891 @@ +<sect1 id="Text_Widget_Actions"> +<title>Text Widget Actions</title> +<para> +<!-- .LP --> +<!-- .IN "Text widget" "actions" --> +<!-- .XS --> +<!-- Actions Supported by all Text Widgets --> +<!-- .XE --> +<!-- .IN "Text widget" "actions" "@DEF@" --> + +All editing functions are performed by translation manager actions that may +be specified through the <function>translations</function> resource in the Text widget. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i 3i --> +<!-- .ta .5i 2.5i 3i --> +Insert Point Movement Delete + forward-character delete-next-character + backward-character delete-previous-character + forward-word delete-next-word + backward-word delete-previous-word + forward-paragraph delete-selection + backward-paragraph + beginning-of-line + end-of-line Selection + next-line select-word + previous-line select-all + next-page select-start + previous-page select-adjust + beginning-of-file select-end + end-of-file extend-start + scroll-one-line-up extend-adjust + scroll-one-line-down extend-end + insert-selection + + +Miscellaneous New Line + redraw-display newline-and-indent + insert-file newline-and-backup + insert-char newline + insert-string + display-caret + focus-in Kill + focus-in kill-word + search backward-kill-word + multiply kill-selection + form-paragraph kill-to-end-of-line + transpose-characters kill-paragraph + no-op kill-to-end-of-paragraph + XawWMProtocols + reconnect-im +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +Most of the actions take no arguments, and unless otherwise noted you +may assume this to be the case. +</para> +<para> +<!-- .LP --> +</para> +<sect2 id="Cursor_Movement_Actions_fP"> +<title>Cursor Movement Actions\fP</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + forward-character() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-character() + </term> + <listitem> + <para> +These actions move the insert point forward or backward one character in +the buffer. If the insert point is at the end or beginning of a line +this action will move the insert point to the next (or previous) line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + forward-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-word() + </term> + <listitem> + <para> +These actions move the insert point to the next or previous word boundary. +A word boundary is defined as a Space, Tab or Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + forward-paragraph() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-paragraph() + </term> + <listitem> + <para> +These actions move the insert point to the next or previous paragraph boundary. +A paragraph boundary is defined as two Carriage Returns in a row with only +Spaces or Tabs between them. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + beginning-of-line() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + end-of-line() + </term> + <listitem> + <para> +These actions move to the beginning or end of the current line. If the +insert point is already at the end or beginning of the line then no action is taken. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + next-line() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + previous-line() + </term> + <listitem> + <para> +These actions move the insert point up or down one line. If the insert +point is currently N characters from the beginning of the line then it +will be N characters from the beginning of the next or previous line. +If N is past the end of the line, the insert point is placed at the end +of the line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + next-page() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + previous-page() + </term> + <listitem> + <para> +These actions move the insert point up or down one page in the file. +One page is defined as the current height of the text widget. The +insert point is always placed at the first character of the top line by +this action. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + beginning-of-file() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + end-of-file() + </term> + <listitem> + <para> +These actions place the insert point at the beginning or end of the +current text buffer. The text widget is then scrolled the minimum +amount necessary to make the new insert point location visible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + scroll-one-line-up() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + scroll-one-line-down() + </term> + <listitem> + <para> +These actions scroll the current text field up or down by one line. +They do not move the insert point. Other than the scrollbars this is +the only way that the insert point may be moved off of the visible text +area. The widget will be scrolled so that the insert point is back on +the screen as soon as some other action is executed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Delete_Actions"> +<title>Delete Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + delete-next-character() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-previous-character() + </term> + <listitem> + <para> +These actions remove the character immediately before or after the +insert point. If a Carriage Return is removed then the next line is +appended to the end of the current line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-next-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-previous-word() + </term> + <listitem> + <para> +These actions remove all characters between the insert point location and +the next word boundary. A word boundary is defined as a Space, Tab or +Carriage Return. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + delete-selection() + </term> + <listitem> + <para> +This action removes all characters in the current selection. +The selection can be set with the selection actions. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Selection_Actions"> +<title>Selection Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + select-word() + </term> + <listitem> + <para> +This action selects the word in which the insert point is currently located. +If the insert point is between words then it will select the previous word. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-all() + </term> + <listitem> + <para> +This action selects the entire text buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-start() + </term> + <listitem> + <para> +This action sets the insert point to the current pointer location (if +triggered by a button event) or text cursor location (if triggered by +a key event). It +will then begin a selection at this location. If many of these +selection actions occur quickly in succession then the selection count +mechanism will be invoked (see the section titled \fBText Selections for +Application Programmers\fP for details). <!-- xref --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-adjust() + </term> + <listitem> + <para> +This action allows a selection started with the <emphasis remap='I'>select-start</emphasis> +action to be modified, as described above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + select-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action ends a text selection that began with the <emphasis remap='I'>select-start</emphasis> +action, and asserts ownership of the selection or selections specified. +A <emphasis remap='I'>name</emphasis> can be a selection (e.g., <function>PRIMARY</function>) or a cut buffer +(e.g., <function>CUT_BUFFER0</function>). Note that case is important. If no +<emphasis remap='I'>names</emphasis> are specified, <function>PRIMARY</function> is asserted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-start() + </term> + <listitem> + <para> +This action finds the nearest end of the current selection, and moves it +to the current pointer location (if triggered by a button event) or text +cursor location (if triggered by a key event). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-adjust() + </term> + <listitem> + <para> +This action allows a selection started with an <emphasis remap='I'>extend-start</emphasis> action +to be modified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + extend-end(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action ends a text selection that began with the <emphasis remap='I'>extend-start</emphasis> +action, and asserts ownership of the selection or selections specified. +A <emphasis remap='I'>name</emphasis> can be a selection (e.g. <function>PRIMARY</function>) or a cut buffer +(e.g <function>CUT_BUFFER0</function>). Note that case is important. If no names are +given, <function>PRIMARY</function> is asserted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-selection(<emphasis remap='I'>name</emphasis>[,<emphasis remap='I'>name</emphasis>,...]) + </term> + <listitem> + <para> +This action retrieves the value of the first (left-most) named selection +that exists or the cut buffer that is not empty and inserts it into the +Text widget at the current insert point location. A <emphasis remap='I'>name</emphasis> can be a +selection (e.g. <function>PRIMARY</function>) or a cut buffer (e.g <function>CUT_BUFFER0</function>). +Note that case is important. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="The_New_Line_Actions"> +<title>The New Line Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + newline-and-indent() + </term> + <listitem> + <para> +This action inserts a newline into the text and adds spaces to +that line to indent it to match the previous line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + newline-and-backup() + </term> + <listitem> + <para> +This action inserts a newline into the text <emphasis remap='I'>after</emphasis> the insert point. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + newline() + </term> + <listitem> + <para> +This action inserts a newline into the text <emphasis remap='I'>before</emphasis> the insert point. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Kill_and_Actions"> +<title>Kill and Actions</title> +<para> +<!-- .LP --> +<!-- .sp --> +<variablelist> + <varlistentry> + <term> + kill-word() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + backward-kill-word() + </term> + <listitem> + <para> +These actions act exactly like the <emphasis remap='I'>delete-next-word</emphasis> and +<emphasis remap='I'>delete-previous-word</emphasis> actions, but they stuff the word that was +killed into the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-selection() + </term> + <listitem> + <para> +This action deletes the current selection and stuffs the deleted text into +the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-to-end-of-line() + </term> + <listitem> + <para> +This action deletes the entire line to the right of the insert point position, +and stuffs the deleted text into the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-paragraph() + </term> + <listitem> + <para> +This action deletes the current paragraph, if between paragraphs it deletes +the paragraph above the insert point, and stuffs the deleted text into +the kill buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + kill-to-end-of-paragraph() + </term> + <listitem> + <para> +This action deletes everything between the current insert point location and +the next paragraph boundary, and stuffs the deleted text into the kill +buffer (<function>CUT_BUFFER_1</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Miscellaneous_Actions"> +<title>Miscellaneous Actions</title> +<para> +<!-- .LP --> +<!-- .sp 1 --> +<variablelist> + <varlistentry> + <term> + redraw-display() + </term> + <listitem> + <para> +This action recomputes the location of all the text lines on the +display, scrolls the text to vertically center the line containing the insert point +on the screen, clears the entire screen, and redisplays it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-file([<emphasis remap='I'>filename</emphasis>]) + </term> + <listitem> + <para> +This action activates the insert file popup. The <emphasis remap='I'>filename</emphasis> +option specifies the default filename to put in the filename buffer of +the popup. If no <emphasis remap='I'>filename</emphasis> is specified the buffer is empty +at startup. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-char() + </term> + <listitem> + <para> +This action may only be attached to a key event. When the +<function>international</function> resource is <function>false</function>, this action +calls XLookupString to translate the event into a (rebindable) Latin-1 +character (sequence) and inserts it into the text at the +insert point. When the <function>international</function> resource is <function>true</function>, +characters are passed to the input method via XwcLookupString, and any +committed string returned is inserted into the text at the insert point. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + insert-string(<emphasis remap='I'>string</emphasis>[,<emphasis remap='I'>string</emphasis>,...]) + </term> + <listitem> + <para> +This action inserts each <emphasis remap='I'>string</emphasis> into the text +at the insert point location. Any <emphasis remap='I'>string</emphasis> +beginning with the characters "0x" followed by an even +number of hexadecimal digits is +interpreted as a hexadecimal constant and the +corresponding string is inserted instead. This +hexadecimal string may represent up to 50 8-bit characters. + When the<function>international</function> resource is +<function>true</function>, a hexadecimal string is intrepeted as +being in a multi-byte encoding, and a hexadecimal +or regular string will result in an error message +if it is not legal in the current locale. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + display-caret(<emphasis remap='I'>state</emphasis>,<emphasis remap='I'>when</emphasis>) + </term> + <listitem> + <para> +This action allows the insert point to be turned on and off. +The <emphasis remap='I'>state</emphasis> argument specifies the desired state of the insert point. +This value may be any of the string +values accepted for Boolean resources (e.g. <function>on</function>, <function>True</function>, +<function>off</function>, <function>False</function>, etc.). If no arguments are specified, the +default value is <function>True</function>. +The <emphasis remap='I'>when</emphasis> argument specifies, for <function>EnterNotify</function> or <function>LeaveNotify</function> +events whether or not the focus field in the event is to be examined. +If the second argument is not specified, or specified as something other +than <function>always</function> then if the action is bound to an <function>EnterNotify</function> +or <function>LeaveNotify</function> event, the action will be taken only if the focus +field is <function>True</function>. An augmented binding that might be useful is: + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i 2.5i 4.0i --> +<!-- .ta 2.0i 2.5i 4.0i --> + *Text.Translations: #override \\ + <FocusIn>: display-caret(on) \\n\\ + <FocusOut>: display-caret(off) +</literallayout> +<variablelist> + <varlistentry> + <term> + focus-in() + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + focus-out() + </term> + <listitem> + <para> +These actions do not currently do anything. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + search(<emphasis remap='I'>direction</emphasis>,[<emphasis remap='I'>string</emphasis>]) + </term> + <listitem> + <para> +This action activates the search popup. The <emphasis remap='I'>direction</emphasis> must be +specified as either <function>forward</function> or <function>backward</function>. The string is +optional and is used as an initial value for the <emphasis remap='I'>Search for</emphasis>: string. +For further explanation of the search widget see the section on +<function>Text Searches</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + multiply(<emphasis remap='I'>value</emphasis>) + </term> + <listitem> + <para> +The multiply action allows the user to multiply the effects of many of +the text actions. Thus the following action sequence +<emphasis remap='I'>multiply(10) delete-next-word()</emphasis> will delete 10 words. It does not +matter whether these actions take place in one event or many events. +Using the default translations the key sequence \fIControl-u, +Control-d\fP will delete 4 characters. +Multiply actions can be chained, thus \fImultiply(5) +multiply(5)\fP is the same as <emphasis remap='I'>multiply(25)</emphasis>. If the string +<function>reset</function> is passed to the multiply action the effects of all previous +multiplies are removed and a beep is sent to the display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + form-paragraph() + </term> + <listitem> + <para> +This action removes all the Carriage Returns from the current +paragraph and reinserts them so that each line is as long as possible, while +still fitting on the current screen. Lines are broken at word boundaries if +at all possible. This action currently works only on Text widgets +that use ASCII text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + transpose-characters() + </term> + <listitem> + <para> +This action will swap the position of the character to the left of the +insert point with the character to the right of the insert point. The insert point will then +be advanced one character. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + no-op([<emphasis remap='I'>action</emphasis>]) + </term> + <listitem> + <para> +The no-op action makes no change to the text widget, and is mainly used +to override translations. This action takes one optional argument. If +this argument is <emphasis remap='I'>RingBell</emphasis> then a beep is sent to the display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + XawWMProtocols([<emphasis remap='I'>wm_protocol_name</emphasis>]) + </term> + <listitem> + <para> +<!-- .IN "XawWMProtocols" --> +<!-- .sp --> +This action is written specifically for the file insertion and the search +and replace +dialog boxes. This action is attached to those shells by the Text widget, +in order to handle ClientMessage events with the WM_PROTOCOLS atom in the +detail field. This action supports WM_DELETE_WINDOW on the Text widget +popups, and may support other window manager protocols if necessary in +the future. The popup will be dismissed if the window manager sends +a WM_DELETE_WINDOW request and there are no parameters in the action +call, which is the default. The popup will also be dismissed if the +parameters include the string ``wm_delete_window,'' and the event is a +ClientMessage event requesting dismissal or is not a ClientMessage event. +This action is not sensitive to the case of the strings passed as parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + reconnect-im() + </term> + <listitem> + <para> +<!-- .IN "Input Method" --> +When the <function>international</function> resource is <function>true</function>, +input is usually passed to an input method, a separate +process, for composing. Sometimes the connection to +this process gets severed; this action will attempt to +reconnect it. Causes for severage include network +trouble, and the user explicitly killing one input +method and starting a new one. This action may also +establish first connection when the application is +started before the input method. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Text_Selections_for_Application_Programmers"> +<title>Text Selections for Application Programmers</title> +<!-- .IN "Text widget" "Text Selections for Application Programmers" --> +<para> +<!-- .LP --> +The default behavior of the text selection array is described in the +section called <function>Text Selections for Users</function>. To modify the selections +a programmer must construct a <function>XawTextSelectType</function> array (called the +selection array), containing the selections desired, and pass this as +the new value for the <function>selectionTypes</function> resource. The selection +array may also be modified using the <function>XawTextSetSelectionArray</function> +<!-- .IN "XawTextSetSelectionArray" "" --> +function. All selection arrays must end with the value +<function>XawselectNull</function>. The <function>selectionTypes</function> resource has no converter +registered and cannot be modified through the resource manager. +</para> +<para> +<!-- .LP --> +The array contains a list of entries that will be called when the user +attempts to select text in rapid succession with the <emphasis remap='I'>select-start</emphasis> +action (usually by clicking a pointer button). The first entry in the +selection array will be used when the <emphasis remap='I'>select-start</emphasis> action is +initially called. The next entry will be used when <emphasis remap='I'>select-start</emphasis> +is called again, and so on. If a timeout value (1/10 of a second) is +exceeded, the the next <emphasis remap='I'>select-start</emphasis> action will begin at the top +of the selection array. When <function>XawselectNull</function> is reached the array +is recycled beginning with the first element. + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry><function>XawselectAll</function></entry> + <entry>Selects the contents of the entire buffer.</entry> + </row> + <row> + <entry><function>XawselectChar</function></entry> + <entry>Selects text characters as the pointer moves over them.</entry> + </row> + <row> + <entry><function>XawselectLine</function></entry> + <entry>Selects the entire line.</entry> + </row> + <row> + <entry><function>XawselectNull</function></entry> + <entry>Indicates the end of the selection array.</entry> + </row> + <row> + <entry><function>XawselectParagraph</function></entry> + <entry>Selects the entire paragraph.</entry> + </row> + <row> + <entry><function>XawselectPosition</function></entry> + <entry>Selects the current pointer position.</entry> + </row> + <row> + <entry><function>XawselectWord</function></entry> + <entry>Selects whole words as the pointer moves onto them.</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<para> +<!-- .LP --> +The default selectType array is: +</para> +<para> +<!-- .LP --> +<!-- .sp --> +<literallayout class="monospaced"> +{XawselectPosition, XawselectWord, XawselectLine, XawselectParagraph, XawselectAll, XawselectNull} +</literallayout> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +The selection array is not copied by the text widgets. The +application must allocate space for the array and cannot deallocate or +change it until the text widget is destroyed or until a new selection +array is set. +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/TextCustom.xml b/libXaw/specs/TextCustom.xml new file mode 100644 index 000000000..7ca2d5f78 --- /dev/null +++ b/libXaw/specs/TextCustom.xml @@ -0,0 +1,123 @@ +<sect1 id="Customizing_the_Text_Widget"> +<title>Customizing the Text Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Customizing the Text Widget --> +<!-- .XE --> +<!-- .IN "Text widget" "customizing" "@DEF@" --> +</para> +<para> +<!-- .LP --> +The remainder of this chapter will describe customizing the Text +widget. The Text widget may be customized by subclassing, or by +creating new sources and sinks. Subclassing is described in +detail in Chapter 7; this section will describe only those things that +are specific to the Text widget. Attributes of the Text widget base +class and creating new sources and sinks will be discussed. +</para> +<para> +<!-- .LP --> +The Text widget is made up of a number of different pieces, with the +Text widget as the base widget class. It and the AsciiText widget are +the only true "widgets" in the Text widget family. The other pieces +(sources and sinks) are X Toolkit objects and have no window +associated with them. No source or sink is useful unless assigned to +a Text widget. +</para> +<para> +<!-- .LP --> +Each of the following pieces of the Text widget has a specific purpose, +and will be, or has been, discussed in detail in this chapter: +<!-- .IN "Text widget" "" --> +</para> +<para> +<variablelist> + <varlistentry> + <term><function>Text</function></term> + <listitem> + <para> +This is the glue that binds everything else together. This widget reads +the text data from the source, and displays the information in the sink. +All translations and actions are handled in the Text widget itself. + </para> + </listitem> + </varlistentry> +<!-- .IN "TextSink object" "" --> + <varlistentry> + <term><function>TextSink</function></term> + <listitem> + <para> +This object is responsible for displaying and clearing the drawing area. +It also reports the configuration of the window that contains the +drawing area. The TextSink does not have its own window; instead it does +its drawing on the Text widget's window. + </para> + </listitem> + </varlistentry> +<!-- .IN "TextSrc object" "" --> + <varlistentry> + <term><function>TextSrc</function></term> + <listitem> + <para> +This object is responsible for reading, editing and searching through the +text buffer. + </para> + </listitem> + </varlistentry> +<!-- .IN "AsciiSink object" "" --> + <varlistentry> + <term><function>AsciiSink</function></term> + <listitem> + <para> +This object is a subclass of the TextSink and knows how to display +ASCII text. Support has been added to display any 8-bit character set, given +the font. + </para> + </listitem> + </varlistentry> +<!-- .IN "MultiSink object" "" --> + <varlistentry> + <term><function>MultiSink</function></term> + <listitem> + <para> +This object is a subclass of the TextSink and knows how to display +font sets. + </para> + </listitem> + </varlistentry> +<!-- .IN "AsciiSrc object" "" --> + <varlistentry> + <term><function>AsciiSrc</function></term> + <listitem> + <para> +This object is a subclass of the TextSrc and knows how to read strings +and files. + </para> + </listitem> + </varlistentry> +<!-- .IN "MultiSrc object" "" --> + <varlistentry> + <term><function>MultiSrc</function></term> + <listitem> + <para> +This object is a subclass of the TextSrc and knows how to read strings +and multibyte files, converting them to wide characters based on locale. + </para> + </listitem> + </varlistentry> +<!-- .IN "AsciiText widget" "" --> + <varlistentry> + <term><function>AsciiText</function></term> + <listitem> + <para> +This widget is a subclass of the Text widget. When created, the AsciiText +automatically creates and attaches either an AsciiSrc and AsciiSink, or a +MultiSrc and MultiSink, to itself. The AsciiText provides the simplest +interface to the Athena Text widgets. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect1> diff --git a/libXaw/specs/TextFuncs.xml b/libXaw/specs/TextFuncs.xml new file mode 100644 index 000000000..0d2ae8192 --- /dev/null +++ b/libXaw/specs/TextFuncs.xml @@ -0,0 +1,856 @@ +<sect1 id="Text_Functions"> +<title>Text Functions</title> +<!-- .XS --> +<!-- Text Functions --> +<!-- .XE --> +<para> +<!-- .LP --> +The following functions are provided as convenience routines for use with +the Text widget. Although many of these actions can be performed by +modifying resources, these interfaces are frequently more efficient. +</para> +<para> +<!-- .LP --> +These data structures are defined in the Text widget's public header file, +<X11/Xaw/Text.h>. +</para> +<para> +<!-- .LP --> +<!-- .IN "XawTextPosition" "" "@DEF@" --> +typedef long XawTextPosition; +<!-- .sp --> +</para> +<para> +<!-- .LP --> +Character positions in the Text widget begin at 0 and end at n, where +n is the number of characters in the Text source widget. +</para> +<para> +<!-- .LP --> +<!-- .IN "XawTextBlock" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA .5i 1.5i 2.25i --> +<!-- .ta .5i 1.5i 2.25i --> +typedef struct { + int <emphasis remap='I'>firstPos</emphasis>; + int <emphasis remap='I'>length</emphasis>; + char *<emphasis remap='I'>ptr</emphasis>; + unsigned long <emphasis remap='I'>format</emphasis>; +} XawTextBlock, *XawTextBlockPtr; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .IN "XawTextBlockPtr" "" --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>firstPos</emphasis> + </term> + <listitem> + <para> +The first position, or index, to use within the <emphasis remap='I'>ptr</emphasis> field. +The value is commonly zero. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +The number of characters to be used from the <emphasis remap='I'>ptr</emphasis> field. +The number of characters used is commonly the number of characters +in <emphasis remap='I'>ptr</emphasis>, and must not be greater than the length of the string +in <emphasis remap='I'>ptr</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ptr</emphasis> + </term> + <listitem> + <para> +Contains the string to be referenced by the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format</emphasis> + </term> + <listitem> + <para> +This flag indicates whether the data pointed to by <function>ptr</function> is char +or wchar_t. When the associated widget has <function>international</function> set +to <function>false</function> this field must be XawFmt8Bit. When the associated +widget has <function>international</function> set to <function>true</function> this field must be +either XawFmt8Bit or XawFmtWide. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<note> +<para> +<!-- .LP --> +Note: Previous versions of Xaw used +<function>FMT8BIT ,</function> +which has been retained for backwards compatibility. <function>FMT8BIT</function> is +deprecated and will eventually be removed from the implementation. +</para> +</note> +<sect2 id="Selecting_Text"> +<title>Selecting Text</title> +<para> +<!-- .LP --> +To select a piece of text, use +<function>XawTextSetSelection : </function> +<!-- .IN "XawTextSetSelection" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextSetSelection</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionleft,<parameter> right</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>left</emphasis> + </term> + <listitem> + <para> +Specifies the character position at which the selection begins. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>right</emphasis> + </term> + <listitem> + <para> +Specifies the character position at which the selection ends. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +If redisplay is enabled, this function highlights the text and +makes it the <function>PRIMARY</function> selection. This function does not have any +effect on <function>CUT_BUFFER0</function>. +</para> +<para> +<!-- .LP --> +</para> +</sect2> +<sect2 id="Unhighlighting_Text"> +<title>Unhighlighting Text</title> +<para> +<!-- .LP --> +To unhighlight previously highlighted text in a widget, use +<function>XawTextUnsetSelection</function>: +<!-- .IN "XawTextUnsetSelection" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextUnsetSelection</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="Getting_Current_Text_Selection"> +<title>Getting Current Text Selection</title> +<para> +<!-- .LP --> +To retrieve the text that has been selected by this +text widget use <function>XawTextGetSelectionPos</function>: +<!-- .IN "XawTextGetSelectionPos" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextGetSelectionPos</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition*begin_return,<parameter> *end_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>begin_return</emphasis> + </term> + <listitem> + <para> +Returns the beginning of the text selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>end_return</emphasis> + </term> + <listitem> + <para> +Returns the end of the text selection. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +If the returned values are equal, no text is currently selected. +</para> +</sect2> +<sect2 id="Replacing_Text"> +<title>Replacing Text</title> +<para> +<!-- .LP --> +To modify the text in an editable Text widget use <function>XawTextReplace</function>: +<!-- .IN "XawTextReplace" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> XawTextReplace</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef> + <paramdef>XawTextBlock<parameter> *text</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>start</emphasis> + </term> + <listitem> + <para> +Specifies the starting character position of the text replacement. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>end</emphasis> + </term> + <listitem> + <para> +Specifies the ending character position of the text replacement. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>text</emphasis> + </term> + <listitem> + <para> +Specifies the text to be inserted into the file. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function will not +be able to replace text in read-only text widgets. It will also only +be able to append text to an append-only text widget. +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function> and <!-- xref --> +<function>XawTextBlock</function>. +</para> +<para> +<!-- .LP --> +This function may return the following values: +<variablelist> + <varlistentry> + <term> + <function>XawEditDone</function> + </term> + <listitem> + <para> +<!-- .IN "XawEditDone" "" --> +The text replacement was successful. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>XawPositionError</function> + </term> + <listitem> + <para> +<!-- .IN "XawPositionError" "" --> +The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the position of +the last character of the source. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>XawEditError</function> + </term> + <listitem> + <para> +<!-- .IN "XawEditError" "" --> +Either the Source was read-only or the range to be deleted is larger +than the length of the Source. + + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The <function>XawTextReplace</function> arguments <function>start</function> and +<emphasis remap='I'>end</emphasis> represent the text source character positions for the +existing text that is to be replaced by the text in the text block. +The characters from <emphasis remap='I'>start</emphasis> up to +but not including <emphasis remap='I'>end</emphasis> are deleted, and the characters +specified on the text block are inserted in their place. If +<emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and the new +text is inserted after <emphasis remap='I'>start</emphasis>. +</para> +</sect2> +<sect2 id="Searching_for_Text"> +<title>Searching for Text</title> +<para> +<!-- .LP --> +To search for a string in the Text widget, use +<function>XawTextSearch</function>: +<!-- .IN "XawTextSearch" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> XawTextSearch</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef> + <paramdef>XawTextBlock*<parameter> text</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dir</emphasis> + </term> + <listitem> + <para> +Specifies the direction to search in. Legal values are +<function>XawsdLeft</function> and <function>XawsdRight</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>text</emphasis> + </term> + <listitem> + <para> +Specifies a text block structure that contains the text to search for. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function> and <function>XawTextBlock</function>. <!-- xref --> +The <function>XawTextSearch</function> function will begin at the insertion point +and search in the +direction specified for a string that matches the one passed in +<emphasis remap='I'>text</emphasis>. If the string is found the location of the first +character in the string is returned. If the string could not be +found then the value <function>XawTextSearchError</function> is returned. +</para> +</sect2> +<sect2 id="Redisplaying_Text"> +<title>Redisplaying Text</title> +<para> +<!-- .LP --> +To redisplay a range of characters, use <function>XawTextInvalidate</function>: +<!-- .IN "XawTextInvalidate" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextInvalidate</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionfrom,<parameter> to</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>from</emphasis> + </term> + <listitem> + <para> +Specifies the start of the text to redisplay. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>to</emphasis> + </term> + <listitem> + <para> +Specifies the end of the text to redisplay. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +The <function>XawTextInvalidate</function> +function causes the specified range of characters to be redisplayed +immediately if redisplay is enabled or the next time that redisplay is +enabled. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To enable redisplay, use <function>XawTextEnableRedisplay</function>: +<!-- .IN "XawTextEnableRedisplay" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextEnableRedisplay</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The <function>XawTextEnableRedisplay</function> function flushes any changes due to +batched updates when <function>XawTextDisableRedisplay</function> +was called and allows future changes to be reflected immediately. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To disable redisplay while making several changes, use +<function>XawTextDisableRedisplay</function>. +<!-- .IN "XawTextDisableRedisplay" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextDisableRedisplay</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The <function>XawTextDisableRedisplay</function> function causes all changes to be +batched until either <function>XawTextDisplay</function> or <function>XawTextEnableRedisplay</function> +is called. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To display batched updates, use <function>XawTextDisplay</function>: +<!-- .IN "XawTextDisplay" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextDisplay</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The <function>XawTextDisplay</function> function forces any accumulated updates to be +displayed. +</para> +</sect2> +<sect2 id="Resources_Convenience_Routines"> +<title>Resources Convenience Routines</title> +<para> +<!-- .LP --> +To obtain the character position of the left-most character on the +first line displayed in the widget (the value of the +<function>displayPosition</function> resource), use <function>XawTextTopPosition</function>. +<!-- .IN "XawTextTopPosition" "" @DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> XawTextTopPosition</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To assign a new selection array to a text widget use +<function>XawTextSetSelectionArray</function>: +<!-- .IN "XawTextSetSelectionArray" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextSetSelectionArray</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextSelectType*<parameter> sarray</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>sarray</emphasis> + </term> + <listitem> + <para> +Specifies a selection array as defined in the section called \fBText +Selections for Application Programmers\fP. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Calling this function is equivalent to setting the value of the +<function>selectionTypes</function> resource. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To move the insertion point to the specified source position, use +<function>XawTextSetInsertionPoint</function>: +<!-- .IN "XawTextSetInsertionPoint" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextSetInsertionPoint</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> position</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>position</emphasis> + </term> + <listitem> + <para> +Specifies the new position for the insertion point. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +The text will be scrolled vertically if necessary to make the line +containing the insertion point visible. Calling this function is +equivalent to setting the <function>insertPosition</function> resource. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To obtain the current position of the insertion point, use +<function>XawTextGetInsertionPoint</function>: +<!-- .IN "XawTextGetInsertionPoint" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> XawTextGetInsertionPoint</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +The result is equivalent to retrieving the value of the +<function>insertPosition</function> resource. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To replace the text source in the specified widget, use +<function>XawTextSetSource</function>: +<!-- .IN "XawTextSetSource" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextSetSource</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Widget<parameter> source</parameter></paramdef> + <paramdef>XawTextPosition<parameter> position</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>source</emphasis> + </term> + <listitem> + <para> +Specifies the text source object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>position</emphasis> + </term> + <listitem> + <para> +Specifies character position that will become the upper left hand corner +of the displayed text. This is usually set to zero. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +See section 5.4 for a description of <function>XawTextPosition</function>. <!-- xref --> +A display update will be performed if redisplay is enabled. +</para> +<para> +<!-- .LP --> +<!-- .sp 1 --> +To obtain the current text source for the specified widget, use +<function>XawTextGetSource</function>: +<!-- .IN "XawTextGetSource" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>Widget<function> XawTextGetSource</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function returns the text source that this Text widget is currently +using. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To enable and disable the insertion point, use +<function>XawTextDisplayCaret</function>: +<!-- .IN "XawTextDisplayCaret" "" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTextDisplayCaret</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Boolean<parameter> visible</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Text widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>visible</emphasis> + </term> + <listitem> + <para> +Specifies whether or not the caret should be displayed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +If <function>visible</function> is <function>False</function> the insertion point will be disabled. +The marker is re-enabled either by setting <function>visible</function> to <function>True</function>, by +calling <function>XtSetValues</function>, or by executing the <function>display-caret</function> +action routine. +</para> +</sect2> +</sect1> diff --git a/libXaw/specs/TextSink.xml b/libXaw/specs/TextSink.xml new file mode 100644 index 000000000..bafe557bd --- /dev/null +++ b/libXaw/specs/TextSink.xml @@ -0,0 +1,915 @@ +<sect1 id="TextSink_Object"> +<title>TextSink Object</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- TextSink Object --> +<!-- .XE --> +<!-- .IN "TextSink object" "" "@DEF@" --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +Application Header file <X11/Xaw/TextSink.h> +<!-- .IN "TextSink.h" "" --> +Class Header file <X11/Xaw/TextSinkP.h> +<!-- .IN "TextSinkP.h" "" --> +Class textSinkObjectClass +<!-- .IN "textSinkObjectClass" "" --> +Class Name TextSink +<!-- .IN "TextSink object" "class name" --> +Superclass Object +</literallayout> +</para> +<para> +<!-- .LP --> +The TextSink object is the root object for all text sinks. Any new text +sink objects should be subclasses of the TextSink Object. The TextSink +Class contains all methods that the Text widget expects a text sink to +export. +</para> +<para> +<!-- .LP --> +Since all text sinks will have some resources in common, the TextSink +defines a few new resources. +</para> +<sect2 id="textsink_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating an TextSink object instance, the following resources are +retrieved from the argument list or from the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "AsciiSink object" "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>background</entry> + <entry>Background</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultBackground</entry> + </row> + <row> + <entry>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> +<!-- .Bg Bold --> +<!-- .Dc --> +<!-- .Sg Bold --> +</para> +</sect2> +<sect2 id="Subclassing_the_TextSink"> +<title>Subclassing the TextSink</title> +<!-- .IN "TextSink object" "subclassing" "@DEF@" --> +<para> +<!-- .LP --> +The only purpose of the TextSink Object is to be subclassed. It +contains the minimum set of class methods that all text sinks must have. +While all may be inherited, the direct descendant of TextSink <function>must +specify</function> some of them as TextSink does contain enough information to +be a valid text sink by itself. Do not try to use +the TextSink as a valid sink for the Text widget; it is not intended +to be used as a sink by itself. +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Function</entry> + <entry>Inherit with</entry> + <entry>Public Interface</entry> + <entry>must specify</entry> + </row> + </thead> + <tbody> + <row> + <entry>DisplayText</entry> + <entry>XtInheritDisplayText</entry> + <entry>XawTextSinkDisplayText</entry> + <entry>yes</entry> + </row> + <row> + <entry>InsertCursor</entry> + <entry>XtInheritInsertCursor</entry> + <entry>XawTextSinkInsertCursor</entry> + <entry>yes</entry> + </row> + <row> + <entry>ClearToBackground</entry> + <entry>XtInheritClearToBackground</entry> + <entry>XawTextSinkClearToBackground</entry> + <entry>no</entry> + </row> + <row> + <entry>FindPosition</entry> + <entry>XtInheritFindPosition</entry> + <entry>XawTextSinkFindPosition</entry> + <entry>yes</entry> + </row> + <row> + <entry>FindDistance</entry> + <entry>XtInheritFindDistance</entry> + <entry>XawTextSinkFindDistance</entry> + <entry>yes</entry> + </row> + <row> + <entry>Resolve</entry> + <entry>XtInheritResolve</entry> + <entry>XawTextSinkResolve</entry> + <entry>yes</entry> + </row> + <row> + <entry>MaxLines</entry> + <entry>XtInheritMaxLines</entry> + <entry>XawTextSinkMaxLines</entry> + <entry>no</entry> + </row> + <row> + <entry>MaxHeight</entry> + <entry>XtInheritMaxHeight</entry> + <entry>XawTextSinkMaxHeight</entry> + <entry>no</entry> + </row> + <row> + <entry>SetTabs</entry> + <entry>XtInheritSetTabs</entry> + <entry>XawTextSinkSetTabs</entry> + <entry>no</entry> + </row> + <row> + <entry>GetCursorBounds</entry> + <entry>XtInheritGetCursorBounds</entry> + <entry>XawTextSinkGetCursorBounds</entry> + <entry>yes</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> +<sect3 id="Displaying_Text"> +<title>Displaying Text</title> +<para> +<!-- .LP --> +To display a section of the text buffer contained in the text source +use the function <function>DisplayText</function>: +<!-- .IN "TextSink object" "DisplayText" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> DisplayText</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Positionx,<parameter> y</parameter></paramdef> + <paramdef>XawTextPositionpos1,<parameter> pos2</parameter></paramdef> + <paramdef>Boolean<parameter> highlight</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +Specifies the x location to start drawing the text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specifies the y location to start drawing text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pos1</emphasis> + </term> + <listitem> + <para> +Specifies the location within the text source of the first character +to be printed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pos2</emphasis> + </term> + <listitem> + <para> +Specifies the location within the text source of the last character +to be printed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>highlight</emphasis> + </term> + <listitem> + <para> +Specifies whether or not to paint the text region highlighted. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +The Text widget will only pass one line at a time to the text sink, so +this function does not need to know how to line feed the text. It is +acceptable for this function to just ignore Carriage Returns. <emphasis remap='I'>x</emphasis> +and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the first character to +be displayed. +</para> +</sect3> +<sect3 id="Displaying_the_Insert_Point"> +<title>Displaying the Insert Point</title> +<para> +<!-- .LP --> +The function that controls the display of the text cursor is +<function>InsertCursor</function>. This function will be called whenever the text +widget desires to change the state of, or move the insert point. +<funcsynopsis> +<funcprototype> + <funcdef>void<function> InsertCursor</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Positionx,<parameter> y</parameter></paramdef> + <paramdef>XawTextInsertState<parameter> state</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +Specifies the x location of the cursor in Pixels. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specifies the y location of the cursor in Pixels. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>state</emphasis> + </term> + <listitem> + <para> +Specifies the state of the cursor, may be one of <function>XawisOn</function> or +<function>XawisOff</function>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of the insert point. +</para> +</sect3> +<sect3 id="Clearing_Portions_of_the_Text_window"> +<title>Clearing Portions of the Text window</title> +<para> +<!-- .LP --> +To clear a portion of the Text window to its background color, the Text +widget will call <function>ClearToBackground</function>. The TextSink object already +defines this function as calling <function>XClearArea</function> on the region passed. +This behavior will be used if you specify +<function>XtInheritClearToBackground</function> for this method. +<!-- .IN "XtInheritClearToBackground" "" --> +<!-- .IN "TextSink object" "ClearToBackground" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> ClearToBackground</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Positionx,<parameter> y</parameter></paramdef> + <paramdef>Dimensionwidth,<parameter> height</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +Specifies the x location, in pixels, of the Region to clear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specifies the y location, in pixels, of the Region to clear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +Specifies the width, in pixels, of the Region to clear. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specifies the height, in pixels, of the Region to clear. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<emphasis remap='I'>X</emphasis> and <emphasis remap='I'>y</emphasis> denote the upper left hand corner of region to clear. +</para> +</sect3> +<sect3 id="Finding_a_Text_Position_Given_Pixel_Values"> +<title>Finding a Text Position Given Pixel Values</title> +<para> +<!-- .LP --> +To find the text character position that will be rendered at a given x +location the Text widget uses the function <function>FindPosition</function>: +<!-- .IN "TextSink object" "FindPosition" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> FindPosition</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef> + <paramdef>intfromX,<parameter> width</parameter></paramdef> + <paramdef>Boolean<parameter> stopAtWordBreak</parameter></paramdef> + <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef> + <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromPos</emphasis> + </term> + <listitem> + <para> +Specifies a reference position, usually the first character in this line. +This character is always to the left of the desired character location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromX</emphasis> + </term> + <listitem> + <para> +Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the +left edge of the window. This is the reference x location for the +reference position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +Specifies the distance, in pixels, from the reference position to the +desired character position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>stopAtWordBreak</emphasis> + </term> + <listitem> + <para> +Specifies whether or not the position that is returned should be forced +to be on a word boundary. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pos_return</emphasis> + </term> + <listitem> + <para> +Returns the character position that corresponds to the location that has +been specified, or the work break immediately to the left of the +position if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width_return</emphasis> + </term> + <listitem> + <para> +Returns the actual distance between <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>pos_return</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and +<emphasis remap='I'>pos_return</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function need make no attempt to deal with line feeds. The text +widget will only call it one line at a time. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +Another means of finding a text position is provided by the <function>Resolve</function> +function: +<!-- .IN "TextSink object" "Resolve" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> Resolve</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> fromPos</parameter></paramdef> + <paramdef>intfromX,<parameter> width</parameter></paramdef> + <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromPos</emphasis> + </term> + <listitem> + <para> +Specifies a reference position, usually the first character in this line. +This character is always to the left of the desired character location. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromX</emphasis> + </term> + <listitem> + <para> +Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the +left edge of the window. This is the reference x location for the +reference position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>width</emphasis> + </term> + <listitem> + <para> +Specifies the distance, in pixels, from the reference position to the +desired character position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pos_return</emphasis> + </term> + <listitem> + <para> +Returns the character position that corresponds to the +location that has been specified, or the word break immediately to the left +if <emphasis remap='I'>stopAtWordBreak</emphasis> is <function>True</function>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function need make no attempt to deal with line feeds. The text +widget will only call it one line at a time. This is a more convenient +interface to the <function>FindPosition</function> function, and provides a subset of its +functionality. +<!-- .IN "FindPosition" "" --> +</para> +</sect3> +<sect3 id="Finding_the_Distance_Between_two_Text_Positions"> +<title>Finding the Distance Between two Text Positions</title> +<para> +<!-- .LP --> +To find the distance in pixels between two text positions on the same +line use the function <function>FindDistance</function>. +<!-- .IN "TextSink object" "FindDistance" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> FindDistance</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionfromPos,<parameter> toPos</parameter></paramdef> + <paramdef>int<parameter> fromX</parameter></paramdef> + <paramdef>XawTextPosition<parameter> *pos_return</parameter></paramdef> + <paramdef>int*width_return,<parameter> *height_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromPos</emphasis> + </term> + <listitem> + <para> +Specifies the text buffer position, in characters, of the first position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>fromX</emphasis> + </term> + <listitem> + <para> +Specifies the distance that the left edge of <emphasis remap='I'>fromPos</emphasis> is from the +left edge of the window. This is the reference x location for the +reference position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>toPos</emphasis> + </term> + <listitem> + <para> +Specifies the text buffer position, in characters, of the second position. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resWidth</emphasis> + </term> + <listitem> + <para> +Return the actual distance between <emphasis remap='I'>fromPos</emphasis> +and <emphasis remap='I'>pos_return</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resPos</emphasis> + </term> + <listitem> + <para> +Returns the character position that corresponds to the actual character +position used for <emphasis remap='I'>toPos</emphasis> in the calculations. This may be +different than <emphasis remap='I'>toPos</emphasis>, for example if <emphasis remap='I'>fromPos</emphasis> and <emphasis remap='I'>toPos</emphasis> +are on different lines in the file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height_return</emphasis> + </term> + <listitem> + <para> +Returns the maximum height of the text between <emphasis remap='I'>fromPos</emphasis> and +<emphasis remap='I'>pos_return</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function need make no attempt to deal with line feeds. The Text +widget will only call it one line at a time. +</para> +</sect3> +<sect3 id="Finding_the_Size_of_the_Drawing_area"> +<title>Finding the Size of the Drawing area</title> +<para> +<!-- .LP --> +To find the maximum number of lines that will fit into the current Text +widget, use the function <function>MaxLines</function>. The TextSink already defines +this function to compute the maximum number of lines by using the height +of <function>font</function>. +<!-- .IN "TextSink object" "MaxLines" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> MaxLines</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Dimension<parameter> height</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specifies the height of the current drawing area. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Returns the maximum number of lines that will fit in <emphasis remap='I'>height</emphasis>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To find the height required for a given number of text lines, use +the function <function>MaxHeight</function>. The TextSink already defines this +function to compute the maximum height of the window by using the +height of <function>font</function>. +<!-- .IN "TextSink object" "MaxHeight" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>int<function> MaxHeight</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>int<parameter> lines</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>height</emphasis> + </term> + <listitem> + <para> +Specifies the height of the current drawing area. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Returns the height that will be taken up by the number of lines passed. +</para> +</sect3> +<sect3 id="Setting_the_Tab_Stops"> +<title>Setting the Tab Stops</title> +<para> +<!-- .LP --> +To set the tab stops for a text sink use the <function>SetTabs</function> function. +The TextSink already defines this function to set the tab x location in +pixels to be the number of characters times the figure width of +<function>font</function>. +<!-- .IN "TextSink object" "SetTabs" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> SetTabs</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>inttab_count,<parameter> *tabs</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSink object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>tab_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of tabs passed in <emphasis remap='I'>tabs</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>tabs</emphasis> + </term> + <listitem> + <para> +Specifies the position, in characters, of the tab stops. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +This function is responsible for the converting character positions passed +to it into whatever internal positions the TextSink uses for tab placement. +</para> +</sect3> +<sect3 id="Getting_the_Insert_Point_s_Size_and_Location"> +<title>Getting the Insert Point's Size and Location</title> +<para> +<!-- .LP --> +To get the size and location of the insert point use the +<function>GetCursorBounds</function> function. +<!-- .IN "TextSink object" "GetCursorBounds" "@DEF@" --> +<funcsynopsis> +<funcprototype> + <funcdef>void<function> GetCursorBounds</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XRectangle<parameter> *rect_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSinkObject. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>rect_return</emphasis> + </term> + <listitem> + <para> +Returns the location and size of the insert point. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<emphasis remap='I'>Rect</emphasis> will be filled with the current size and location of the +insert point. + +</para> +</sect3> +</sect2> +</sect1> diff --git a/libXaw/specs/TextSource.xml b/libXaw/specs/TextSource.xml new file mode 100644 index 000000000..51b9ae0c3 --- /dev/null +++ b/libXaw/specs/TextSource.xml @@ -0,0 +1,620 @@ +<sect1 id="TextSrc_Object"> +<title>TextSrc Object</title> +<literallayout class="monospaced"> +Application Header file <X11/Xaw/TextSrc.h> +Class Header file <X11/Xaw/TextSrcP.h> +Class textSrcObjectClass +Class Name TextSrc +Superclass Object +</literallayout> + +<para> +<!-- .LP --> +The TextSrc object is the root object for all text sources. Any new text +source objects should be subclasses of the TextSrc Object. The +TextSrc Class contains all methods the Text widget expects a text +source to export. +</para> + +<para> +<!-- .LP --> +Since all text sources will have some resources in common the +TextSrc defines a few new resources. +</para> + +<sect2 id="textsource_resources"> +<title>Resources</title> +<para> +When creating an TextSrc object instance, the following resources are +retrieved from the argument list or from the resource database: +</para> + +<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>destroyCallback</entry> + <entry>Callback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>editType</entry> + <entry>EditType</entry> + <entry>EditMode</entry> + <entry></entry> + <entry>NULL</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</sect2> + +<sect2 id="Subclassing_the_TextSrc"> +<title>Subclassing the TextSrc</title> +<para> +The only purpose of the TextSrc Object is to be subclassed. It contains +the minimum set of class methods that all text sources must have. All +class methods of the TextSrc must be defined, as the Text widget uses +them all. While all may be inherited, the direct descendant of TextSrc +<function>must</function> specify some of them as TextSrc does not contain enough +information to be a valid text source by itself. Do not try to use the +TextSrc as a valid source for the Text widget; it is not intended to be +used as a source by itself and bad things will probably happen. +</para> + +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Function</entry> + <entry>Inherit with</entry> + <entry>Public Interface</entry> + <entry>must specify</entry> + </row> + </thead> + <tbody> + <row> + <entry>Read</entry> + <entry>XtInheritRead</entry> + <entry>XawTextSourceRead</entry> + <entry>yes</entry> + </row> + <row> + <entry>Replace</entry> + <entry>XtInheritReplace</entry> + <entry>XawTextSourceReplace</entry> + <entry>no</entry> + </row> + <row> + <entry>Scan</entry> + <entry>XtInheritScan</entry> + <entry>XawTextSourceScan</entry> + <entry>yes</entry> + </row> + <row> + <entry>Search</entry> + <entry>XtInheritSearch</entry> + <entry>XawTextSourceSearch</entry> + <entry>no</entry> + </row> + <row> + <entry>SetSelection</entry> + <entry>XtInheritSetSelection</entry> + <entry>XawTextSourceSetSelection</entry> + <entry>no</entry> + </row> + <row> + <entry>ConvertSelection</entry> + <entry>XtInheritConvertSelection</entry> + <entry>XawTextSourceConvertSelection</entry> + <entry>no</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<sect3 id="Reading_Text_"> +<title>Reading Text.</title> +<para> +<!-- .LP --> +To read the text in a text source use the <function>Read</function> function: +<!-- .IN "TextSrc object" "Read" "@DEF@" --> +</para> +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> Read</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> pos</parameter></paramdef> + <paramdef>XawTextBlock<parameter> *text_return</parameter></paramdef> + <paramdef>int<parameter> length</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>pos</emphasis> + </term> + <listitem> + <para> +Specifies the position of the first character to be read from the text buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>text</emphasis></term> + <listitem> + <para> +Returns the text read from the source. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the maximum number of characters the TextSrc should +return to the application in <emphasis remap='I'>text_return</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function returns the text position immediately after the +characters read from the +text buffer. The function is not required to read <emphasis remap='I'>length</emphasis> +characters if that many characters are in the file, it may break at +any point that is convenient to the internal structure of the +source. It may take several calls to <function>Read</function> before the desired +portion of the text buffer is fully retrieved. +</para> +</sect3> + +<sect3 id="Replacing_Text_"> +<title>Replacing Text.</title> +<para> +To replace or edit the text in a text buffer use the <function>Replace</function> function: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> Replace</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef> + <paramdef>XawTextBlock<parameter> *text</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term><emphasis remap='I'>w</emphasis></term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>start</emphasis></term> + <listitem> + <para> +Specifies the position of the first character to be removed from the text +buffer. This is also the location to begin inserting the new text. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>end</emphasis></term> + <listitem> + <para> +Specifies the position immediately after the last character to be +removed from the text buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>text</emphasis></term> + <listitem> + <para> +Specifies the text to be added to the text source. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function can return any of the following values: +</para> + +<variablelist> + <varlistentry> + <term><function>XawEditDone</function></term> + <listitem> + <para> +The text replacement was successful. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>XawPositionError</function></term> + <listitem> + <para> +<!-- .IN "XawPositionError" "" --> +The edit mode is <function>XawtextAppend</function> and <function>start</function> is not the last +character of the source. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>XawEditError</function></term> + <listitem> + <para> +<!-- .IN "XawEditError" "" --> +Either the Source was read-only or the range to be deleted is larger +than the length of the Source. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +The <function>Replace</function> arguments <function>start</function> and <function>end</function> represent the +text source character positions for the existing text that is to be +replaced by the text in the text block. The characters from +<emphasis remap='I'>start</emphasis> up to but not including <emphasis remap='I'>end</emphasis> are deleted, and the +buffer specified by the text block is inserted in their +place. If <emphasis remap='I'>start</emphasis> and <emphasis remap='I'>end</emphasis> are equal, no text is deleted and +the new text is inserted after <emphasis remap='I'>start</emphasis>. +</para> +</sect3> + +<sect3 id="Scanning_the_TextSrc"> +<title>Scanning the TextSrc</title> +<para> +To search the text source for one of the predefined boundary types use +the <function>Scan</function> function: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> Scan</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> position</parameter></paramdef> + <paramdef>XawTextScanType<parameter> type</parameter></paramdef> + <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef> + <paramdef>int<parameter> count</parameter></paramdef> + <paramdef>Boolean<parameter> include</parameter></paramdef> +</funcprototype> +</funcsynopsis> + + +<variablelist> + <varlistentry> + <term><emphasis remap='I'>w</emphasis></term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>position</emphasis></term> + <listitem> + <para> +Specifies the position to begin scanning the source. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>type</emphasis></term> + <listitem> + <para> +Specifies the type of boundary to scan for, may be one of: +<function>XawstPosition</function>, <function>XawstWhiteSpace</function>, <function>XawstEOL</function>, +<function>XawstParagraph</function>, <function>XawstAll</function>. The exact meaning of these +boundaries is left up to the individual text source. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>dir</emphasis></term> + <listitem> + <para> +Specifies the direction to scan, may be either <function>XawsdLeft</function> to search +<!-- .IN "XawsdLeft" "" --> +backward, or <function>XawsdRight</function> to search forward. +<!-- .IN "XawsdRight" "" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>count</emphasis></term> + <listitem> + <para> +Specifies the number of boundaries to scan for. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>include</emphasis></term> + <listitem> + <para> +Specifies whether the boundary itself should be included in the scan. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .LP --> +The <function>Scan</function> function returns the position in the text source of the desired +boundary. It is expected to return a valid address for +all calls made to it, thus if a particular request is made that would take +the text widget beyond the end of the source it must return the +position of that end. +</para> +</sect3> + +<sect3 id="Searching_through_a_TextSrc"> +<title>Searching through a TextSrc</title> +<para> +To search for a particular string use the <function>Search</function> function. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>XawTextPosition<function> Search</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPosition<parameter> position</parameter></paramdef> + <paramdef>XawTextScanDirection<parameter> dir</parameter></paramdef> + <paramdef>XawTextBlock<parameter> *text</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term><emphasis remap='I'>w</emphasis></term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>position</emphasis></term> + <listitem> + <para> +Specifies the position to begin the search. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>dir</emphasis></term> + <listitem> + <para> +Specifies the direction to search, may be either <function>XawsdLeft</function> to search +<!-- .IN "XawsdLeft" "" --> +backward, or <function>XawsdRight</function> to search forward. +<!-- .IN "XawsdRight" "" --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>text</emphasis></term> + <listitem> + <para> +Specifies a text block containing the text to search for. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function will search through the text buffer attempting to find a +match for the string in the text block. If a match is found in the +direction specified, then the character location of the first character +in the string is returned. If no text was found then +<function>XawTextSearchError</function> is returned. +</para> + +</sect3> + +<sect3 id="Text_Selections"> +<title>Text Selections</title> + +<para> +<!-- .LP --> +While many selection types are handled by the Text widget, text sources +may have selection types unknown to the Text widget. When a selection +conversion is requested by the X server the Text widget will first call +the <function>ConvertSelection</function> function, to attempt the selection +conversion. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Boolean<function> ConvertSelections</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>Atom*selection,*target,<parameter> *type</parameter></paramdef> + <paramdef>caddr_t<parameter> *value_return</parameter></paramdef> + <paramdef>unsignedlong<parameter> *length_return</parameter></paramdef> + <paramdef>int<parameter> *format_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the type of the selection that has been requested, which +indicates the desired information about the selection (e.g. Filename, +Text, Window). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the atom into which the property type of the converted +value of the selection is to be stored. For instance, either file +name or text might have property type <function>XA_STRING</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_return</emphasis> + </term> + <listitem> + <para> +Returns a pointer into which a pointer to the converted value of the +selection +is to be stored. The selection owner is responsible for allocating +this storage. The memory is considered owned by the toolkit, and is +freed by XtFree when the Intrinsics selection mechanism is done with it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length_return</emphasis> + </term> + <listitem> + <para> +Returns a pointer into which the number of elements in value is to be stored. +The size of each element is determined by <emphasis remap='I'>format</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format_return</emphasis> + </term> + <listitem> + <para> +Returns a pointer into which the size in bits of the data elements of the +selection value is to be stored. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If this function returns <function>True</function> then the Text widget will assume +that the source has taken care of converting the selection, Otherwise the +Text widget will attempt to convert the selection itself. +</para> + +<para> +If the source needs to know when the text selection is modified it +should define a <function>SetSelection</function> procedure: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function> SetSelection</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> + <paramdef>XawTextPositionstart,<parameter> end</parameter></paramdef> + <paramdef>Atom<parameter> selection</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term><emphasis remap='I'>w</emphasis></term> + <listitem> + <para> +Specifies the TextSrc object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>start</emphasis></term> + <listitem> + <para> +Specifies the character position of the beginning of the new text selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>end</emphasis></term> + <listitem> + <para> +Specifies the character position of the end of the new text selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis remap='I'>selection</emphasis></term> + <listitem> + <para> +Specifies the type of selection that was requested (e.g. <function>PRIMARY</function>). + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect3> +</sect2> +</sect1> diff --git a/libXaw/specs/Toggle.xml b/libXaw/specs/Toggle.xml new file mode 100644 index 000000000..d5c239898 --- /dev/null +++ b/libXaw/specs/Toggle.xml @@ -0,0 +1,773 @@ +<sect1 id="Toggle_Widget"> +<title>Toggle Widget</title> +<literallayout class="monospaced"> +Application Header file <Xaw/Toggle.h> +Class Header file <Xaw/ToggleP.h> +Class toggleWidgetClass +Class Name Toggle +Superclass Command +</literallayout> + +<para> +The Toggle widget is an area, often rectangular, +that displays a graphic. The graphic may be a text +string containing multiple lines of characters in an 8 +bit or 16 bit character set (to be displayed with a +<emphasis remap='I'>font</emphasis>), or in a multi-byte encoding (for use with +a <emphasis remap='I'>fontset</emphasis>). The graphic may also be a bitmap or +pixmap. +</para> + +<para> +This widget maintains a Boolean state (e.g. +True/False or On/Off) and changes state whenever it is selected. When +the pointer is on the Toggle widget, the Toggle widget may become highlighted by +drawing a rectangle around its perimeter. This highlighting indicates +that the Toggle widget is ready for selection. When pointer button 1 is +pressed and released, the Toggle widget indicates that it has changed +state by reversing its foreground and background colors, and its +<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 Toggle widget reverts to its previous foreground and background +colors, and releasing the pointer button has no effect. This behavior allows +the user to cancel the operation. +</para> + +<para> +Toggle widgets may also be part of a ``radio group.'' A radio group is a +list of at least two Toggle widgets in which no more than one Toggle may +be set at +any time. A radio group is identified by the widget ID of any one of +its members. The convenience routine <function>XawToggleGetCurrent</function> will +return information about the Toggle widget in the radio group. +</para> + +<para> +Toggle widget state is preserved across changes in sensitivity. +</para> + +<sect2 id="toggle_resources"> +<title>Resources</title> +<para> +When creating a Toggle widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> + +<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>fontSet</entry> + <entry>FontSet</entry> + <entry>XFontSet</entry> + <entry></entry> + <entry>XtDefaultFontSet</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>radioData</entry> + <entry>RadioData</entry> + <entry>Pointer</entry> + <entry></entry> + <entry>Name of widget</entry> + </row> + <row> + <entry>radioGroup</entry> + <entry>Widget</entry> + <entry>Widget</entry> + <entry></entry> + <entry>No radio group</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>shapeStype</entry> + <entry>ShapeStyle</entry> + <entry>ShapeStyle</entry> + <entry></entry> + <entry>Rectangle</entry> + </row> + <row> + <entry>state</entry> + <entry>State</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>Off</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> + </tbody> + </tgroup> +</informaltable> + +<variablelist> + <varlistentry> + <term> + <function>radioData</function> + </term> + <listitem> + <para> +Specifies the data that will be returned by <function>XawToggleGetCurrent</function> +when this is the currently <emphasis remap='I'>set</emphasis> widget in the radio group. This +value is also used to identify the Toggle that will be set by a call to +<function>XawToggleSetCurrent</function>. The value NULL will be returned by +<function>XawToggleGetCurrent</function> if no widget in a radio group is currently +set. Programmers must not specify NULL (or Zero) as <function>radioData</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>radioGroup</function> + </term> + <listitem> + <para> +Specifies another Toggle widget that is in the radio group to which this +Toggle widget should be added. A radio group is a group of at least two Toggle +widgets, only one of which may be <emphasis remap='I'>set</emphasis> at a time. If this value is +NULL (the default) then the Toggle will not be part of any radio group +and can change state without affecting any other Toggle widgets. If the +widget specified in this resource is not already in a radio group then a +new radio group will be created containing these two Toggle widgets. No +Toggle widget can be in multiple radio groups. The behavior of a radio +group of one toggle is undefined. A converter is registered which will +convert widget names to widgets without caching. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>state</function> + </term> + <listitem> + <para> +Specifies whether the Toggle widget is set (<function>True</function>) or unset +(<function>False</function>). + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="Toggle_Actions"> +<title>Toggle Actions</title> +<para> +The Toggle widget supports the following actions: +</para> + +<itemizedlist> + <listitem> + <para> +Switching the Toggle widget between the foreground and background +colors with <function>set</function> and <function>unset</function> and <function>toggle</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> +The following are the default translation bindings used by the +Toggle widget: +</para> + +<literallayout class="monospaced"> + <EnterWindow>: highlight(Always) + <LeaveWindow>: unhighlight() + <Btn1Down>,<Btn1Up>: toggle() notify() +</literallayout> +</sect2> + +<sect2 id="Toggle_Actions_b"> +<title>Toggle Actions_b</title> +<para> +The full list of actions supported by Toggle is: +</para> +<variablelist> + <varlistentry> + <term> + <function>highlight</function>(<emphasis remap='I'>condition</emphasis>) + </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 +Toggle widget. The conditions <function>WhenUnset</function> and <function>Always</function> are +understood by this action procedure. If no argument is passed then +<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 +Toggle widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>set</function>() + </term> + <listitem> + <para> +Enters the <emphasis remap='I'>set</emphasis> state, in which <function>notify</function> is possible. This +action causes the Toggle widget 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 Toggle widget in the +<function>background</function> color. The label or bitmap is displayed in the +<function>foreground</function> color. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>toggle</function>() + </term> + <listitem> + <para> +Changes the current state of the Toggle widget, causing to be set +if it was previously unset, and unset if it was previously set. +If the widget is to be set, and is in a radio group then this procedure may +unset another Toggle widget causing all routines on its callback list +to be invoked. The callback routines for the Toggle that +is to be unset will be called before the one that is to be set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>reset</function>() + </term> + <listitem> + <para> +Cancels any <function>set</function> or <function>highlight</function> and displays the interior of the +Toggle widget in the <function>background</function> color, with the label displayed in the +<function>foreground</function> color. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>notify</function>() + </term> + <listitem> + <para> +When the Toggle widget 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 call_data argument in these callback functions is undefined. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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. +</para> +</sect2> + +<sect2 id="Radio_Groups"> +<title>Radio Groups</title> +<para> +There are typically two types of radio groups desired by applications. +The default translations for the Toggle widget implement a "zero or one +<!-- .IN "Radio groups" "zero or one of many" --> +of many" radio group. This means that there may be no more than one +Toggle widget active, but there need not be any Toggle widgets active. +</para> + +<para> +The other type of radio group is "one of many" and has the more strict +policy that there will always be exactly one radio button active. +Toggle widgets can be used to provide this interface with a slight +modification to the translation table of each Toggle in the group. +</para> + +<literallayout class="monospaced"> + <EnterWindow>: highlight(Always) + <LeaveWindow>: unhighlight() + <Btn1Down>,<Btn1Up>: set() notify() +</literallayout> + +<para> +This translation table will not allow any Toggle to be <emphasis remap='I'>unset</emphasis> +except as a result of another Toggle becoming <emphasis remap='I'>set</emphasis>. It is +the application programmer's responsibility to choose an initial +state for the radio group by setting the <function>state</function> resource of one of +its member widgets to <function>True</function>. +</para> +</sect2> + +<sect2 id="toggle_convenience_routines"> +<title>Convenience Routines</title> +<para> +The following functions allow easy access to the Toggle widget's radio +group functionality. +</para> + +<sect3 id="Changing_the_Toggle_s_Radio_Group_"> +<title>Changing the Toggle's Radio Group.</title> +<para> +To enable an application to change the Toggle's radio group, add +the Toggle to a radio group, or remove the Toggle from a radio group, use +<function>XawToggleChangeRadioGroup</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawToggleChangeRadioGroup</function></funcdef> + <paramdef>Widgetw,<parameter> radio_group</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<para> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the Toggle widget. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>radio_group</emphasis> + </term> + <listitem> + <para> +Specifies any Toggle in the new radio group. If NULL then the Toggle +will be removed from any radio group of which it is a member. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> + +<para> +If a Toggle is already <emphasis remap='I'>set</emphasis> in the new radio group, +and the Toggle to be added is also <emphasis remap='I'>set</emphasis> then the previously +<emphasis remap='I'>set</emphasis> Toggle in the radio group is <emphasis remap='I'>unset</emphasis> and its callback +procedures are invoked. +Finding the Currently selected Toggle in a radio group of Toggles +</para> + +<para> +To find the currently selected Toggle in a radio group of Toggle widgets +use <function>XawToggleGetCurrent</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>XtPointer<function> XawToggleGetCurrent</function></funcdef> + <paramdef>XtPointer<parameter> XawToggleGetCurrent(radio_group)</parameter></paramdef> + <paramdef>Widget<parameter> radio_group</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>radio_group</emphasis> + </term> + <listitem> + <para> +Specifies any Toggle widget in the radio group. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The value returned by this function is the +<function>radioData</function> +of the Toggle in this radio group that is currently set. The default +value for <function>radioData</function> +is the name of that Toggle widget. If no Toggle is set in the radio +group specified then NULL is returned. +Changing the Toggle that is set in a radio group. +</para> + +<para> +To change the Toggle that is currently set in a radio group use +<function>XawToggleSetCurrent</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawToggleSetCurrent</function></funcdef> + <paramdef>voidXawToggleSetCurrent(radio_group,<parameter> radio_data)</parameter></paramdef> + <paramdef>Widget<parameter> radio_group</parameter></paramdef> + <paramdef>XtPointer<parameter> radio_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>radio_group</emphasis> + </term> + <listitem> + <para> +Specifies any Toggle widget in the radio group. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>radio_data</emphasis> + </term> + <listitem> + <para> +Specifies the +<function>radioData</function> +identifying the Toggle that should be set in the radio group specified +by the <emphasis remap='I'>radio_group</emphasis> argument. + </para> + </listitem> + </varlistentry> +</variablelist> + + +<para> +<function>XawToggleSetCurrent</function> locates the Toggle widget to be set by +matching <emphasis remap='I'>radio_data</emphasis> against the <function>radioData</function> for each Toggle in +the radio group. If none match, <function>XawToggleSetCurrent</function> returns +without making any changes. If more than one Toggle matches, +<function>XawToggleSetCurrent</function> will choose a Toggle to set arbitrarily. If +this causes any Toggle widgets to change state, all routines in their +callback lists will be invoked. The callback routines for a Toggle that +is to be unset will be called before the one that is to be set. +Unsetting all Toggles in a radio group. +</para> + +<para> +To unset all Toggle widgets in a radio group use +<function>XawToggleUnsetCurrent</function>. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawToggleUnsetCurrent</function></funcdef> + <paramdef>void<parameter> XawToggleUnsetCurrent(radio_group)</parameter></paramdef> + <paramdef>Widget<parameter> radio_group</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>radio_group</emphasis> + </term> + <listitem> + <para> +Specifies any Toggle widget in the radio group. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If this causes a Toggle widget to change state, all routines on its +callback list will be invoked. +</para> +</sect3> +</sect2> +</sect1> diff --git a/libXaw/specs/Tree.xml b/libXaw/specs/Tree.xml new file mode 100644 index 000000000..bb51e80d1 --- /dev/null +++ b/libXaw/specs/Tree.xml @@ -0,0 +1,404 @@ +<sect1 id="Tree_Widget"> +<title>Tree Widget</title> +<literallayout class="monospaced"> +Application Header file <X11/Xaw/Tree.h> +Class Header file <X11/Xaw/TreeP.h> +Class treeWidgetClass +Class Name Tree +Superclass Constraint +</literallayout> + +<para> +The Tree widget provides geometry management of arbitrary widgets arranged +in a directed, acyclic graph (i.e., a tree). The hierarchy is constructed +by attaching a constraint resource called <function>treeParent</function> to each widget +indicating which other node in the tree should be treated as the widget's +superior. The structure of the tree is shown by laying out the nodes +in the standard format for tree diagrams with lines drawn connecting each +node with its children. +</para> + +<para> +The Tree sizes itself according to the needs of its children and is not +intended to be resized by its parent. Instead, it should be placed inside +another composite widget (such as the <function>Porthole</function> or <function>Viewport</function>) +that can be used to scroll around in the tree. +</para> + +<sect2 id="tree_resources"> +<title>Resources</title> +<para> +When creating a Tree widget instance, the following resources are +retrieved from the argument list or from the resource database: +</para> + +<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>autoReconfigure</entry> + <entry>AutoReconfigure</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>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>foreground</entry> + <entry>Foreground</entry> + <entry>Pixel</entry> + <entry></entry> + <entry>XtDefaultForeground</entry> + </row> + <row> + <entry>gravity</entry> + <entry>Gravity</entry> + <entry>XtGravity</entry> + <entry></entry> + <entry>WestGravity</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</function></entry> <!-- xref --> + </row> + <row> + <entry>hSpace</entry> + <entry>HSpace</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>lineWidth</entry> + <entry>LineWidth</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>0</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</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>vSpace</entry> + <entry>VSpace</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>4</entry> + </row> + <row> + <entry>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry>A</entry> + <entry>see <function>Layout Semantics</function></entry> <!-- xref --> + </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> + </tbody> + </tgroup> +</informaltable> + +<variablelist> + <varlistentry> + <term><function>autoReconfigure</function></term> + <listitem> + <para> +Whether or not to layout the tree every time a node is added or removed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>gravity</function></term> + <listitem> + <para> +Specifies the side of the widget from which the tree should grow. Valid +values include <function>WestGravity</function>, <function>NorthGravity</function>, <function>EastGravity</function>, and +<function>SouthGravity</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>hSpace</function></term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>vSpace</function></term> + <listitem> + <para> +The amount of space, in pixels, to leave between the children. This +resource specifies the amount of space left between the outermost +children and the edge of the box. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>lineWidth</function></term> + <listitem> + <para> +The width of the lines from nodes that do not have a <function>treeGC</function> +constraint resource to their children. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2 id="tree_constraint_resources"> +<title>Constraint Resources</title> +<para> +Each child of the Tree widget must specify its superior node in the tree. In +addition, it may specify a GC to use when drawing a line between it and its +inferior nodes. +</para> + +<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>treeGC</entry> + <entry>TreeGC</entry> + <entry>GC</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>treeParent</entry> + <entry>TreeParent</entry> + <entry>Widget</entry> + <entry></entry> + <entry>NULL</entry> + </row> + </tbody> + </tgroup> +</informaltable> + + + +<variablelist> + <varlistentry> + <term><function>treeGC</function></term> + <listitem> + <para> +This specifies the GC to use when drawing lines between this widget and its +inferiors in the tree. If this resource is not specified, the Tree's +<function>foreground</function> and <function>lineWidth</function> will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><function>treeParent</function></term> + <listitem> + <para> +This specifies the superior node in the tree for this widget. The default is +for the node to have no superior (and to therefore be at the top of the tree). + + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + + +<sect2 id="tree_layout_semantics"> +<title>Layout Semantics</title> +<para> +Each time a child is managed or unmanaged, the Tree widget will attempt +to reposition the remaining children to fix the shape of the tree if the +<!-- .B autoReconfigure --> +resource is set. Children at the top (most superior) of the tree are +drawn at the side specified by the resource. +</para> + +<para> +After positioning all children, the Tree widget attempts to shrink its +own size to the minimum dimensions required for the layout. +</para> + +</sect2> + +<sect2 id="tree_convenience_routines"> +<title>Convenience Routines</title> +<para> +The most efficient way to layout a tree is to set +<function>autoReconfigure</function> +to False and then use the +<function> XawTreeForceLayout</function> +routine to arrange the children. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void<function> XawTreeForceLayout</function></funcdef> + <paramdef>Widget<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term>w</term> + <listitem> + <para> +Specifies the Tree widget. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> +</sect1> diff --git a/libXaw/specs/Viewport.xml b/libXaw/specs/Viewport.xml new file mode 100644 index 000000000..3b3703639 --- /dev/null +++ b/libXaw/specs/Viewport.xml @@ -0,0 +1,391 @@ +<sect1 id="Viewport_Widget"> +<title>Viewport Widget</title> +<para> +<!-- .LP --> +<!-- .XS --> +<!-- Viewport Widget --> +<!-- .XE --> +<!-- .IN "Viewport widget" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA 2.0i --> +<!-- .ta 2.0i --> +<!-- .sp --> +Application Header file <X11/Xaw/Viewport.h> +<!-- .IN "Viewport.h" "" --> +Class Header file <X11/Xaw/ViewportP.h> +<!-- .IN "ViewportP.h" "" --> +Class viewportWidgetClass +<!-- .IN "viewportWidgetClass" "" --> +Class Name Viewport +<!-- .IN "Viewport widget" "class name" --> +Superclass Form +<!-- .sp --> +</literallayout> +</para> +<para> +<!-- .LP --> +The Viewport widget consists of a frame window, one or two Scrollbars, +and an inner window. The size of the frame window is determined by the +viewing size of the data that is to be displayed and the dimensions to +which the Viewport is created. The inner window is the full size of the +data that is to be displayed and is clipped by the frame window. The +Viewport widget controls the scrolling of the data directly. No +application callbacks are required for scrolling. +</para> +<para> +<!-- .LP --> +When the geometry of the frame window is equal in size to the inner +window, or when the data does not require scrolling, the Viewport widget +automatically removes any scrollbars. The <function>forceBars</function> option causes +the Viewport widget to display all scrollbars permanently. +</para> +<sect2 id="viewport_resources"> +<title>Resources</title> +<para> +<!-- .LP --> +When creating a Viewport widget instance, the following resources are +retrieved from the argument list or the resource database: +</para> +<para> +<!-- .LP --> +<!-- .IN "Viewport 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>allowHoriz</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>allowVert</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</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>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>children</entry> + <entry>ReadOnly</entry> + <entry>WidgetList</entry> + <entry>R</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>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>forceBars</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>height</entry> + <entry>Height</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>height of the child</entry> + </row> + <row> + <entry>mappedWhenManaged</entry> + <entry>MappedWhenManaged</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>True</entry> + </row> + <row> + <entry>numChildren</entry> + <entry>ReadOnly</entry> + <entry>Cardinal</entry> + <entry>R</entry> + <entry>0</entry> + </row> + <row> + <entry>reportCallback</entry> + <entry>ReportCallback</entry> + <entry>XtCallbackList</entry> + <entry></entry> + <entry>NULL</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>translations</entry> + <entry>Translations</entry> + <entry>TranslationTable</entry> + <entry></entry> + <entry>NULL</entry> + </row> + <row> + <entry>useBottom</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>useRight</entry> + <entry>Boolean</entry> + <entry>Boolean</entry> + <entry></entry> + <entry>False</entry> + </row> + <row> + <entry>width</entry> + <entry>Width</entry> + <entry>Dimension</entry> + <entry></entry> + <entry>width of the child</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> +<!-- .Ac --> +<variablelist> + <varlistentry> + <term> + <function>allowHoriz</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>allowVert</function> + </term> + <listitem> + <para> +If these resources are <function>False</function> then the Viewport will never create +a scrollbar in this direction. If it is <function>True</function> then the scrollbar will +only appear when it is needed, unless <function>forceBars</function> is <function>True</function>. +<!-- .As --> +<!-- .Bg --> +<!-- .Gp --> +<!-- .Bc --> +<!-- .Bp --> +<!-- .Bw --> +<!-- .Ch --> +<!-- .Cm --> +<!-- .Dp --> +<!-- .Dc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>forceBars</function> + </term> + <listitem> + <para> +When <function>True</function> the scrollbars that have been <emphasis remap='I'>allowed</emphasis> will always be +visible on the screen. If <function>False</function> the scrollbars will be visible only +when the inner window is larger than the frame. +<!-- .Hw --> +<!-- .Mm --> +<!-- .Nc --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>reportCallback</function> + </term> + <listitem> + <para> +These callbacks will be executed whenever the Viewport adjusts the viewed +area of the child. The call_data parameter is a pointer to an XawPannerReport +structure. +<!-- .Sc --> +<!-- .Se --> +<!-- .Tr --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>useBottom</function> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <function>useRight</function> + </term> + <listitem> + <para> +By default the scrollbars appear on the left and top of the screen. +These resources allow the vertical scrollbar to be placed on the right +edge of the Viewport, and the horizontal scrollbar on the bottom edge of +the Viewport. +<!-- .Xy --> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +</sect2> +<sect2 id="viewport_layout_semantics"> +<title>Layout Semantics</title> +<para> +<!-- .LP --> +<!-- .IN "Viewport widget" "layout semantics" --> +The Viewport widget manages a single child widget. When the size of the +child is larger than the size of the Viewport, the user can interactively +move the child within the Viewport by repositioning the scrollbars. +</para> +<para> +<!-- .LP --> +The default size of the Viewport before it is realized is the width and/or +height of the child. After it is realized, the Viewport will allow its +child to grow vertically or horizontally if <function>allowVert</function> or +<function>allowHoriz</function> are set, respectively. If the corresponding vertical +or horizontal scrollbar is not enabled, the Viewport will propagate the +geometry request to its own parent and the child will be allowed to change +size only if the Viewport's parent allows it. Regardless of whether or not +scrollbars are enabled in the corresponding direction, if the child requests +a new size smaller than the Viewport size, the change will be allowed only +if the parent of the Viewport allows the Viewport to shrink to the +appropriate dimension. +</para> +<para> +<!-- .LP --> +The scrollbar children of the Viewport are named <function>horizontal</function> and +<function>vertical</function>. By using these names the programmer can specify resources +for the individual scrollbars. <function>XtSetValues</function> can be used to modify +the resources dynamically once the widget ID has been obtained with +<function>XtNameToWidget</function>. +<!-- .IN "XtNameToWidget" "" --> +<!-- .NT --> +</para> +<note><para> +Although the Viewport is a Subclass of the Form, no resources for the Form +may be supplied for any of the children of the Viewport. These constraints +are managed internally and are not meant for public consumption. +</para></note> +<!-- .NE --> + +</sect2> +</sect1> diff --git a/libXaw/specs/libXaw.xml b/libXaw/specs/libXaw.xml new file mode 100644 index 000000000..d8a0a35bc --- /dev/null +++ b/libXaw/specs/libXaw.xml @@ -0,0 +1,88 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<book id="libXaw"> + +<bookinfo> + <title>Athena Widget Set - C Language Interface</title> + <subtitle>X Consortium Standard</subtitle> + <releaseinfo>X Version 11, Release 6.4</releaseinfo> + <authorgroup> + <author> + <firstname>Chris</firstname><surname>Peterson</surname> + </author> + </authorgroup> + <copyright><year>1985</year><holder>X Consortium</holder></copyright> + <copyright><year>1986</year><holder>X Consortium</holder></copyright> + <copyright><year>1987</year><holder>X Consortium</holder></copyright> + <copyright><year>1988</year><holder>X Consortium</holder></copyright> + <copyright><year>1989</year><holder>X Consortium</holder></copyright> + <copyright><year>1991</year><holder>X Consortium</holder></copyright> + <copyright><year>1994</year><holder>X Consortium</holder></copyright> + <releaseinfo>libXaw 1.0.7</releaseinfo> + <affiliation><orgname>formerly MIT X Consortium</orgname></affiliation> + <productnumber>X Version 11, Release 7</productnumber> + +<legalnotice> + +<para> +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files +(the “Software”), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to permit +persons to whom the Software is furnished to do so, subject to the following +conditions: +</para> + +<para> +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. +</para> + +<para> +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +</para> + +<para> +Except as contained in this notice, the name of the X Consortium shall not +be used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +</para> + +<para> +Permission to use, copy, modify and distribute this documentation for any +purpose and without fee is hereby granted, provided that the above copyright +notice appears in all copies and that both that copyright notice and this +permission notice appear in supporting documentation, and that the name of +Digital not be used in in advertising or publicity pertaining +to distribution of the software without specific, written prior permission. +Digital makes no representations about the suitability of the +software described herein for any purpose. +It is provided ``as is'' without express or implied warranty. +</para> + +<para> +Except as contained in this notice, the name of the X Consortium shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from the X Consortium. +</para> +</legalnotice> +</bookinfo> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH1.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH2.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH3.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH4.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH5.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH6.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="CH7.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="TPage_Credits.xml"/> +</book> + |