aboutsummaryrefslogtreecommitdiff
path: root/libXaw/spec/List
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
committermarha <marha@users.sourceforge.net>2009-11-06 06:59:46 +0000
commitace7902333b6f61aab5a6035dbcb222763bff186 (patch)
tree28445e829d5f04c8d79bda2514be37d5fb29738e /libXaw/spec/List
parentc9179017c7e70703b7cac46c2df8b950506319e0 (diff)
downloadvcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.gz
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.tar.bz2
vcxsrv-ace7902333b6f61aab5a6035dbcb222763bff186.zip
Added libXaw-1.0.7
Diffstat (limited to 'libXaw/spec/List')
-rw-r--r--libXaw/spec/List341
1 files changed, 341 insertions, 0 deletions
diff --git a/libXaw/spec/List b/libXaw/spec/List
new file mode 100644
index 000000000..1b64aaaf5
--- /dev/null
+++ b/libXaw/spec/List
@@ -0,0 +1,341 @@
+.\" $Xorg: List,v 1.3 2000/08/17 19:42:27 cpqbld Exp $
+.NH 2
+List Widget
+.LP
+.XS
+ List Widget
+.XE
+.IN "List widget" "" "@DEF@"
+.Ds 0
+.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
+.De
+.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 \fBNotify\fP action is invoked, calling all routines on
+its callback list. Only one string may be selected at a time.
+.NH 3
+Resources
+.LP
+When creating a List widget instance, the following resources are
+retrieved from the argument list or from the resource database:
+.LP
+.IN "List widget" "resources"
+.TS H
+expand;
+lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
+_
+.sp 3p
+.TB
+Name Class Type Notes Default Value
+.sp 3p
+_
+.TH
+.R
+.sp 3p
+accelerators Accelerators AcceleratorTable NULL
+ancestorSensitive AncestorSensitive Boolean D True
+background Background Pixel XtDefaultBackground
+backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap
+borderColor BorderColor Pixel XtDefaultForeground
+borderPixmap Pixmap Pixmap XtUnspecifiedPixmap
+borderWidth BorderWidth Dimension 1
+callback Callback Callback NULL
+colormap Colormap Colormap Parent's Colormap
+columnSpacing Spacing Dimension 6
+cursor Cursor Cursor XC_left_ptr
+cursorName Cursor String NULL
+defaultColumns Columns int 2
+depth Depth int C Parent's Depth
+destroyCallback Callback XtCallbackList NULL
+font Font FontStruct XtDefaultFont
+fontSet FontSet XFontSet XtDefaultFontSet
+forceColumns Columns Boolean False
+foreground Foreground Pixel XtDefaultForeground
+height Height Dimension A Enough space to contain the list
+insensitiveBorder Insensitive Pixmap GreyPixmap
+internalHeight Height Dimension 2
+internalWidth Width Dimension 4
+international International Boolean C False
+list List Pointer name of widget
+longest Longest int A 0
+mappedWhenManaged MappedWhenManaged Boolean True
+numberStrings NumberStrings int A computed for NULL terminated list
+pasteBuffer Boolean Boolean False
+pointerColor Foreground Pixel XtDefaultForeground
+pointerColorBackground Background Pixel XtDefaultBackground
+rowSpacing Spacing Dimension 2
+screen Screen Screen R Parent's Screen
+sensitive Sensitive Boolean True
+translations Translations TranslationTable See below
+verticalList Boolean Boolean False
+width Width Dimension A Enough space to contain the list
+x Position Position 0
+y Position Position 0
+.sp 3p
+_
+.TE
+.Ac
+.As
+.Bg
+.Gp
+.Bc
+.Bp
+.Bw
+.IP \fBcallback\fP 1.5i
+All functions on this list are called whenever the \fBnotify\fP action is
+invoked. The \fIcall_data\fP argument contains information about the element
+selected and is described in detail in the \fBList Callbacks\fP section.
+.Cm
+.IP \fBcolumnSpacing\fP 1.5i
+.br
+.ns
+.IP \fBrowSpacing\fP 1.5i
+The amount of space, in pixels, between each of the rows and columns
+in the list.
+.Cu
+.Cn
+.IP \fBdefaultColumns\fP 1.5i
+The default number of columns. This value is used when neither the
+width nor the height of the List widget is specified or when
+\fBforceColumns\fP is \fBTrue\fP.
+.Dp
+.Dc
+.IP \fBfont\fP
+The text font to use when displaying the \fBlist\fP, when the
+\fBinternational\fP resource is \fBfalse\fP.
+.IP \fBfontSet\fP
+The text font set to use when displaying the \fBlist\fP, when the
+\fBinternational\fP resource is \fBtrue\fP.
+.IP \fBforceColumns\fP
+Forces the default number of columns to be used regardless of the
+List widget's current size.
+.IP \fBforeground\fP 1.5i
+A pixel value which indexes the widget's colormap to derive the color
+used to paint the text of the list elements.
+.Hw
+.Ib
+.IP \fPinternalHeight\fP 1.5i
+.br
+.ns
+.IP \fPinternalWidth\fP 1.5i
+The margin, in pixels, between the edges of the list and the
+corresponding edge of the List widget's window.
+.IP \fBlist\fP 1.5i
+An array of text strings displayed in the List widget. If
+\fBnumberStrings\fP is zero (the default) then the \fBlist\fP must be
+NULL terminated. If a value is not specified for the \fBlist\fP, then
+\fBnumberStrings\fP is set to 1, and the name of the widget is used as
+the \fBlist\fP, and \fBlongest\fP is set to the length of the name of the
+widget. The \fBlist\fP is used in place, and must be available
+to the List widget for the lifetime of this widget, or until it is
+changed with \fBXtSetValues\fP or \fBXawListChange\fP.
+.In
+.IP \fBlongest\fP
+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
+.IP \fBnumberStrings\fP 1.5i
+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 \fBlist\fP is NULL
+terminated.
+.IP \fBpasteBuffer\fP 1.5i
+If this resource is set to \fBTrue\fP then the name of the currently
+selected list element will be put into \fBCUT_BUFFER_0\fP.
+.Pf
+.Pb
+.Sc
+.Se
+.Tr
+.IP \fBverticalList\fP 1.5i
+If this resource is set to \fBTrue\fP then the list elements will be
+presented in column major order.
+.Xy
+.NH 3
+List Actions
+.IN "List widget" "actions"
+.LP
+The List widget supports the following actions:
+.IP \(bu 5
+Highlighting and unhighlighting the list element under the
+pointer with \fBSet\fP and \fBUnset\fP
+.IP \(bu 5
+Processing application callbacks with \fBNotify\fP
+.LP
+The following is the default translation table used by the List Widget:
+.IN "List widget" "default translation table"
+.LP
+.Ds
+.TA .5i 2.25i
+.ta .5i 2.25i
+<Btn1Down>,<Btn1Up>: Set(\|) Notify(\|)
+.sp
+.De
+.LP
+The full list of actions supported by List widget is:
+.IP \fBSet\fP(\|) 1.5i
+\fISets\fP 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 \fIset\fP
+element will be \fIunset\fP.
+.IP \fBUnset\fP(\|) 1.5i
+Cancels the \fIset\fP state of the element under the pointer,
+and redraws it with normal foreground and background colors.
+.IP \fBNotify\fP(\|) 1.5i
+Calls all callbacks on the List widget's callback list. Information
+about the currently selected list element is passed in the
+\fIcall_data\fP argument (see \fBList Callbacks\fP below).
+.NH 3
+List Callbacks
+.IN "List widget" "callbacks"
+.LP
+All procedures on the List widget's callback list will have a
+\fBXawListReturnStruct\fP passed to them as \fIcall_data\fP. The
+structure is defined in the List widget's application header file.
+.LP
+.Ds 0
+.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
+The \fIlist_index\fP item used to be called simply \fIindex\fP.
+Unfortunately, this name collided with a global name defined on some
+operating systems, and had to be changed.
+.NE
+.De
+.NH 3
+Changing the List
+.LP
+To change the list that is displayed, use
+.PN XawListChange .
+.IN "XawListChange" "" "@DEF@"
+.FD 0
+void XawListChange(\fIw\fP, \fIlist\fP, \fInitems\fP, \fIlongest\fP, \fIresize\fP)
+.br
+ Widget \fIw\fP;
+.br
+ String * \fIlist\fP;
+.br
+ int \fInitems\fP, \fIlongest\fP;
+.br
+ Boolean \fIresize\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the List widget.
+.IP \fIlist\fP 1i
+Specifies the new list for the List widget to display.
+.IP \fInitems\fP 1i
+Specifies the number of items in the \fIlist\fP. If a value less than 1
+is specified, \fIlist\fP must be NULL terminated, and the number of
+items will be calculated by the List widget.
+.IP \fIlongest\fP 1i
+Specifies the length of the longest item in the \fIlist\fP in pixels.
+If a value less than 1 is specified, the List widget will calculate the
+value.
+.IP \fIresize\fP 1i
+Specifies a Boolean value that if \fBTrue\fP 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.
+.LP
+.PN XawListChange
+will \fIunset\fP all list elements that are currently \fBset\fP before
+the list is actually changed. The \fIlist\fP is used in place, and must
+remain usable for the lifetime of the List widget, or until \fIlist\fP
+has been changed again with this function or with \fBXtSetValues\fP.
+.NH 3
+Highlighting an Item
+.LP
+To highlight an item in the list, use
+.PN XawListHighlight .
+.IN "XawListHighlight" "" "@DEF@"
+.FD 0
+void XawListHighlight(\fIw\fP, \fIitem\fP)
+.br
+ Widget \fIw\fP;
+.br
+ int \fIitem\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the List widget.
+.IP \fIitem\fP 1i
+Specifies an index into the current list that indicates the item to be
+highlighted.
+.LP
+Only one item can be highlighted at a time.
+If an item is already highlighted when
+.PN XawListHighlight
+is called,
+the highlighted item is unhighlighted before the new item is highlighted.
+.NH 3
+Unhighlighting an Item
+.LP
+To unhighlight the currently highlighted item in the list, use
+.PN XawListUnhighlight .
+.IN "XawListUnhighlight" "" "@DEF@"
+.FD 0
+void XawListUnhighlight(\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the List widget.
+.NH 3
+Retrieving the Currently Selected Item
+.LP
+To retrieve the list element that is currently \fIset\fP, use
+.PN XawListShowCurrent .
+.IN "XawListShowCurrent" "" "@DEF@"
+.FD 0
+XawListReturnStruct *XawListShowCurrent(\fIw\fP)
+.br
+ Widget \fIw\fP;
+.FN
+.IP \fIw\fP 1i
+Specifies the List widget.
+.LP
+.PN XawListShowCurrent
+returns a pointer to an
+.PN XawListReturnStruct
+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.
+.NH 3
+Restrictions
+.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.'')
+.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.)
+.LP