'\" t .\" List.sgm /main/12 1996/09/08 20:49:54 rws $ .de P! .fl \!!1 setgray .fl \\&.\" .fl \!!0 setgray .fl \" force out current output buffer \!!save /psv exch def currentpoint translate 0 0 moveto \!!/showpage{}def .fl \" prolog .sy sed -e 's/^/!/' \\$1\" bring in postscript file \!!psv restore . .de pF .ie \\*(f1 .ds f1 \\n(.f .el .ie \\*(f2 .ds f2 \\n(.f .el .ie \\*(f3 .ds f3 \\n(.f .el .ie \\*(f4 .ds f4 \\n(.f .el .tm ? font overflow .ft \\$1 .. .de fP .ie !\\*(f4 \{\ . ft \\*(f4 . ds f4\" ' br \} .el .ie !\\*(f3 \{\ . ft \\*(f3 . ds f3\" ' br \} .el .ie !\\*(f2 \{\ . ft \\*(f2 . ds f2\" ' br \} .el .ie !\\*(f1 \{\ . ft \\*(f1 . ds f1\" ' br \} .el .tm ? font underflow .. .ds f1\" .ds f2\" .ds f3\" .ds f4\" .ta 8n 16n 24n 32n 40n 48n 56n 64n 72n .TH "XmList" 3 .SH "NAME" \fBXmList\fP \(em The List widget class "XmList" "widget class" "List" .SH "SYNOPSIS" .PP .nf #include .fi .SH "DESCRIPTION" .PP List allows a user to select one or more items from a group of choices\&. Items are selected from the list in a variety of ways, using both the pointer and the keyboard\&. List operates on an array of compound strings that are defined by the application\&. Each compound string becomes an item in the List, with the first compound string becoming the item in position 1, the second becoming the item in position 2, and so on\&. .PP Specifying the number of items that are visible sets the size of the List\&. If the number of visible items is not specified, the height of the list controls the number of visible items\&. Each item assumes the height of the tallest element in the list\&. To create a list that allows the user to scroll easily through a large number of items, use the \fBXmCreateScrolledList\fP convenience function\&. .PP To select items, move the pointer or cursor to the desired item and press the \fB\fP mouse button or the key defined as \fB\fP\&. There are several styles of selection behavior, and they all highlight the selected item or items by displaying them in inverse colors\&. An appropriate callback is invoked to notify the application of the user\&'s choice\&. The application then takes whatever action is required for the specified selection\&. When a List is insensitive, all of the list items are displayed in a stippled fill pattern\&. .PP List uses the \fBXmQTspecifyRenderTable\fP, \fBXmQTscrollFrame\fP, and \fBXmQTnavigator\fP traits, and holds the \fBXmQTtransfer\fP trait\&. .SS "Selection" .PP Each list has one of four selection models: .IP " \(bu" 6 Single Select .IP " \(bu" 6 Browse Select .IP " \(bu" 6 Multiple Select .IP " \(bu" 6 Extended Select .PP In Single Select and Browse Select, at most one item is selected at a time\&. In Single Select, pressing \fB\fP on an item toggles its selection state and deselects any other selected item\&. In Browse Select, pressing \fB\fP on an item selects it and deselects any other selected item; dragging \fB\fP moves the selection as the pointer is moved\&. Releasing \fB\fP on an item moves the location cursor to that item\&. .PP In Multiple Select, any number of items can be selected at a time\&. Pressing \fB\fP on an item toggles its selection state but does not deselect any other selected items\&. .PP In Extended Select, any number of items can be selected at a time, and the user can easily select ranges of items\&. Pressing \fB\fP on an item selects it and deselects any other selected item\&. Dragging \fB\fP or pressing or dragging \fB\fP\fB\fP following a \fB\fP action selects all items between the item under the pointer and the item on which \fB\fP was pressed\&. This action also deselects any other selected items outside that range\&. .PP Extended Select also allows the user to select and deselect discontiguous ranges of items\&. Pressing \fB\fP\fB\fP on an item toggles its selection state but does not deselect any other selected items\&. Dragging \fB\fP\fB\fP or pressing or dragging \fB\fP\fB\fP following a \fB\fP\fB\fP action sets the selection state of all items between the item under the pointer and the item on which \fB\fP\fB\fP was pressed to the state of the item on which \fB\fP\fB\fP was pressed\&. This action does not deselect any other selected items outside that range\&. .PP All selection operations available from the mouse are also available from the keyboard\&. List has two keyboard selection modes, Normal Mode and Add Mode\&. In Normal Mode, navigation operations and \fB\fP select the item at the location cursor and deselect any other selected items\&. In Add Mode, navigation operations have no effect on selection, and \fB\fP toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select\&. .PP Single and Multiple Select use Add Mode, and Browse Select uses Normal Mode\&. .PP Extended Select can use either mode; the user changes modes by pressing \fB\fP\&. In Extended Select Normal Mode, pressing \fB\fP has the same effect as pressing \fB\fP; \fB\fP and shifted navigation have the same effect as pressing \fB\fP\fB\fP following a \fB\fP action\&. In Extended Select Add Mode, pressing \fB\fP has the same effect as pressing \fB\fP\fB\fP; \fB\fP and shifted navigation have the same effect as pressing \fB\fP\fB\fP following a \fB\fP\fB\fP action\&. .PP Normal Mode is indicated by a solid location cursor, and Add Mode is indicated by a dashed location cursor\&. .SS "Data Transfer Behavior" .PP List supports dragging of items from the List and transfer of items to the clipboard\&. When the user presses \fBBTransfer\fP on a selected item, the widget transfers all selected items\&. When the user presses \fBBTransfer\fP on an unselected item, the widget transfers only that item\&. Depending on the value of \fBXmNprimaryOwnership\fP, List can also support primary selection\&. .PP When the \fBXmNconvertCallback\fP procedures are called, the \fBlocation_data\fP member of the \fBXmConvertCallbackStruct\fR member is NULL if the selected items are being transferred\&. If the selected items are not being transferred, this member has the following value: If a single item is being transferred, the value is an integer representing the position of the item in the List\&. A value of 1 transfers the first item in the List; a value of 2 transfers the second item; and so on\&. If the entire contents of the List are being transferred, the value is \-1\&. .PP As a source of data, List supports the following targets and associated conversions of data to these targets: .IP "\fIlocale\fP" 10 If the \fIlocale\fP target matches the widget\&'s locale, the widget transfers the selected list items in the encoding of the locale\&. Each item transferred except the last includes a trailing separator\&. .IP "\fBCOMPOUND_TEXT\fP" 10 The widget transfers the selected list items as type \fBCOMPOUND_TEXT\fP\&. Each item transferred except the last includes a trailing separator\&. .IP "\fBUTF8_STRING\fP" 10 The widget transfers the selected list items as type \fBUTF8_STRING\fP\&. Each item transferred except the last includes a trailing separator\&. .IP "\fBSTRING\fP" 10 The widget transfers the selected list items as type \fBSTRING\fP\&. Each item transferred except the last includes a trailing separator\&. .IP "\fBTEXT\fP" 10 If the selected list items are fully convertible to the encoding of the locale, the widget transfers the selected list items in the encoding of the locale\&. Otherwise, the widget transfers the selected list items as type \fBCOMPOUND_TEXT\fP\&. Each item transferred except the last includes a trailing separator\&. .IP "\fB_MOTIF_CLIPBOARD_TARGETS\fP" 10 The widget transfers, as type \fBATOM\fP, a list of the targets it supports for immediate transfer for the \fBCLIPBOARD\fP selection\&. These include \fB_MOTIF_COMPOUND_STRING\fP\&. If the selected list items are fully convertible to \fBSTRING\fP, these also include \fBSTRING\fP; otherwise, they also include \fBCOMPOUND_TEXT\fP and \fBUTF8_STRING\fP\&. .IP "\fB_MOTIF_COMPOUND_STRING\fP" 10 The widget transfers the selected list items as a compound string in Byte Stream format\&. Each item transferred except the last includes a trailing separator\&. .IP "\fB_MOTIF_DEFERRED_CLIPBOARD_TARGETS\fP" 10 The widget transfers, as type \fBATOM\fP, a list of the targets it supports for delayed transfer for the \fBCLIPBOARD\fP selection\&. This widget currently supplies no targets for \fB_MOTIF_DEFERRED_CLIPBOARD_TARGETS\fP\&. .IP "\fB_MOTIF_EXPORT_TARGETS\fP" 10 The widget transfers, as type \fBATOM\fP, a list of the targets to be used as the value of the DragContext\&'s \fBXmNexportTargets\fP in a drag-and-drop transfer\&. These include \fB_MOTIF_COMPOUND_STRING\fP, \fBCOMPOUND_TEXT\fP, \fBUTF8_STRING\fP, the encoding of the locale, \fBSTRING\fP, \fBTEXT\fP, \fBBACKGROUND\fP, and \fBFOREGROUND\fP\&. .IP "\fB_MOTIF_LOSE_SELECTION\fP" 10 When the widget loses the selection, it deselects all list items\&. .PP As a source of data, List also supports the following standard Motif targets: .IP "\fBBACKGROUND\fP" 10 The widget transfers \fBXmNbackground\fP as type \fBPIXEL\fP\&. .IP "\fBCLASS\fP" 10 The widget finds the first shell in the widget hierarchy that has a \fBWM_CLASS\fP property and transfers the contents as text in the current locale\&. .IP "\fBCLIENT_WINDOW\fP" 10 The widget finds the first shell in the widget hierarchy and transfers its window as type \fBWINDOW\fP\&. .IP "\fBCOLORMAP\fP" 10 The widget transfers \fBXmNcolormap\fP as type \fBCOLORMAP\fP\&. .IP "\fBFOREGROUND\fP" 10 The widget transfers \fBXmNforeground\fP as type \fBPIXEL\fP\&. .IP "\fBNAME\fP" 10 The widget finds the first shell in the widget hierarchy that has a \fBWM_NAME\fP property and transfers the contents as text in the current locale\&. .IP "\fBTARGETS\fP" 10 The widget transfers, as type \fBATOM\fP, a list of the targets it supports\&. These include the standard targets in this list\&. These also include \fB_MOTIF_COMPOUND_STRING\fP, \fBCOMPOUND_TEXT\fP, \fBUTF8_STRING\fP the encoding of the locale, \fBSTRING\fP, and \fBTEXT\fP\&. .IP "\fBTIMESTAMP\fP" 10 The widget transfers the timestamp used to acquire the selection as type \fBINTEGER\fP\&. .IP "\fB_MOTIF_RENDER_TABLE\fP" 10 The widget transfers \fBXmNrenderTable\fP if it exists, or else the default text render table, as type \fBSTRING\fP\&. .IP "\fB_MOTIF_ENCODING_REGISTRY\fP" 10 The widget transfers its encoding registry as type \fBSTRING\fP\&. The value is a list of NULL separated items in the form of tag encoding pairs\&. This target symbolizes the transfer target for the Motif Segment Encoding Registry\&. Widgets and applications can use this Registry to register text encoding formats for specified render table tags\&. Applications access this Registry by calling \fBXmRegisterSegmentEncoding\fP and \fBXmMapSegmentEncoding\fP\&. .PP List has no widget class destination procedure\&. Subclasses and the \fBXmNdestinationCallback\fP procedures are responsible for any data transfers to the widget\&. .SS "Classes" .PP List inherits behavior, resources, and traits from \fBCore\fP and \fBXmPrimitive\fP\&. .PP The class pointer is \fBxmListWidgetClass\fP\&. .PP The class name is \fBXmList\fP\&. .SS "New Resources" .PP The following table defines a set of widget resources used by the programmer to specify data\&. The programmer can also set the resource values for the inherited classes to set attributes for this widget\&. To reference a resource by name or by class in a \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or \fBXmC\fP prefix and use the remaining letters\&. To specify one of the defined values for a resource in a \fB\&.Xdefaults\fP file, remove the \fBXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words)\&. The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fBXtSetValues\fP (S), retrieved by using \fBXtGetValues\fP (G), or is not applicable (N/A)\&. .PP .TS tab() box; c s s s s l| l| l| l| l. \fBXmList Resource Set\fP \fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP _____ XmNautomaticSelectionXmCAutomaticSelectionXtEnumFalseCSG _____ XmNbrowseSelectionCallbackXmCCallbackXtCallbackListNULLC _____ XmNdefaultActionCallbackXmCCallbackXtCallbackListNULLC _____ XmNdestinationCallbackXmCCallbackXtCallbackListNULLC _____ XmNdoubleClickIntervalXmCDoubleClickIntervalintdynamicCSG _____ XmNextendedSelectionCallbackXmCCallbackXtCallbackListNULLC _____ XmNfontListXmCFontListXmFontListdynamicCSG _____ XmNitemCountXmCItemCountint0CSG _____ XmNitemsXmCItemsXmStringTableNULLCSG _____ XmNlistMarginHeightXmCListMarginHeightDimension0CSG _____ XmNlistMarginWidthXmCListMarginWidthDimension0CSG _____ XmNlistSizePolicyXmCListSizePolicyunsigned charXmVARIABLECG _____ XmNlistSpacingXmCListSpacingDimension0CSG _____ XmNmatchBehaviorXmCMatchBehaviorunsigned charXmQUICK_NAVIGATECSG _____ XmNmultipleSelectionCallbackXmCCallbackXtCallbackListNULLC _____ XmNprimaryOwnershipXmCPrimaryOwnershipunsigned charXmOWN_NEVERCSG _____ XmNrenderTableXmCRenderTableXmRenderTabledynamicCSG _____ XmNscrollBarDisplayPolicyXmCScrollBarDisplayPolicyunsigned charXmAS_NEEDEDCSG _____ XmNselectColorXmCSelectColorXmRSelectColorXmREVERSED_GROUND_COLORSCSG _____ XmNselectedItemCountXmCSelectedItemCountint0CSG _____ XmNselectedItemsXmCSelectedItemsXmStringTableNULLCSG _____ XmNselectedPositionCountXmCSelectedPositionCountint0CSG _____ XmNselectedPositionsXmCSelectedPositionsunsigned int *NULLCSG _____ XmNselectionModeXmCSelectionModeunsigned chardynamicCSG _____ XmNselectionPolicyXmCSelectionPolicyunsigned charXmBROWSE_SELECTCSG _____ XmNsingleSelectionCallbackXmCCallbackXtCallbackListNULLC _____ XmNstringDirectionXmCStringDirectionXmStringDirectiondynamicCSG _____ XmNtopItemPositionXmCTopItemPositionint1CSG _____ XmNvisibleItemCountXmCVisibleItemCountintdynamicCSG _____ .TE .IP "\fBXmNautomaticSelection\fP" 10 Invokes either \fBXmNbrowseSelectionCallback\fP or \fBXmNextendedSelectionCallback\fP when \fB\fP is pressed and the items that are shown as selected change if the value is True (or \fBXmAUTO\fP) and the selection mode is either \fBXmBROWSE_SELECT\fP or \fBXmEXTENDED_SELECT\fP respectively\&. If False (\fBXmNO_AUTO_SELECT\fP), no selection callbacks are invoked until the user releases the mouse button\&. See \fBBehavior\fP for further details on the interaction of this resource with the selection modes\&. .IP "\fBXmNbrowseSelectionCallback\fP" 10 Specifies a list of callbacks that is called when an item is selected in the browse selection mode\&. The reason is \fBXmCR_BROWSE_SELECT\fP\&. .IP "\fBXmNdefaultActionCallback\fP" 10 Specifies a list of callbacks that is called when an item is double clicked or \fB\fP is pressed\&. The reason is \fBXmCR_DEFAULT_ACTION\fP\&. .IP "\fBXmNdestinationCallback\fP" 10 Specifies a list of callbacks called when the List is the destination of a transfer operation\&. The type of the structure whose address is passed to these callbacks is \fBXmDestinationCallbackStruct\fR\&. The reason is \fBXmCR_OK\fP\&. .IP "\fBXmNdoubleClickInterval\fP" 10 If a button click is followed by another button click within the time span specified by this resource (in milliseconds), the button clicks are considered a double-click action, rather than two single-click actions\&. The value must not be negative\&. The default value is the display\&'s multiclick time\&. .IP "\fBXmNextendedSelectionCallback\fP" 10 Specifies a list of callbacks that is called when items are selected using the extended selection mode\&. The reason is \fBXmCR_EXTENDED_SELECT\fP\&. .IP "\fBXmNfontList\fP" 10 Specifies the font list associated with the list items\&. \fBXmNfontList\fP is obsolete and exists only for compatibility with previous releases\&. You should now use \fBXmNrenderTable\fP instead of \fBXmNfontList\fP\&. If both are specified, the render table will take precedence\&. The font list is used in conjunction with the \fBXmNvisibleItemCount\fP resource to determine the height of the List widget\&. If this value is NULL at initialization, the parent hierarchy of the widget is searched for a widget that holds the \fBXmQTspecifyRenderTable\fP trait\&. If such an ancestor is found, the font list is initialized to the \fBXmTEXT_RENDER_TABLE\fP value of the ancestor widget\&. If no such widget is found, the default is implementation dependent\&. Refer to \fBXmFontList\fP(3) for more information on a font list structure\&. .IP "\fBXmNitemCount\fP" 10 Specifies the total number of items\&. The value must be the number of items in \fBXmNitems\fP and must not be negative\&. It is automatically updated by the list whenever an item is added to or deleted from the list\&. .IP "\fBXmNitems\fP" 10 Points to an array of compound strings that are to be displayed as the list items\&. Refer to \fBXmString\fP(3) for more information on the creation and structure of compound strings\&. \fBXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items\&. The application must not free the returned items\&. .IP "\fBXmNlistMarginHeight\fP" 10 Specifies the height of the margin between the list border and the items\&. .IP "\fBXmNlistMarginWidth\fP" 10 Specifies the width of the margin between the list border and the items\&. .IP "\fBXmNlistSizePolicy\fP" 10 Controls the reaction of the List when an item grows horizontally beyond the current size of the list work area\&. If the value is \fBXmCONSTANT\fP, the list viewing area does not grow, and a horizontal ScrollBar is added for a List whose parent is a ScrolledWindow\&. If this resource is set to \fBXmVARIABLE\fP, the List grows to match the size of the longest item, and no horizontal ScrollBar appears\&. .IP "" 10 When the value of this resource is \fBXmRESIZE_IF_POSSIBLE\fP, the List attempts to grow or shrink to match the width of the widest item\&. If it cannot grow to match the widest size, a horizontal ScrollBar is added for a List whose parent is a ScrolledWindow if the longest item is wider than the list viewing area\&. .IP "" 10 The size policy must be set at the time the List widget is created\&. It cannot be changed at a later time through \fBXtSetValues\fP\&. .IP "\fBXmNlistSpacing\fP" 10 Specifies the spacing between list items\&. This spacing increases by the value of the \fBXmNhighlightThickness\fP resource in Primitive\&. .IP "\fBXmNmatchBehavior\fP" 10 Specifies the matching behavior followed by XmList\&. The current values are \fBXmNONE\fP and \fBXmQUICK_NAVIGATE\fP, as follows: .RS .IP "\fBXmNONE\fP" 10 Specifies that the typed in characters are ignored\&. .IP "\fBXmQUICK_NAVIGATE\fP" 10 Specifies that 1-character navigation shall be supported when List has focus\&. If the typed character is the initial character of some set of items in List, the first of those items following the current item will be navigated to (become the current item)\&. If all such items precede the current item, the first such item becomes the current item\&. Subsequently, typing the same character will cyclically navigate among the items with the same first character\&. .RE .IP "\fBXmNmultipleSelectionCallback\fP" 10 Specifies a list of callbacks that is called when an item is selected in multiple selection mode\&. The reason is \fBXmCR_MULTIPLE_SELECT\fP\&. .IP "\fBXmNprimaryOwnership\fP" 10 Specifies whether XmContainer takes ownership of the Primary selection when a selection is made inside it\&. This resource can take the following values: .RS .IP "\fBXmOWN_NEVER\fP" 10 Never takes ownership\&. .IP "\fBXmOWN_ALWAYS\fP" 10 Always takes ownership\&. .IP "\fBXmOWN_MULTIPLE\fP" 10 Only takes ownership is more than one element has been selected\&. .IP "\fBXmOWN_POSSIBLE_MULTIPLE\fP" 10 Only takes ownership if more than one element can be selected at a time\&. .RE .IP "\fBXmNrenderTable\fP" 10 Specifies the render table associated with the list items\&. The render table is used in conjunction with the \fBXmNvisibleItemCount\fP resource to determine the height of the List widget\&. If this value is NULL at initialization, List searches its parent hierarchy for a widget that holds the \fBXmQTspecifyRenderTable\fP trait\&. If such an ancestor is found, the render table is initialized to the \fBXmTEXT_RENDER_TABLE\fP value of the ancestor widget\&. If no such widget is found, the default is implementation dependent\&. If a font list and a render table are both specified, the render table will take precedence\&. Refer to \fBXmRenderTable\fP(3) for more information on the creation and structure of a render table\&. .IP "\fBXmNscrollBarDisplayPolicy\fP" 10 Controls the display of vertical ScrollBars in a List whose parent is a ScrolledWindow\&. When the value of this resource is \fBXmAS_NEEDED\fP, a vertical ScrollBar is displayed only when the number of items in the List exceeds the number of visible items\&. When the value is \fBXmSTATIC\fP, a vertical ScrollBar is always displayed\&. .IP "\fBXmNselectColor\fP" 10 Allows the application to specify the color of the background rectangle that indicates selected text\&. It takes two values: .RS .IP "\fBXmDEFAULT_SELECT_COLOR\fP" 10 Causes the select color to be set to a color between the background and the bottom shadow color\&. .IP "\fBXmREVERSED_GROUND_COLORS\fP" 10 Forces the select color to the foreground color and the color of any text rendered over the select color to be in the background color\&. .IP "\fBHIGHLIGHT_COLOR\fP" 10 Forces the fill color to use the highlight color\&. .RE .IP "\fBXmNselectedItemCount\fP" 10 Specifies the number of strings in the selected items list\&. The value must be the number of items in \fBXmNselectedItems\fP and must not be negative\&. .IP "\fBXmNselectedItems\fP" 10 Points to an array of compound strings that represents the list items that are currently selected, either by the user or by the application\&. \fBXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items\&. The application must not free the returned items or the array\&. .IP "" 10 Setting \fBXmNselectedItems\fP selects those list items that exactly match items in the given \fBXmNselectedItems\fP list\&. There may be additional items in \fBXmNselectedItems\fP that do not match items in the list\&. These items remain until \fBXmNselectedItems\fP is updated\&. If \fBXmNitems\fP is changed such that the list now contains items matching previously unmatched items in \fBXmNselectedItems\fP, those new items will also appear selected\&. .IP "" 10 Any user interaction with the list that causes at least one item to be selected or deselected and any call to \fBXmListDeleteAllItems\fP, \fBXmListDeleteItem\fP, \fBXmListDeleteItems\fP, \fBXmListDeleteItemsPos\fP, \fBXmListDeletePos\fP, \fBXmListDeletePositions\fP, \fBXmListDeselectAllItems\fP, \fBXmListDeselectItem\fP, \fBXmListDeselectPos\fP, \fBXmListSelectItem\fP, \fBXmListSelectPos\fP, or \fBXmListUpdateSelectedList\fP cause \fBXmNselectedItems\fP to be updated immediately to exactly reflect the visual state of the list\&. Calls to any other \fBXmList\fP functions do not affect \fBXmNselectedItems\fP\&. .IP "\fBXmNselectedPositionCount\fP" 10 Specifies the number of positions in the selected positions list\&. The value must be the number of items in \fBXmNselectedPositions\fP .IP "\fBXmNselectedPositions\fP" 10 Points to an array of the positions of the selected items in the List\&. \fBXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items\&. The application must not free the returned items or the array\&. .IP "\fBXmNselectionMode\fP" 10 Defines what effect keyboard navigations have on selection\&. The valid modes are: .RS .IP "\fBXmADD_MODE\fP" 10 Allows no navigation operations to have effect on selection, and \fB\fP toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select\&. However, the widget cannot be put into add mode if the \fBXmNselectionPolicy\fP resource is an incompatible mode (\fBXmNselectionPolicy\fP cannot be \fBXmBROWSE_SELECT\fP)\&. .IP "\fBXmNORMAL_MODE\fP" 10 Allows navigation operations and \fB\fP to select the item at the location cursor and deselect any other selected items\&. However, the widget cannot be put into normal mode if the \fBXmNselectionPolicy\fP resource is an incompatible mode (\fBXmNselectionPolicy\fP cannot be \fBXmSINGLE_SELECT\fP or \fBXmMULTIPLE_SELECT\fP)\&. .RE .IP "\fBXmNselectionPolicy\fP" 10 Defines the interpretation of the selection action\&. This can be one of the following: .RS .IP "\fBXmSINGLE_SELECT\fP" 10 Allows only single selections .IP "\fBXmMULTIPLE_SELECT\fP" 10 Allows multiple selections .IP "\fBXmEXTENDED_SELECT\fP" 10 Allows extended selections .IP "\fBXmBROWSE_SELECT\fP" 10 Allows drag-and-browse functionality .RE .IP "\fBXmNsingleSelectionCallback\fP" 10 Specifies a list of callbacks that is called when an item is selected in single selection mode\&. The reason is \fBXmCR_SINGLE_SELECT\fP\&. .IP "\fBXmNstringDirection\fP" 10 Is a synthetic resource for setting \fBXmNlayoutDirection\fP\&. The values for this resource are \fBXmSTRING_DIRECTION_L_TO_R\fP and \fBXmSTRING_DIRECTION_R_TO_L\fP\&. Refer to the \fBXmNlayoutDirection\fP resource description\&. The \fBXmNstringDirection\fP resource is obsoleted by \fBXmNlayoutDirection\fP, but is kept here for backward compatibility\&. .IP "\fBXmNtopItemPosition\fP" 10 Specifies the position of the item that is the first visible item in the list\&. Setting this resource is equivalent to calling the \fBXmListSetPos\fP function\&. The position of the first item in the list is 1; the position of the second item is 2; and so on\&. A position of 0 (zero) specifies the last item in the list\&. The value must not be negative\&. .IP "\fBXmNvisibleItemCount\fP" 10 Specifies the number of items that can fit in the visible space of the list work area\&. The List uses this value to determine its height\&. The value must be greater than 0 (zero)\&. .SS "Inherited Resources" .PP List inherits behavior and resources from the superclasses described in the following tables\&. For a complete description of each resource, refer to the reference page for that superclass\&. .PP .TS tab() box; c s s s s l| l| l| l| l. \fBXmPrimitive Resource Set\fP \fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP _____ XmNbottomShadowColorXmCBottomShadowColorPixeldynamicCSG _____ XmNbottomShadowPixmapXmCBottomShadowPixmapPixmapXmUNSPECIFIED_PIXMAPCSG _____ XmNconvertCallbackXmCCallbackXtCallbackListNULLC _____ XmNforegroundXmCForegroundPixeldynamicCSG _____ XmNhelpCallbackXmCCallbackXtCallbackListNULLC _____ XmNhighlightColorXmCHighlightColorPixeldynamicCSG _____ XmNhighlightOnEnterXmCHighlightOnEnterBooleanFalseCSG _____ XmNhighlightPixmapXmCHighlightPixmapPixmapdynamicCSG _____ XmNhighlightThicknessXmCHighlightThicknessDimension2CSG _____ XmNlayoutDirectionXmCLayoutDirectionXmDirectiondynamicCG _____ XmNnavigationTypeXmCNavigationTypeXmNavigationTypeXmTAB_GROUPCSG _____ XmNpopupHandlerCallbackXmCCallbackXtCallbackListNULLC _____ XmNshadowThicknessXmCShadowThicknessDimension2CSG _____ XmNtopShadowColorXmCTopShadowColorPixeldynamicCSG _____ XmNtopShadowPixmapXmCTopShadowPixmapPixmapdynamicCSG _____ XmNtraversalOnXmCTraversalOnBooleanTrueCSG _____ XmNunitTypeXmCUnitTypeunsigned chardynamicCSG _____ XmNuserDataXmCUserDataXtPointerNULLCSG _____ .TE .PP .TS tab() box; c s s s s l| l| l| l| l. \fBCore Resource Set\fP \fBName\fP\fBClass\fP\fBType\fP\fBDefault\fP\fBAccess\fP _____ XmNacceleratorsXmCAcceleratorsXtAcceleratorsdynamicCSG _____ XmNancestorSensitiveXmCSensitiveBooleandynamicG _____ XmNbackgroundXmCBackgroundPixeldynamicCSG _____ XmNbackgroundPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG _____ XmNborderColorXmCBorderColorPixelXtDefaultForegroundCSG _____ XmNborderPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG _____ XmNborderWidthXmCBorderWidthDimension0CSG _____ XmNcolormapXmCColormapColormapdynamicCG _____ XmNdepthXmCDepthintdynamicCG _____ XmNdestroyCallbackXmCCallbackXtCallbackListNULLC _____ XmNheightXmCHeightDimensiondynamicCSG _____ XmNinitialResourcesPersistentXmCInitialResourcesPersistentBooleanTrueC _____ XmNmappedWhenManagedXmCMappedWhenManagedBooleanTrueCSG _____ XmNscreenXmCScreenScreen *dynamicCG _____ XmNsensitiveXmCSensitiveBooleanTrueCSG _____ XmNtranslationsXmCTranslationsXtTranslationsdynamicCSG _____ XmNwidthXmCWidthDimensiondynamicCSG _____ XmNxXmCPositionPosition0CSG _____ XmNyXmCPositionPosition0CSG _____ .TE .SS "Callback Information" .PP List defines a new callback structure\&. The application must first look at the reason field and use only the structure members that are valid for that particular reason, because not all fields are relevant for every possible reason\&. The callback structure is defined as follows: .PP .nf typedef struct { int \fIreason\fP; XEvent *\fIevent\fP; XmString \fIitem\fP; int \fIitem_length\fP; int \fIitem_position\fP; XmString *\fIselected_items\fP; int \fIselected_item_count\fP; int *\fIselected_item_positions\fP; char \fIselection_type\fP; unsigned char \fIauto_selection_type\fP; } XmListCallbackStruct; .fi .IP "\fIreason\fP" 10 Indicates why the callback was invoked\&. .IP "\fIevent\fP" 10 Points to the \fBXEvent\fP that triggered the callback\&. It can be NULL\&. .IP "\fIitem\fP" 10 The last item selected at the time of the \fIevent\fP that caused the callback\&. \fIitem\fP points to a temporary storage space that is reused after the callback is finished\&. Therefore, if an application needs to save the item, it should copy the item into its own data space\&. .IP "\fIitem_length\fP" 10 The length in bytes of \fIitem\fP\&. This member is obsolete and exists for compatibility with earlier releases\&. .IP "\fIitem_position\fP" 10 The position (plus one) of \fIitem\fP in the List\&'s \fBXmNitems\fP array\&. An \fIitem_position\fP value of one symbolizes the first element in the list\&. .IP "\fIselected_items\fP" 10 A list of items selected at the time of the \fIevent\fP that caused the callback\&. \fIselected_items\fP points to a temporary storage space that is reused after the callback is finished\&. Therefore, if an application needs to save the selected list, it should copy the list into its own data space\&. .IP "\fIselected_item_count\fP" 10 The number of items in the \fIselected_items\fP list\&. This number must be non-negative\&. .IP "\fIselected_item_positions\fP" 10 An array of integers, one for each selected item, representing the position of each selected item in the List\&'s \fBXmNitems\fP array\&. \fIselected_item_positions\fP points to a temporary storage space that is reused after the callback is finished\&. Therefore, if an application needs to save this array, it should copy the array into its own data space\&. .IP "\fIselection_type\fP" 10 Indicates that the most recent extended selection was the initial selection (\fBXmINITIAL\fP), a modification of an existing selection (\fBXmMODIFICATION\fP), or an additional noncontiguous selection (\fBXmADDITION\fP)\&. .IP "\fBauto_selection_type\fP" 10 Indicates the type of automatic selection callback\&. The types of callbacks include the following: .RS .IP "\fBXmAUTO_BEGIN\fP" 10 Indicates the beginning of automatic selection\&. .IP "\fBXmAUTO_MOTION\fP" 10 Indicates that there is a button drag selection\&. .IP "\fBXmAUTO_CANCEL\fP" 10 Indicates that the new selection is cancelled\&. .IP "\fBXmAUTO_NO_CHANGE\fP" 10 Indicates that the currently selected item matches the initial item\&. .IP "\fBXmAUTO_CHANGE\fP" 10 Indicates that the currently selected item does not match the initial item\&. .RE .PP The following table describes the reasons for which the individual callback structure fields are valid\&. .TS tab() box; l| l. \fBReason\fP\fBValid Fields\fP __ XmCR_SINGLE_SELECTT{ \fIreason, event, item, item_length, item_position\fP T} __ XmCR_DEFAULT_ACTIONT{ \fIreason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions\fP T} __ XmCR_BROWSE_SELECTT{ \fIreason, event, item, item_length, item_position\fP T} __ XmCR_MULTIPLE_SELECTT{ \fIreason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions\fP T} __ XmCR_EXTENDED_SELECTT{ \fIreason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions, selection_type\fP T} __ .TE .PP A pointer to the following callback structure is passed to the \fBXmNdestinationCallback\fP procedures: .PP .nf typedef struct { int \fIreason\fP; XEvent *\fIevent\fP; Atom \fIselection\fP; XtEnum \fIoperation\fP; int \fIflags\fP; XtPointer \fItransfer_id\fP; XtPointer \fIdestination_data\fP; XtPointer \fIlocation_data\fP; Time \fItime\fP; } XmDestinationCallbackStruct; .fi .IP "\fIreason\fP" 10 Indicates why the callback was invoked\&. .IP "\fIevent\fP" 10 Points to the \fBXEvent\fP that triggered the callback\&. It can be NULL\&. .IP "\fIselection\fP" 10 Indicates the selection for which data transfer is being requested\&. Possible values are \fBCLIPBOARD\fP, \fBPRIMARY\fP, \fBSECONDARY\fP, and \fB_MOTIF_DROP\fP\&. .IP "\fIoperation\fP" 10 Indicates the type of transfer operation requested\&. .RS .IP " \(bu" 6 When the selection is \fBPRIMARY\fP, possible values are \fBXmMOVE\fP, \fBXmCOPY\fP, and \fBXmLINK\fP\&. .IP " \(bu" 6 When the selection is \fBSECONDARY\fP or \fBCLIPBOARD\fP, possible values are \fBXmCOPY\fP and \fBXmLINK\fP\&. .IP " \(bu" 6 When the selection is \fB_MOTIF_DROP\fP, possible values are \fBXmMOVE\fP, \fBXmCOPY\fP, \fBXmLINK\fP, and \fBXmOTHER\fP\&. A value of \fBXmOTHER\fP means that the callback procedure must get further information from the \fBXmDropProcCallbackStruct\fR in the \fIdestination_data\fP member\&. .RE .IP "\fIflags\fP" 10 Indicates whether or not the destination widget is also the source of the data to be transferred\&. Following are the possible values: .RS .IP "\fBXmCONVERTING_NONE\fP" 10 The destination widget is not the source of the data to be transferred\&. .IP "\fBXmCONVERTING_SAME\fP" 10 The destination widget is the source of the data to be transferred\&. .RE .IP "\fBtransfer_id\fP" 10 Serves as a unique ID to identify the transfer transaction\&. .IP "\fIdestination_data\fP" 10 Contains information about the destination\&. When the selection is \fB_MOTIF_DROP\fP, the callback procedures are called by the drop site\&'s \fBXmNdropProc\fP, and \fIdestination_data\fP is a pointer to the \fBXmDropProcCallbackStruct\fR passed to the \fBXmNdropProc\fP procedure\&. When the selection is \fBSECONDARY\fP, \fIdestination_data\fP is an Atom representing a target recommended by the selection owner for use in converting the selection\&. Otherwise, \fIdestination_data\fP is NULL\&. .IP "\fBlocation_data\fP" 10 Contains information about the location where data is to be transferred\&. The value is always NULL when the selection is \fBSECONDARY\fP or \fBCLIPBOARD\fP\&. If the value is NULL, the data is to be inserted at the widget\&'s cursor position\&. Otherwise, the value is an integer representing the position in the List where the items are to be transferred\&. A value of 1 makes the first new item the first item in the list; a value of 2 makes it the second item; and so on\&. Once \fBXmTransferDone\fP procedures start to be called, \fBlocation_data\fP will no longer be stable\&. .IP "\fItime\fP" 10 Indicates the time when the transfer operation began\&. .SS "Translations" .PP \fBXmList\fP includes translations from Primitive\&. The \fBXmList\fP translations are described in the following list\&. .PP The following key names are listed in the X standard key event translation table syntax\&. This format is the one used by Motif to specify the widget actions corresponding to a given key\&. A brief overview of the format is provided under \fBVirtualBindings\fP(3)\&. For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation\&. .IP "\fB\fP\fB\fP:" 10 ListButtonMotion() .IP "\fBs \(apm \(apa\fP \fB\fP:" 10 ListBeginExtend() .IP "\fBs \(apm \(apa\fP \fB\fP:" 10 ListEndExtend() .IP "\fBc \(aps \(apm \(apa\fP \fB\fP:" 10 ListBeginToggle() .IP "\fBc \(aps \(apm \(apa\fP \fB\fP:" 10 ListEndToggle() .IP "\fB\(aps \(apc \(apm \(apa\fP \fB\fP:" 10 ListBeginSelect() .IP "\fB\(aps \(apc \(apm \(apa\fP \fB\fP:" 10 ListEndSelect() .IP "\fB\fP:" 10 ListProcessDrag() .IP "\fB:s c\fP \fB\fP\fB\fP:" 10 ListBeginDataExtend() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListBeginData() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListBeginLine() .IP "\fB:s c\fP \fB\fP\fB\fP:" 10 ListEndDataExtend() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListEndData() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListEndLine() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListLeftPage() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListLeftPage() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListPrevPage() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListRightPage() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListRightPage() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListNextPage() .IP "\fBs\fP \fB\fP\fB\fP\fB:\fP" 10 ListKbdBeginExtend() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdBeginSelect() .IP "\fB:s\fP \fB\fP\fB\fP:" 10 ListKbdEndExtend() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdEndSelect() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdSelectAll() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdDeSelectAll() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdActivate() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListAddMode() .IP "\fB:\fP\fB\fP\fB\fP:" 10 PrimitiveHelp() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListKbdCancel() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListLeftPage() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListLeftChar() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListRightPage() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListRightChar() .IP "\fB:s\fP \fB\fP\fB\fP:" 10 ListExtendPrevItem() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListPrevItem() .IP "\fB:s\fP \fB\fP\fB\fP:" 10 ListExtendNextItem() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListNextItem() .IP "\fB:c\fP \fB\fP\fB\fP:" 10 ListCopyToClipboard() .IP "\fB:\fP\fB\fP\fB\fP:" 10 ListCopyToClipboard() .IP "\fB\(aps c \(apm \(apa\fP \fB\fP\fBslash\fP:" 10 ListKbdSelectAll() .IP "\fB\(aps c \(apm \(apa\fP \fB\fP\fBbackslash\fP:" 10 ListKbdDeSelectAll() .IP "\fBs \(apm \(apa\fP \fB\fP\fBTab\fP:" 10 PrimitivePrevTabGroup() .IP "\fB\(apm \(apa\fP \fB\fP\fBTab\fP:" 10 PrimitiveNextTabGroup() .IP "\fB\(aps \(apm \(apa\fP \fB\fP\fBReturn\fP:" 10 ListKbdActivate() .IP "\fB\(aps \(apm \(apa\fP \fB\fP\fBspace\fP:" 10 ListKbdBeginSelect() .IP "\fB\(aps \(apm \(apa\fP \fB\fP\fBspace\fP:" 10 ListKbdEndSelect() .IP "\fBs \(apm \(apa\fP \fB\fP\fBspace\fP:" 10 ListKbdBeginExtend() .IP "\fBs \(apm \(apa\fP \fB\fP\fBspace\fP:" 10 ListKbdEndExtend() .IP "\fB\fP:" 10 ListQuickNavigate() .PP The List button event translations are modified when Display\&'s \fBXmNenableBtn1Transfer\fP resource does not have a value of \fBXmOFF\fP (in other words, it is either \fBXmBUTTON2_TRANSFER\fP or \fBXmBUTTON2_ADJUST\fP)\&. This option allows the actions for selection and transfer to be integrated on \fB\fP, and the actions for extending the selection can be bound to \fB\fP\&. The actions for \fB\fP that are defined above still apply when the \fB\fP event occurs over text that is not selected\&. The following actions apply when the \fB\fP event occurs over text that is selected: .IP "\fB\fP\fB:\fP" 10 ListProcessBtn1(\fBListButtonMotion\fP) .IP "\fBs \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListBeginExtend\fP) .IP "\fBs \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListEndExtend\fP) .IP "\fBc \(aps \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListBeginToggle\fP) .IP "\fBc \(aps \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListEndToggle\fP) .IP "\fB\(aps \(apc \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListBeginSelect\fP) .IP "\fB\(aps \(apc \(apm \(apa\fP \fB\fP" 10 ListProcessBtn1(\fBListEndSelect\fP) .PP When Display\&'s \fBXmNenableBtn1Transfer\fP resource has a value of \fBXmBUTTON2_ADJUST\fP, the following actions apply: .IP "\fB\fP\fB:\fP" 10 ListProcessBtn2(\fBListBeginExtend\fP) .IP "\fB\fP\fB:\fP" 10 ListProcessBtn2(\fBListButtonMotion\fP) .IP "\fB\fP\fB:\fP" 10 ListProcessBtn2(\fBListEndExtend\fP) .SS "Action Routines" .PP The \fBXmList\fP action routines are described in the following list\&. The current selection is always shown with inverted colors\&. .IP "ListAddMode():" 10 Toggles the state of Add Mode for keyboard selection\&. .IP "ListBeginData():" 10 Moves the location cursor to the first item in the list\&. In Normal Mode, this also deselects any current selection, selects the first item in the list, and calls the appropriate selection callbacks (\fBXmNbrowseSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "ListBeginDataExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP or \fBXmEXTENDED_SELECT\fP, this action moves the location cursor to the first item in the list\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; changes the selection state of the first item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "ListBeginExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done, and changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP\&. .IP "ListBeginLine():" 10 Moves the horizontal scroll region to the beginning of the line\&. .IP "ListBeginSelect():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, deselects any current selection and toggles the selection state of the item under the pointer\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, deselects any current selection and selects the item under the pointer\&. If \fBXmNautomaticSelection\fP is set to True, calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, toggles the selection state of the item under the pointer\&. Any previous selections remain\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action deselects any current selection, selects the item under the pointer, and sets the current anchor at that item\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP\&. .IP "ListBeginToggle():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action moves the current anchor to the item under the pointer without changing the current selection\&. If the item is unselected, this action selects it; if the item is selected, this action unselects it\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "" 10 Otherwise, the list takes keyboard focus\&. No other action occurs\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP\&. .IP "ListButtonMotion():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, this action deselects any current selection and selects the item under the pointer\&. If \fBXmNautomaticSelection\fP is set to True and the pointer has entered a new list item, this action calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection is being made and an extended selection has previously been made from the current anchor point, restores the selection state of the items in that range to their state before the previous extended selection was done and changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point\&. If \fBXmNautomaticSelection\fP is set to True and the pointer has entered a new list item, calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "" 10 If the pointer leaves a scrolled list, this action scrolls the list in the direction of the pointer motion\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_MOTION\fP\&. .IP "ListCopyToClipboard()" 10 Copies the content of the selected items to the clipboard as a single compound string with each item separated by a newline\&. This action calls the \fBXmNconvertCallback\fP procedures, possibly multiple times, for the \fBCLIPBOARD\fP selection\&. .IP "ListEndData():" 10 Moves the location cursor to the last item in the list\&. In Normal Mode, this also deselects any current selection, selects the last item in the list, and calls the appropriate selection callbacks (\fBXmNbrowseSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "ListEndDataExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP or \fBXmEXTENDED_SELECT\fP, this action moves the location cursor to the last item in the list\&. .IP "" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; changes the selection state of the last item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "ListEndExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action moves the location cursor to the last item selected or deselected and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "" 10 If \fBXmNautomaticSelection\fP is set to True, then the \fBauto_selection_type\fP field of the callback will be valid\&. If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP and the currently selected item position matches the position of the item that was selected before the browse selection began, or if \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with \fBauto_selection_type\fP set to \fBXmAUTO_NO_CHANGE\fP\&. Otherwise, it will be set to \fBXmAUTO_CHANGE\fP\&. .IP "ListEndLine():" 10 Moves the horizontal scroll region to the end of the line\&. .IP "ListEndSelect():" 10 This action moves the location cursor to the last item selected or deselected and calls the appropriate selection callbacks (\fBXmNsingleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, \fBXmNbrowseSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, \fBXmNmultipleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "" 10 If \fBXmNautomaticSelection\fP is set to True, then the \fBauto_selection_type\fP field of the callback will be valid\&. If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP and the currently selected item position matches the position of the item that was selected before the brose selection began, or if \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with \fBauto_selection_type\fP set to \fBXmAUTO_NO_CHANGE\fP\&. Otherwise, it will be set to \fBXmAUTO_CHANGE\fP\&. .IP "ListEndToggle():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, moves the location cursor to the last item selected or deselected and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "" 10 If \fBXmNautomaticSelection\fP is set to True, then the \fBauto_selection_type\fP field of the callback will be valid\&. If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP and the currently selected item position matches the position of the item that was selected before the browse selection began, or if \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with \fBauto_selection_type\fP set to \fBXmAUTO_NO_CHANGE\fP\&. Otherwise, it will be set to \fBXmAUTO_CHANGE\fP\&. .IP "ListExtendNextItem():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; moves the location cursor to the next item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "ListExtendPrevItem():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; moves the location cursor to the previous item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point; calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "ListScrollCursorVertically(\fIpercentage\fP\fB)\fP:" 10 Scrolls the line containing the insertion cursor vertically to an intermediate position in the visible window based on an input percentage\&. A value of 0 (zero) indicates the top of the window; a value of 100, the bottom of the window\&. If this action is called with no argument, the line containing the insertion cursor is scrolled vertically to a new position designated by the \fIy\fP event passed to the routine\&. .IP "ListKbdActivate():" 10 Calls the callbacks for \fBXmNdefaultActionCallback\fP\&. If the List\&'s parent is a manager, this action passes the event to the parent\&. .IP "ListKbdBeginExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done; changes the selection state of the item at the location cursor and all items between it and the current anchor point to the state of the item at the current anchor point\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP"\&. .IP "ListKbdBeginSelect():" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, deselects any current selection and toggles the state of the item at the location cursor\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP"\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, deselects any current selection and selects the item at the location cursor\&. If \fBXmNautomaticSelection\fP is set to True, calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, toggles the selection state of the item at the location cursor\&. Any previous selections remain\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, moves the current anchor to the item at the location cursor\&. In Normal Mode, this action deselects any current selection and selects the item at the location cursor\&. In Add Mode, this action toggles the selection state of the item at the location cursor and leaves the current selection unchanged\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_BEGIN\fP"\&. .IP "ListKbdCancel():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and an extended selection is being made from the current anchor point, this action cancels the new selection and restores the selection state of the items in that range to their state before the extended selection was done\&. If \fBXmNautomaticSelection\fP is set to True, this action calls the \fBXmNextendedSelectionCallback\fP callbacks; otherwise, if the parent is a manager, it passes the event to the parent\&. The \fBauto_selection_type\fP component of the callback structure will be set to \fBXmAUTO_CANCEL\fP"\&. .IP "ListKbdDeSelectAll():" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, \fBXmMULTIPLE_SELECT\fP, or \fBXmEXTENDED_SELECT\fP in Add Mode, this action deselects all items in the list\&. If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP in Normal Mode, this action deselects all items in the list (except the item at the location cursor if the shell\&'s \fBXmNkeyboardFocusPolicy\fP is \fBXmEXPLICIT\fP)\&. This action also calls the appropriate selection callbacks (\fBXmNsingleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, \fBXmNmultipleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "ListKbdEndExtend():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action calls the \fBXmNextendedSelectionCallback\fP callbacks\&. .IP "" 10 If \fBXmNautomaticSelection\fP is set to True, then the \fBauto_selection_type\fP field of the callback will be valid\&. If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP and the currently selected item position matches the position of the item that was selected before the browse selection began, or if \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with \fBauto_selection_type\fP set to \fBXmAUTO_NO_CHANGE\fP\&. Otherwise, it will be set to \fBXmAUTO_CHANGE\fP\&. .IP "ListKbdEndSelect():" 10 Calls the appropriate selection callbacks (\fBXmNsingleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, \fBXmNbrowseSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, \fBXmNmultipleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "" 10 If \fBXmNautomaticSelection\fP is set to True, then the \fBauto_selection_type\fP field of the callback will be valid\&. If \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP and the currently selected item position matches the position of the item that was selected before the browse selection began, or if \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP and the set of currently selected item positions matches the set of item positions selected before the extended selection began, the callback will be called with \fBauto_selection_type\fP set to \fBXmAUTO_NO_CHANGE\fP\&. Otherwise, it will be set to \fBXmAUTO_CHANGE\fP\&. .IP "ListKbdSelectAll():" 10 If \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP or \fBXmBROWSE_SELECT\fP, this action selects the item at the location cursor\&. If \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP or \fBXmMULTIPLE_SELECT\fP, it selects all items in the list\&. This action also calls the appropriate selection callbacks (\fBXmNsingleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmSINGLE_SELECT\fP, \fBXmNbrowseSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, \fBXmNmultipleSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmMULTIPLE_SELECT\fP, \fBXmNextendedSelectionCallback\fP when \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP)\&. .IP "ListLeftChar():" 10 Scrolls the list one character to the left\&. .IP "ListLeftPage():" 10 Scrolls the list one page to the left\&. .IP "ListNextItem():" 10 Moves the location cursor to the next item in the list\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, this action also selects the next item, deselects any current selection, and calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the next item, deselects any current selection, moves the current anchor to the next item, and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. In Add Mode, this action does not affect the selection or the anchor\&. .IP "ListNextPage():" 10 Scrolls the list to the next page, moving the location cursor to a new item\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, this action also selects the new item, deselects any current selection, and calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. In Add Mode, this action does not affect the selection or the anchor\&. .IP "ListPrevItem():" 10 Moves the location cursor to the previous item in the list\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, this action also selects the previous item, deselects any current selection, and calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the previous item, deselects any current selection, moves the current anchor to the previous item, and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. In Add Mode, this action does not affect the selection or the anchor\&. .IP "ListPrevPage():" 10 Scrolls the list to the previous page, moving the location cursor to a new item\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmBROWSE_SELECT\fP, this action also selects the new item, deselects any current selection, and calls the \fBXmNbrowseSelectionCallback\fP callbacks\&. .IP "" 10 If the \fBXmNselectionPolicy\fP is set to \fBXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the \fBXmNextendedSelectionCallback\fP callbacks\&. In Add Mode this action does not affect the selection or the anchor\&. .IP "ListProcessBtn1(\fIstring\fP)" 10 When Display\&'s \fBXmNenableBtn1Transfer\fP resource is not \fBXmOFF\fP, the actions for selection and transfer are integrated on \fB\fP\&. When the button is not performing a transfer or drag, the action that is performed depends on the value of \fIstring\fP, which can be one of the following actions: .RS .IP " \(bu" 6 \fBListButtonMotion\fP .IP " \(bu" 6 \fBListBeginExtend\fP .IP " \(bu" 6 \fBListEndExtend\fP .IP " \(bu" 6 \fBListBeginToggle\fP .IP " \(bu" 6 \fBListEndToggle\fP .IP " \(bu" 6 \fBListBeginSelect\fP .IP " \(bu" 6 \fBListEndSelect\fP .RE .IP "\fBListProcessBtn2\fP" 10 When Display\&'s \fBXmNenableBtn1Transfer\fP resource has a value of \fBXmBUTTON2_TRANSFER\fP, the actions for extending selection are bound on \fB\fP, and a drag starts immediately\&. When Display\&'s \fBXmNenableBtn1Transfer\fP resource has a value of \fBXmBUTTON2_ADJUST\fP, the action that is performed depends on the value of \fIstring\fP, which can be one of the following actions: .RS .IP " \(bu" 6 \fBListBeginExtend\fP .IP " \(bu" 6 \fBListButtonMotion\fP .IP " \(bu" 6 \fBListEndExtend\fP .RE .IP "ListProcessDrag():" 10 Drags the content of one or more selected list items\&. Each item is separated by a newline\&. If \fBBTransfer\fP is pressed on an unselected item, it drags only that item, excluding any other selected items\&. This action sets the \fBXmNconvertProc\fP of the DragContext to a function that calls the \fBXmNconvertCallback\fP procedures, possibly multiple times, for the \fB_MOTIF_DROP\fP selection\&. .IP "\fBListQuickNavigate\fP" 10 Navigates to an item\&. When List\&'s \fBXmNmatchBehavior\fP resource is \fBXmQUICK_NAVIGATE\fP, this action uses 1-character navigation to navigate\&. Refer to the \fBXmNmatchBehavior\fP resource for a description of how this navigation works\&. .IP "ListRightChar():" 10 Scrolls the list one character to the right\&. .IP "ListRightPage():" 10 Scrolls the list one page to the right\&. .IP "PrimitiveHelp():" 10 Calls the callbacks for \fBXmNhelpCallback\fP if any exist\&. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them\&. .IP "PrimitiveNextTabGroup():" 10 Moves the focus to the first item contained within the next tab group\&. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list\&. .IP "PrimitivePrevTabGroup():" 10 Moves the focus to the first item contained within the previous tab group\&. If the beginning of the tab group list is reached, it wraps to the end of the tab group list\&. .SS "Additional Behavior" .PP The List widget has the following additional behavior: .IP "\fB\fP" 10 If a button click is followed by another button click within the time span specified by the display\&'s multiclick time, the List interprets that as a double click and calls the callbacks for \fBXmNdefaultActionCallback\fP\&. The item\&'s colors invert to indicate that it is selected\&. The \fBXmNdoubleClickInterval\fP resource can be used to specify a time span that overrides the display\&'s multi-click time\&. .IP "\fB\fP:" 10 If the focus policy is Explicit, this action sets the focus and draw the location cursor\&. .IP "\fB\fP:" 10 If the focus policy is Explicit, this action removes the focus and erase the location cursor\&. .SS "Virtual Bindings" .PP The bindings for virtual keys are vendor specific\&. For information about bindings for virtual buttons and keys, see \fBVirtualBindings\fP(3)\&. .SH "RELATED" .PP \fBCore\fP(3), \fBXmCreateList\fP(3), \fBXmCreateScrolledList\fP(3), \fBXmFontListCreate\fP(3), \fBXmFontListAppendEntry\fP(3), \fBXmListAddItem\fP(3), \fBXmListAddItems\fP(3), \fBXmListAddItemUnselected\fP(3), \fBXmListAddItemsUnselected\fP(3), \fBXmListDeleteAllItems\fP(3), \fBXmListDeleteItem\fP(3), \fBXmListDeleteItems\fP(3), \fBXmListDeleteItemsPos\fP(3), \fBXmListDeletePos\fP(3), \fBXmListDeletePositions\fP(3), \fBXmListDeselectAllItems\fP(3), \fBXmListDeselectItem\fP(3), \fBXmListDeselectPos\fP(3), \fBXmListGetKbdItemPos\fP \fBXmListGetMatchPos\fP(3), \fBXmListGetSelectedPos\fP(3), \fBXmListItemExists\fP(3), \fBXmListItemPos\fP(3), \fBXmListPosToBounds\fP(3), \fBXmListReplaceItems\fP(3), \fBXmListReplaceItemsPos\fP(3), \fBXmListReplaceItemsPos\fP(3), \fBXmListReplaceItemsPosUnselected\fP(3), \fBXmListReplaceItemsUnselected\fP(3), \fBXmListSelectItem\fP(3), \fBXmListSelectPos\fP(3), \fBXmListSetAddMode\fP(3), \fBXmListSetBottomItem\fP(3), \fBXmListSetBottomPos\fP(3), \fBXmListSetHorizPos\fP(3), \fBXmListSetItem\fP(3), \fBXmListSetKbdItemPos\fP(3), \fBXmListSetPos\fP(3), \fBXmListUpdateSelectedList\fP(3), \fBXmListYToPos\fP(3), \fBXmPrimitive\fP(3) \fBXmStringCreate\fP(3), \fBXmVaCreateList\fP(3), and \fBXmVaCreateManagedList\fP(3)\&.