Added libXaw-1.0.7

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