diff options
Diffstat (limited to 'libXaw/spec/List')
| -rw-r--r-- | libXaw/spec/List | 341 |
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 |