342 lines
10 KiB
Plaintext
342 lines
10 KiB
Plaintext
.\" $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
|