diff options
Diffstat (limited to 'libXaw/specs/Scrollbar.xml')
| -rw-r--r-- | libXaw/specs/Scrollbar.xml | 884 |
1 files changed, 884 insertions, 0 deletions
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> |