diff options
Diffstat (limited to 'libXaw/spec/List')
| -rw-r--r-- | libXaw/spec/List | 341 |
1 files changed, 0 insertions, 341 deletions
diff --git a/libXaw/spec/List b/libXaw/spec/List deleted file mode 100644 index 1b64aaaf5..000000000 --- a/libXaw/spec/List +++ /dev/null @@ -1,341 +0,0 @@ -.\" $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 |