manpagez: man pages & more
man XmList(3)
Home | html | info | man
XmList(library call)                                      XmList(library call)




NAME

       XmList -- The List widget class


SYNOPSIS

       #include <Xm/List.h>


DESCRIPTION

       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.

       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 XmCreateScrolledList convenience function.

       To select items, move the pointer or cursor to  the  desired  item  and
       press  the <Btn1> mouse button or the key defined as <osfSelect>. There
       are several styles of selection behavior, and they  all  highlight  the
       selected  item or items by displaying them in inverse colors. An appro-
       priate 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.

       List  uses the XmQTspecifyRenderTable, XmQTscrollFrame, and XmQTnaviga-
       tor traits, and holds the XmQTtransfer trait.

   Selection
       Each list has one of four selection models:

          o  Single Select

          o  Browse Select

          o  Multiple Select

          o  Extended Select

       In Single Select and Browse Select, at most one item is selected  at  a
       time.   In Single Select, pressing <Btn1> on an item toggles its selec-
       tion state and deselects any other selected item.   In  Browse  Select,
       pressing  <Btn1> on an item selects it and deselects any other selected
       item; dragging <Btn1> moves the selection  as  the  pointer  is  moved.
       Releasing <Btn1> on an item moves the location cursor to that item.

       In  Multiple  Select,  any  number  of items can be selected at a time.
       Pressing <Btn1> on an item toggles its selection  state  but  does  not
       deselect any other selected items.

       In  Extended Select, any number of items can be selected at a time, and
       the user can easily select ranges of items.  Pressing <Btn1> on an item
       selects  it  and deselects any other selected item.  Dragging <Btn1> or
       pressing or dragging <Shift><Btn1> following a  <Btn1>  action  selects
       all  items  between  the  item  under the pointer and the item on which
       <Btn1> was pressed.  This action  also  deselects  any  other  selected
       items outside that range.

       Extended Select also allows the user to select and deselect discontigu-
       ous ranges of items.  Pressing <Ctrl><Btn1>  on  an  item  toggles  its
       selection  state but does not deselect any other selected items.  Drag-
       ging <Ctrl><Btn1> or pressing or  dragging  <Shift><Btn1>  following  a
       <Ctrl><Btn1>  action  sets the selection state of all items between the
       item under the pointer and the item on which <Ctrl><Btn1>  was  pressed
       to  the  state  of  the  item  on which <Ctrl><Btn1> was pressed.  This
       action does not deselect any other selected items outside that range.

       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  <osfSelect>
       select  the item at the location cursor and deselect any other selected
       items.  In Add Mode, navigation operations have no effect on selection,
       and <osfSelect> toggles the selection state of the item at the location
       cursor without deselecting any other selected items, except  in  Single
       Select.

       Single  and Multiple Select use Add Mode, and Browse Select uses Normal
       Mode.

       Extended Select can use either mode; the user changes modes by pressing
       <osfAddMode>.  In Extended Select Normal Mode, pressing <osfSelect> has
       the same effect as pressing <Btn1>; <osfExtend> and shifted  navigation
       have  the  same  effect  as  pressing  <Shift><Btn1> following a <Btn1>
       action.  In Extended Select Add Mode, pressing <osfSelect> has the same
       effect  as  pressing  <Ctrl><Btn1>;  <osfExtend> and shifted navigation
       have the same effect as pressing <Shift><Btn1> following a <Ctrl><Btn1>
       action.

       Normal  Mode  is  indicated by a solid location cursor, and Add Mode is
       indicated by a dashed location cursor.

   Data Transfer Behavior
       List supports dragging of items from the List and transfer of items  to
       the clipboard.  When the user presses BTransfer on a selected item, the
       widget transfers all selected items.  When the user  presses  BTransfer
       on  an unselected item, the widget transfers only that item.  Depending
       on the value of XmNprimaryOwnership,  List  can  also  support  primary
       selection.

       When  the  XmNconvertCallback  procedures are called, the location_data
       member of the XmConvertCallbackStruct 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.

       As a source of data, List supports the following targets and associated
       conversions of data to these targets:

       locale    If  the locale 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.

       COMPOUND_TEXT
                 The widget transfers the selected list  items  as  type  COM-
                 POUND_TEXT.  Each item transferred except the last includes a
                 trailing separator.

       UTF8_STRING
                 The  widget  transfers  the  selected  list  items  as   type
                 UTF8_STRING.   Each item transferred except the last includes
                 a trailing separator.

       STRING    The widget transfers the selected list items as type  STRING.
                 Each  item  transferred  except  the last includes a trailing
                 separator.

       TEXT      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  COM-
                 POUND_TEXT.  Each item transferred except the last includes a
                 trailing separator.

       _MOTIF_CLIPBOARD_TARGETS
                 The  widget transfers, as type ATOM, a list of the targets it
                 supports for immediate transfer for the CLIPBOARD  selection.
                 These  include  _MOTIF_COMPOUND_STRING.  If the selected list
                 items are fully convertible to  STRING,  these  also  include
                 STRING;   otherwise,  they  also  include  COMPOUND_TEXT  and
                 UTF8_STRING.

       _MOTIF_COMPOUND_STRING
                 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.

       _MOTIF_DEFERRED_CLIPBOARD_TARGETS
                 The widget transfers, as type ATOM, a list of the targets  it
                 supports  for  delayed  transfer for the CLIPBOARD selection.
                 This   widget   currently    supplies    no    targets    for
                 _MOTIF_DEFERRED_CLIPBOARD_TARGETS.

       _MOTIF_EXPORT_TARGETS
                 The  widget transfers, as type ATOM, a list of the targets to
                 be used as the value of the DragContext's XmNexportTargets in
                 a   drag-and-drop   transfer.    These   include  _MOTIF_COM-
                 POUND_STRING, COMPOUND_TEXT, UTF8_STRING, the encoding of the
                 locale, STRING, TEXT, BACKGROUND, and FOREGROUND.

       _MOTIF_LOSE_SELECTION
                 When  the  widget  loses the selection, it deselects all list
                 items.

       As a source of data, List also supports the  following  standard  Motif
       targets:

       BACKGROUND
                 The widget transfers XmNbackground as type PIXEL.

       CLASS     The widget finds the first shell in the widget hierarchy that
                 has a WM_CLASS property and transfers the contents as text in
                 the current locale.

       CLIENT_WINDOW
                 The  widget finds the first shell in the widget hierarchy and
                 transfers its window as type WINDOW.

       COLORMAP  The widget transfers XmNcolormap as type COLORMAP.

       FOREGROUND
                 The widget transfers XmNforeground as type PIXEL.

       NAME      The widget finds the first shell in the widget hierarchy that
                 has  a WM_NAME property and transfers the contents as text in
                 the current locale.

       TARGETS   The widget transfers, as type ATOM, a list of the targets  it
                 supports.   These  include the standard targets in this list.
                 These  also  include  _MOTIF_COMPOUND_STRING,  COMPOUND_TEXT,
                 UTF8_STRING the encoding of the locale, STRING, and TEXT.

       TIMESTAMP The widget transfers the timestamp used to acquire the selec-
                 tion as type INTEGER.

       _MOTIF_RENDER_TABLE
                 The widget transfers XmNrenderTable if it exists, or else the
                 default text render table, as type STRING.

       _MOTIF_ENCODING_REGISTRY
                 The  widget  transfers  its encoding registry as type STRING.
                 The value is a list of NULL separated items in  the  form  of
                 tag encoding pairs.  This target symbolizes the transfer tar-
                 get 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  XmRegisterSegmentEncoding  and
                 XmMapSegmentEncoding.

       List has no widget class destination  procedure.   Subclasses  and  the
       XmNdestinationCallback  procedures  are responsible for any data trans-
       fers to the widget.

   Classes
       List inherits behavior, resources, and traits from  Core  and  XmPrimi-
       tive.

       The class pointer is xmListWidgetClass.

       The class name is XmList.

   New Resources
       The  following table defines a set of widget resources used by the pro-
       grammer to specify data. The programmer can also set the resource  val-
       ues  for  the  inherited  classes to set attributes for this widget. To
       reference a resource by name or by class in a .Xdefaults  file,  remove
       the  XmN or XmC prefix and use the remaining letters. To specify one of
       the defined values for a resource in a .Xdefaults file, remove  the  Xm
       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 XtSetValues (S), retrieved by using XtGetValues (G), or is
       not applicable (N/A).


       +-----------------------------------------------------------------------------------------------------------------+
       |                             |                XmList Resource Set            |                          |        |
       |Name                         | Class                     | Type              | Default                  | Access |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNautomaticSelection        | XmCAutomaticSelection     | XtEnum            | False                    | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNbrowseSelectionCallback   | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNdefaultActionCallback     | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNdestinationCallback       | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNdoubleClickInterval       | XmCDoubleClickInterval    | int               | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNextendedSelectionCallback | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNfontList                  | XmCFontList               | XmFontList        | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNitemCount                 | XmCItemCount              | int               | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNitems                     | XmCItems                  | XmStringTable     | NULL                     | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNlistMarginHeight          | XmCListMarginHeight       | Dimension         | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNlistMarginWidth           | XmCListMarginWidth        | Dimension         | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNlistSizePolicy            | XmCListSizePolicy         | unsigned char     | XmVARIABLE               | CG     |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNlistSpacing               | XmCListSpacing            | Dimension         | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNmatchBehavior             | XmCMatchBehavior          | unsigned char     | XmQUICK_NAVIGATE         | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNmultipleSelectionCallback | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNprimaryOwnership          | XmCPrimaryOwnership       | unsigned char     | XmOWN_NEVER              | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNrenderTable               | XmCRenderTable            | XmRenderTable     | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNscrollBarDisplayPolicy    | XmCScrollBarDisplayPolicy | unsigned char     | XmAS_NEEDED              | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectColor               | XmCSelectColor            | XmRSelectColor    | XmREVERSED_GROUND_COLORS | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectedItemCount         | XmCSelectedItemCount      | int               | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectedItems             | XmCSelectedItems          | XmStringTable     | NULL                     | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectedPositionCount     | XmCSelectedPositionCount  | int               | 0                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectedPositions         | XmCSelectedPositions      | unsigned int *    | NULL                     | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectionMode             | XmCSelectionMode          | unsigned char     | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNselectionPolicy           | XmCSelectionPolicy        | unsigned char     | XmBROWSE_SELECT          | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNsingleSelectionCallback   | XmCCallback               | XtCallbackList    | NULL                     | C      |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNstringDirection           | XmCStringDirection        | XmStringDirection | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNtopItemPosition           | XmCTopItemPosition        | int               | 1                        | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       |XmNvisibleItemCount          | XmCVisibleItemCount       | int               | dynamic                  | CSG    |
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       +-----------------------------+---------------------------+-------------------+--------------------------+--------+
       XmNautomaticSelection
                 Invokes  either  XmNbrowseSelectionCallback or XmNextendedSe-
                 lectionCallback when <Btn1> is pressed and the items that are
                 shown as selected change if the value is True (or XmAUTO) and
                 the  selection  mode  is  either  XmBROWSE_SELECT  or   XmEX-
                 TENDED_SELECT  respectively.  If False (XmNO_AUTO_SELECT), no
                 selection callbacks are invoked until the user  releases  the
                 mouse button.  See Behavior for further details on the inter-
                 action of this resource with the selection modes.

       XmNbrowseSelectionCallback
                 Specifies a list of callbacks that is called when an item  is
                 selected   in  the  browse  selection  mode.  The  reason  is
                 XmCR_BROWSE_SELECT.

       XmNdefaultActionCallback
                 Specifies a list of callbacks that is called when an item  is
                 double  clicked  or  <osfActivate> is pressed.  The reason is
                 XmCR_DEFAULT_ACTION.

       XmNdestinationCallback
                 Specifies a list of callbacks called when  the  List  is  the
                 destination  of a transfer operation.  The type of the struc-
                 ture whose address is passed to these callbacks is XmDestina-
                 tionCallbackStruct.  The reason is XmCR_OK.

       XmNdoubleClickInterval
                 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.

       XmNextendedSelectionCallback
                 Specifies a list of callbacks that is called when  items  are
                 selected  using  the  extended selection mode.  The reason is
                 XmCR_EXTENDED_SELECT.

       XmNfontList
                 Specifies the font list associated with the list items.  XmN-
                 fontList  is  obsolete and exists only for compatibility with
                 previous releases. You should now use XmNrenderTable  instead
                 of  XmNfontList. If both are specified, the render table will
                 take precedence. The font list is used  in  conjunction  with
                 the  XmNvisibleItemCount  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  XmQTspecifyRenderTable  trait.   If  such  an
                 ancestor  is  found,  the  font  list  is  initialized to the
                 XmTEXT_RENDER_TABLE value of the ancestor widget. If no  such
                 widget  is  found,  the  default is implementation dependent.
                 Refer to XmFontList(3) for more information on  a  font  list
                 structure.

       XmNitemCount
                 Specifies  the  total number of items.  The value must be the
                 number of items in XmNitems and must not be negative.  It  is
                 automatically  updated  by the list whenever an item is added
                 to or deleted from the list.

       XmNitems  Points to an array of compound strings that are  to  be  dis-
                 played  as  the  list  items.   Refer to XmString(3) for more
                 information  on  the  creation  and  structure  of   compound
                 strings.   XtGetValues  for  this  resource  returns the list
                 items themselves, not a copy of the list items.  The applica-
                 tion must not free the returned items.

       XmNlistMarginHeight
                 Specifies  the  height  of the margin between the list border
                 and the items.

       XmNlistMarginWidth
                 Specifies the width of the margin between the list border and
                 the items.

       XmNlistSizePolicy
                 Controls the reaction of the List when an item grows horizon-
                 tally beyond the current size of the list work area.  If  the
                 value is XmCONSTANT, 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 XmVARIABLE, the
                 List grows to match the size of the longest item, and no hor-
                 izontal ScrollBar appears.

                 When  the value of this resource is XmRESIZE_IF_POSSIBLE, 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.

                 The size policy must be set at the time the  List  widget  is
                 created.  It cannot be changed at a later time through XtSet-
                 Values.

       XmNlistSpacing
                 Specifies the  spacing  between  list  items.   This  spacing
                 increases  by the value of the XmNhighlightThickness resource
                 in Primitive.

       XmNmatchBehavior
                 Specifies the matching behavior followed by XmList.  The cur-
                 rent values are XmNONE and XmQUICK_NAVIGATE, as follows:

                 XmNONE    Specifies that the typed in characters are ignored.

                 XmQUICK_NAVIGATE
                           Specifies that 1-character navigation shall be sup-
                           ported  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 cur-
                           rent 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.  Sub-
                           sequently,  typing  the  same character will cycli-
                           cally navigate among the items with the same  first
                           character.

       XmNmultipleSelectionCallback
                 Specifies  a list of callbacks that is called when an item is
                 selected in multiple selection mode. The reason is  XmCR_MUL-
                 TIPLE_SELECT.

       XmNprimaryOwnership
                 Specifies  whether XmContainer takes ownership of the Primary
                 selection when a selection is made inside it.  This  resource
                 can take the following values:

                 XmOWN_NEVER
                           Never takes ownership.

                 XmOWN_ALWAYS
                           Always takes ownership.

                 XmOWN_MULTIPLE
                           Only  takes  ownership is more than one element has
                           been selected.

                 XmOWN_POSSIBLE_MULTIPLE
                           Only takes ownership if more than one  element  can
                           be selected at a time.

       XmNrenderTable
                 Specifies  the  render  table associated with the list items.
                 The render table is used in  conjunction  with  the  XmNvisi-
                 bleItemCount  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
                 XmQTspecifyRenderTable trait.  If such an ancestor is  found,
                 the  render  table  is initialized to the XmTEXT_RENDER_TABLE
                 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 XmRenderTable(3) for more information on
                 the creation and structure of a render table.

       XmNscrollBarDisplayPolicy
                 Controls the display of vertical ScrollBars in a  List  whose
                 parent  is a ScrolledWindow.  When the value of this resource
                 is XmAS_NEEDED, a vertical ScrollBar is displayed  only  when
                 the number of items in the List exceeds the number of visible
                 items.  When the value is XmSTATIC, a vertical  ScrollBar  is
                 always displayed.

       XmNselectColor
                 Allows the application to specify the color of the background
                 rectangle that indicates selected text. It takes two values:

                 XmDEFAULT_SELECT_COLOR
                           Causes the select  color  to  be  set  to  a  color
                           between the background and the bottom shadow color.

                 XmREVERSED_GROUND_COLORS
                           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.

                 HIGHLIGHT_COLOR
                           Forces the fill color to use the highlight color.

       XmNselectedItemCount
                 Specifies the number of strings in the selected  items  list.
                 The value must be the number of items in XmNselectedItems and
                 must not be negative.

       XmNselectedItems
                 Points to an array of compound strings  that  represents  the
                 list items that are currently selected, either by the user or
                 by the application.  XtGetValues 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.

                 Setting  XmNselectedItems  selects  those  list  items   that
                 exactly match items in the given XmNselectedItems list. There
                 may be additional items in XmNselectedItems that do not match
                 items  in the list. These items remain until XmNselectedItems
                 is updated.  If XmNitems is changed such that  the  list  now
                 contains  items matching previously unmatched items in XmNse-
                 lectedItems, those new items will also appear selected.

                 Any user interaction with the list that causes at  least  one
                 item  to  be  selected  or deselected and any call to XmList-
                 DeleteAllItems, XmListDeleteItem, XmListDeleteItems,  XmList-
                 DeleteItemsPos,    XmListDeletePos,    XmListDeletePositions,
                 XmListDeselectAllItems,  XmListDeselectItem,  XmListDeselect-
                 Pos,  XmListSelectItem,  XmListSelectPos,  or XmListUpdateSe-
                 lectedList cause XmNselectedItems to be  updated  immediately
                 to  exactly  reflect  the visual state of the list.  Calls to
                 any other XmList functions do not affect XmNselectedItems.

       XmNselectedPositionCount
                 Specifies the number of positions in the  selected  positions
                 list.   The value must be the number of items in XmNselected-
                 Positions

       XmNselectedPositions
                 Points to an array of the positions of the selected items  in
                 the  List.   XtGetValues  for  this resource returns the list
                 items themselves, not a copy of the list items. The  applica-
                 tion must not free the returned items or the array.

       XmNselectionMode
                 Defines  what  effect keyboard navigations have on selection.
                 The valid modes are:

                 XmADD_MODE
                           Allows no navigation operations to have  effect  on
                           selection,  and  <osfSelect>  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 XmNselectionPolicy resource is
                           an incompatible mode (XmNselectionPolicy cannot  be
                           XmBROWSE_SELECT).

                 XmNORMAL_MODE
                           Allows  navigation  operations  and  <osfSelect> to
                           select the item at the location cursor and deselect
                           any  other selected items. However, the widget can-
                           not be put into normal mode if the XmNselectionPol-
                           icy resource is an incompatible mode (XmNselection-
                           Policy  cannot  be  XmSINGLE_SELECT   or   XmMULTI-
                           PLE_SELECT).

       XmNselectionPolicy
                 Defines  the interpretation of the selection action. This can
                 be one of the following:

                 XmSINGLE_SELECT
                           Allows only single selections

                 XmMULTIPLE_SELECT
                           Allows multiple selections

                 XmEXTENDED_SELECT
                           Allows extended selections

                 XmBROWSE_SELECT
                           Allows drag-and-browse functionality

       XmNsingleSelectionCallback
                 Specifies a list of callbacks that is called when an item  is
                 selected  in  single  selection mode. The reason is XmCR_SIN-
                 GLE_SELECT.

       XmNstringDirection
                 Is a synthetic resource for setting XmNlayoutDirection.   The
                 values  for  this  resource are XmSTRING_DIRECTION_L_TO_R and
                 XmSTRING_DIRECTION_R_TO_L. Refer  to  the  XmNlayoutDirection
                 resource  description.  The  XmNstringDirection  resource  is
                 obsoleted by XmNlayoutDirection, but is kept here  for  back-
                 ward compatibility.

       XmNtopItemPosition
                 Specifies  the position of the item that is the first visible
                 item in the list.  Setting this  resource  is  equivalent  to
                 calling the XmListSetPos 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.

       XmNvisibleItemCount
                 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).

   Inherited Resources
       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.


       +---------------------------------------------------------------------------------------------------+
       |                        |            XmPrimitive|Resource Set      |                      |        |
       |Name                    | Class                 | Type             | Default              | Access |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNbottomShadowColor    | XmCBottomShadowColor  | Pixel            | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNbottomShadowPixmap   | XmCBottomShadowPixmap | Pixmap           | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNconvertCallback      | XmCCallback           | XtCallbackList   | NULL                 | C      |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNforeground           | XmCForeground         | Pixel            | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNhelpCallback         | XmCCallback           | XtCallbackList   | NULL                 | C      |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightColor       | XmCHighlightColor     | Pixel            | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightOnEnter     | XmCHighlightOnEnter   | Boolean          | False                | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightPixmap      | XmCHighlightPixmap    | Pixmap           | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightThickness   | XmCHighlightThickness | Dimension        | 2                    | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNlayoutDirection      | XmCLayoutDirection    | XmDirection      | dynamic              | CG     |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNnavigationType       | XmCNavigationType     | XmNavigationType | XmTAB_GROUP          | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNpopupHandlerCallback | XmCCallback           | XtCallbackList   | NULL                 | C      |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNshadowThickness      | XmCShadowThickness    | Dimension        | 2                    | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNtopShadowColor       | XmCTopShadowColor     | Pixel            | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNtopShadowPixmap      | XmCTopShadowPixmap    | Pixmap           | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNtraversalOn          | XmCTraversalOn        | Boolean          | True                 | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNunitType             | XmCUnitType           | unsigned char    | dynamic              | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       |XmNuserData             | XmCUserData           | XtPointer        | NULL                 | CSG    |
       +------------------------+-----------------------+------------------+----------------------+--------+
       +------------------------+-----------------------+------------------+----------------------+--------+

       +---------------------------------------------------------------------------------------------------------------+
       |                              |               Core Resource Set                |                      |        |
       |Name                          | Class                         | Type           | Default              | Access |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNaccelerators               | XmCAccelerators               | XtAccelerators | dynamic              | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNancestorSensitive          | XmCSensitive                  | Boolean        | dynamic              | G      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackground                 | XmCBackground                 | Pixel          | dynamic              | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackgroundPixmap           | XmCPixmap                     | Pixmap         | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderColor                | XmCBorderColor                | Pixel          | XtDefaultForeground  | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderPixmap               | XmCPixmap                     | Pixmap         | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderWidth                | XmCBorderWidth                | Dimension      | 0                    | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNcolormap                   | XmCColormap                   | Colormap       | dynamic              | CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdepth                      | XmCDepth                      | int            | dynamic              | CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdestroyCallback            | XmCCallback                   | XtCallbackList | NULL                 | C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNheight                     | XmCHeight                     | Dimension      | dynamic              | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNinitialResourcesPersistent | XmCInitialResourcesPersistent | Boolean        | True                 | C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNmappedWhenManaged          | XmCMappedWhenManaged          | Boolean        | True                 | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNscreen                     | XmCScreen                     | Screen *       | dynamic              | CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNsensitive                  | XmCSensitive                  | Boolean        | True                 | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNtranslations               | XmCTranslations               | XtTranslations | dynamic              | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNwidth                      | XmCWidth                      | Dimension      | dynamic              | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNx                          | XmCPosition                   | Position       | 0                    | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNy                          | XmCPosition                   | Position       | 0                    | CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       +------------------------------+-------------------------------+----------------+----------------------+--------+
   Callback Information
       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:

       typedef struct
       {
               int reason;
               XEvent *event;
               XmString item;
               int item_length;
               int item_position;
               XmString *selected_items;
               int selected_item_count;
               int *selected_item_positions;
               char selection_type;
               unsigned char auto_selection_type;
       } XmListCallbackStruct;

       reason    Indicates why the callback was invoked.

       event     Points to the XEvent that triggered the callback. It  can  be
                 NULL.

       item      The  last  item selected at the time of the event that caused
                 the callback.  item 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.

       item_length
                 The  length  in  bytes  of item.  This member is obsolete and
                 exists for compatibility with earlier releases.

       item_position
                 The position (plus one) of item in the List's XmNitems array.
                 An item_position value of one symbolizes the first element in
                 the list.

       selected_items
                 A list of items selected at the time of the event that caused
                 the  callback.   selected_items points to a temporary storage
                 space that is reused after the callback is finished.   There-
                 fore,  if  an application needs to save the selected list, it
                 should copy the list into its own data space.

       selected_item_count
                 The number of items in the selected_items list.  This  number
                 must be non-negative.

       selected_item_positions
                 An  array of integers, one for each selected item, represent-
                 ing the position of each selected item in the List's XmNitems
                 array.  selected_item_positions points to a temporary storage
                 space that is reused after the callback is finished.   There-
                 fore,  if  an application needs to save this array, it should
                 copy the array into its own data space.

       selection_type
                 Indicates that the most recent  extended  selection  was  the
                 initial  selection (XmINITIAL), a modification of an existing
                 selection (XmMODIFICATION), or  an  additional  noncontiguous
                 selection (XmADDITION).

       auto_selection_type
                 Indicates the type of automatic selection callback. The types
                 of callbacks include the following:

                 XmAUTO_BEGIN
                           Indicates the beginning of automatic selection.

                 XmAUTO_MOTION
                           Indicates that there is a button drag selection.

                 XmAUTO_CANCEL
                           Indicates that the new selection is cancelled.

                 XmAUTO_NO_CHANGE
                           Indicates that the currently selected item  matches
                           the initial item.

                 XmAUTO_CHANGE
                           Indicates that the currently selected item does not
                           match the initial item.

       The following table describes the  reasons  for  which  the  individual
       callback structure fields are valid.

       +---------------------+----------------------------+
       |Reason               | Valid Fields               |
       +---------------------+----------------------------+
       |XmCR_SINGLE_SELECT   | reason,    event,    item, |
       |                     | item_length, item_position |
       +---------------------+----------------------------+
       |XmCR_DEFAULT_ACTION  | reason,    event,    item, |
       |                     | item_length,    item_posi- |
       |                     | tion,      selected_items, |
       |                     | selected_item_count,       |
       |                     | selected_item_positions    |
       +---------------------+----------------------------+
       |XmCR_BROWSE_SELECT   | reason,    event,    item, |
       |                     | item_length, item_position |
       +---------------------+----------------------------+
       |XmCR_MULTIPLE_SELECT | reason,    event,    item, |
       |                     | item_length,    item_posi- |
       |                     | tion,      selected_items, |
       |                     | selected_item_count,       |
       |                     | selected_item_positions    |
       +---------------------+----------------------------+
       |XmCR_EXTENDED_SELECT | reason,    event,    item, |
       |                     | item_length,    item_posi- |
       |                     | tion,      selected_items, |
       |                     | selected_item_count,       |
       |                     | selected_item_positions,   |
       |                     | selection_type             |
       +---------------------+----------------------------+
       +---------------------+----------------------------+
       A pointer to the following callback structure is passed to the  XmNdes-
       tinationCallback procedures:

       typedef struct
       {
               int reason;
               XEvent *event;
               Atom selection;
               XtEnum operation;
               int flags;
               XtPointer transfer_id;
               XtPointer destination_data;
               XtPointer location_data;
               Time time;
       } XmDestinationCallbackStruct;

       reason    Indicates why the callback was invoked.

       event     Points  to the XEvent that triggered the callback.  It can be
                 NULL.

       selection Indicates the selection for  which  data  transfer  is  being
                 requested.   Possible  values  are  CLIPBOARD,  PRIMARY, SEC-
                 ONDARY, and _MOTIF_DROP.

       operation Indicates the type of transfer operation requested.

                    o  When the selection  is  PRIMARY,  possible  values  are
                       XmMOVE, XmCOPY, and XmLINK.

                    o  When  the selection is SECONDARY or CLIPBOARD, possible
                       values are XmCOPY and XmLINK.

                    o  When the selection is _MOTIF_DROP, possible values  are
                       XmMOVE,  XmCOPY,  XmLINK,  and  XmOTHER.   A  value  of
                       XmOTHER means that the callback procedure must get fur-
                       ther  information  from the XmDropProcCallbackStruct in
                       the destination_data member.

       flags     Indicates whether or not the destination widget is  also  the
                 source of the data to be transferred.  Following are the pos-
                 sible values:

                 XmCONVERTING_NONE
                           The destination widget is not  the  source  of  the
                           data to be transferred.

                 XmCONVERTING_SAME
                           The destination widget is the source of the data to
                           be transferred.

       transfer_id
                 Serves as a unique ID to identify the transfer transaction.

       destination_data
                 Contains information about the destination.  When the  selec-
                 tion  is  _MOTIF_DROP,  the callback procedures are called by
                 the  drop  site's  XmNdropProc,  and  destination_data  is  a
                 pointer  to  the  XmDropProcCallbackStruct passed to the XmN-
                 dropProc procedure.  When the selection is SECONDARY,  desti-
                 nation_data  is an Atom representing a target recommmended by
                 the selection owner for  use  in  converting  the  selection.
                 Otherwise, destination_data is NULL.

       location_data
                 Contains  information  about the location where data is to be
                 transferred.  The value is always NULL when the selection  is
                 SECONDARY or CLIPBOARD.  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  XmTransferDone
                 procedures  start  to be called, location_data will no longer
                 be stable.

       time      Indicates the time when the transfer operation began.

   Translations
       XmList includes translations from Primitive.  The  XmList  translations
       are described in the following list.

       The following key names are listed in the X standard key event transla-
       tion 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 VirtualBindings(3).  For a  complete  descrip-
       tion  of the format, please refer to the X Toolkit Instrinsics Documen-
       tation.

       <Btn1><Motion>:
                 ListButtonMotion()

       s ~m ~a <Btn1Down>:
                 ListBeginExtend()

       s ~m ~a <Btn1Up>:
                 ListEndExtend()

       c ~s ~m ~a <Btn1Down>:
                 ListBeginToggle()

       c ~s ~m ~a <Btn1Up>:
                 ListEndToggle()

       ~s ~c ~m ~a <Btn1Down>:
                 ListBeginSelect()

       ~s ~c ~m ~a <Btn1Up>:
                 ListEndSelect()

       <Btn2Down>:
                 ListProcessDrag()

       :s c <Key><osfBeginLine>:
                 ListBeginDataExtend()

       :c <Key><osfBeginLine>:
                 ListBeginData()

       :<Key><osfBeginLine>:
                 ListBeginLine()

       :s c <Key><osfEndLine>:
                 ListEndDataExtend()

       :c <Key><osfEndLine>:
                 ListEndData()

       :<Key><osfEndLine>:
                 ListEndLine()

       :<Key><osfPageLeft>:
                 ListLeftPage()

       :c <Key><osfPageUp>:
                 ListLeftPage()

       :<Key><osfPageUp>:
                 ListPrevPage()

       :<Key><osfPageRight>:
                 ListRightPage()

       :c <Key><osfPageDown>:
                 ListRightPage()

       :<Key><osfPageDown>:
                 ListNextPage()

       s <KeyDown><osfSelect>:
                 ListKbdBeginExtend()

       :<KeyDown><osfSelect>:
                 ListKbdBeginSelect()

       :s <KeyUp><osfSelect>:
                 ListKbdEndExtend()

       :<KeyUp><osfSelect>:
                 ListKbdEndSelect()

       :<Key><osfSelectAll>:
                 ListKbdSelectAll()

       :<Key><osfDeselectAll>:
                 ListKbdDeSelectAll()

       :<Key><osfActivate>:
                 ListKbdActivate()

       :<Key><osfAddMode>:
                 ListAddMode()

       :<Key><osfHelp>:
                 PrimitiveHelp()

       :<Key><osfCancel>:
                 ListKbdCancel()

       :c <Key><osfLeft>:
                 ListLeftPage()

       :<Key><osfLeft>:
                 ListLeftChar()

       :c <Key><osfRight>:
                 ListRightPage()

       :<Key><osfRight>:
                 ListRightChar()

       :s <Key><osfUp>:
                 ListExtendPrevItem()

       :<Key><osfUp>:
                 ListPrevItem()

       :s <Key><osfDown>:
                 ListExtendNextItem()

       :<Key><osfDown>:
                 ListNextItem()

       :c <Key><osfInsert>:
                 ListCopyToClipboard()

       :<Key><osfCopy>:
                 ListCopyToClipboard()

       ~s c ~m ~a <Key>slash:
                 ListKbdSelectAll()

       ~s c ~m ~a <Key>backslash:
                 ListKbdDeSelectAll()

       s ~m ~a <Key>Tab:
                 PrimitivePrevTabGroup()

       ~m ~a <Key>Tab:
                 PrimitiveNextTabGroup()

       ~s ~m ~a <Key>Return:
                 ListKbdActivate()

       ~s ~m ~a <KeyDown>space:
                 ListKbdBeginSelect()

       ~s ~m ~a <KeyUp>space:
                 ListKbdEndSelect()

       s ~m ~a <KeyDown>space:
                 ListKbdBeginExtend()

       s ~m ~a <KeyUp>space:
                 ListKbdEndExtend()

       <Key>:    ListQuickNavigate()

       The List button event translations are modified when  Display's  XmNen-
       ableBtn1Transfer  resource  does  not  have  a value of XmOFF (in other
       words, it  is  either  XmBUTTON2_TRANSFER  or  XmBUTTON2_ADJUST).  This
       option  allows  the actions for selection and transfer to be integrated
       on <Btn1>, and the actions for extending the selection can be bound  to
       <Btn2>.  The actions for <Btn1> that are defined above still apply when
       the <Btn1> event occurs over text that is not selected.  The  following
       actions apply when the <Btn1> event occurs over text that is selected:

       <Btn1Motion>:
                 ListProcessBtn1(ListButtonMotion)

       s ~m ~a <Btn1Down>
                 ListProcessBtn1(ListBeginExtend)

       s ~m ~a <Btn1Up>
                 ListProcessBtn1(ListEndExtend)

       c ~s ~m ~a <Btn1Down>
                 ListProcessBtn1(ListBeginToggle)

       c ~s ~m ~a <Btn1Up>
                 ListProcessBtn1(ListEndToggle)

       ~s ~c ~m ~a <Btn1Down>
                 ListProcessBtn1(ListBeginSelect)

       ~s ~c ~m ~a <Btn1Up>
                 ListProcessBtn1(ListEndSelect)

       When  Display's  XmNenableBtn1Transfer  resource  has a value of XmBUT-
       TON2_ADJUST, the following actions apply:

       <Btn2Down>:
                 ListProcessBtn2(ListBeginExtend)

       <Btn2Motion>:
                 ListProcessBtn2(ListButtonMotion)

       <Btn2Up>: ListProcessBtn2(ListEndExtend)

   Action Routines
       The XmList action routines are described in the  following  list.   The
       current selection is always shown with inverted colors.

       ListAddMode():
                 Toggles the state of Add Mode for keyboard selection.

       ListBeginData():
                 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 (XmNbrowseSelectionCallback  when  XmNse-
                 lectionPolicy  is  set  to XmBROWSE_SELECT, XmNextendedSelec-
                 tionCallback  when  XmNselectionPolicy  is   set   to   XmEX-
                 TENDED_SELECT).

       ListBeginDataExtend():
                 If  XmNselectionPolicy  is  set to XmMULTIPLE_SELECT or XmEX-
                 TENDED_SELECT, this action moves the location cursor  to  the
                 first item in the list.

                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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 XmNextendedSelectionCallback callbacks.

       ListBeginExtend():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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 cur-
                 rent  anchor point.  If XmNautomaticSelection is set to True,
                 this action calls the XmNextendedSelectionCallback callbacks.
                 The  auto_selection_type  component of the callback structure
                 will be set to XmAUTO_BEGIN.

       ListBeginLine():
                 Moves the horizontal scroll region to the  beginning  of  the
                 line.

       ListBeginSelect():
                 If  XmNselectionPolicy  is  set to XmSINGLE_SELECT, deselects
                 any current selection and toggles the selection state of  the
                 item under the pointer.

                 If  XmNselectionPolicy  is  set to XmBROWSE_SELECT, deselects
                 any current selection and selects the item under the pointer.
                 If  XmNautomaticSelection is set to True, calls the XmNbrows-
                 eSelectionCallback callbacks.  The auto_selection_type compo-
                 nent of the callback structure will be set to XmAUTO_BEGIN.

                 If  XmNselectionPolicy  is  set to XmMULTIPLE_SELECT, toggles
                 the selection state of the item under the pointer.  Any  pre-
                 vious selections remain.

                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  this
                 action deselects any  current  selection,  selects  the  item
                 under  the pointer, and sets the current anchor at that item.
                 If XmNautomaticSelection is set to True,  this  action  calls
                 the  XmNextendedSelectionCallback callbacks.  The auto_selec-
                 tion_type component of the callback structure will be set  to
                 XmAUTO_BEGIN.

       ListBeginToggle():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  this
                 action moves the current anchor to the item under the pointer
                 without changing the current selection.  If the item is unse-
                 lected, this action selects it; if the item is selected, this
                 action  unselects  it.   If  XmNautomaticSelection  is set to
                 True,  this  action  calls  the  XmNextendedSelectionCallback
                 callbacks.

                 Otherwise,  the  list  takes  keyboard focus. No other action
                 occurs.  The auto_selection_type component  of  the  callback
                 structure will be set to XmAUTO_BEGIN.

       ListButtonMotion():
                 If  XmNselectionPolicy is set to XmBROWSE_SELECT, this action
                 deselects any current selection and selects  the  item  under
                 the pointer.  If XmNautomaticSelection is set to True and the
                 pointer has entered a new list item, this  action  calls  the
                 XmNbrowseSelectionCallback callbacks.

                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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 cur-
                 rent  anchor  point.  If XmNautomaticSelection is set to True
                 and the pointer has entered a new list item, calls the XmNex-
                 tendedSelectionCallback callbacks.

                 If  the  pointer  leaves a scrolled list, this action scrolls
                 the list  in  the  direction  of  the  pointer  motion.   The
                 auto_selection_type  component of the callback structure will
                 be set to XmAUTO_MOTION.

       ListCopyToClipboard()
                 Copies the content of the selected items to the clipboard  as
                 a  single  compound string with each item separated by a new-
                 line.  This action calls the  XmNconvertCallback  procedures,
                 possibly multiple times, for the CLIPBOARD selection.

       ListEndData():
                 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 (XmNbrowseSelectionCallback  when  XmNse-
                 lectionPolicy  is  set  to XmBROWSE_SELECT, XmNextendedSelec-
                 tionCallback  when  XmNselectionPolicy  is   set   to   XmEX-
                 TENDED_SELECT).

       ListEndDataExtend():
                 If  XmNselectionPolicy  is  set to XmMULTIPLE_SELECT or XmEX-
                 TENDED_SELECT, this action moves the location cursor  to  the
                 last item in the list.

                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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 XmNextendedSelectionCallback callbacks.

       ListEndExtend():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  this
                 action moves the location cursor to the last item selected or
                 deselected and calls the  XmNextendedSelectionCallback  call-
                 backs.

                 If XmNautomaticSelection is set to True, then the auto_selec-
                 tion_type field of the callback will be valid.  If  XmNselec-
                 tionPolicy  is  set  to  XmBROWSE_SELECT  and  the  currently
                 selected item position matches the position of the item  that
                 was  selected before the browse selection began, or if XmNse-
                 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur-
                 rently  selected item positions matches the set of item posi-
                 tions selected before the extended selection began, the call-
                 back   will   be   called  with  auto_selection_type  set  to
                 XmAUTO_NO_CHANGE.    Otherwise,   it   will   be    set    to
                 XmAUTO_CHANGE.

       ListEndLine():
                 Moves the horizontal scroll region to the end of the line.

       ListEndSelect():
                 This  action  moves  the  location  cursor  to  the last item
                 selected or deselected and calls  the  appropriate  selection
                 callbacks (XmNsingleSelectionCallback when XmNselectionPolicy
                 is set to  XmSINGLE_SELECT,  XmNbrowseSelectionCallback  when
                 XmNselectionPolicy  is set to XmBROWSE_SELECT, XmNmultipleSe-
                 lectionCallback when XmNselectionPolicy is  set  to  XmMULTI-
                 PLE_SELECT,  XmNextendedSelectionCallback  when XmNselection-
                 Policy is set to XmEXTENDED_SELECT).

                 If XmNautomaticSelection is set to True, then the auto_selec-
                 tion_type  field of the callback will be valid.  If XmNselec-
                 tionPolicy  is  set  to  XmBROWSE_SELECT  and  the  currently
                 selected  item position matches the position of the item that
                 was selected before the brose selection began, or  if  XmNse-
                 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur-
                 rently selected item positions matches the set of item  posi-
                 tions selected before the extended selection began, the call-
                 back  will  be  called  with   auto_selection_type   set   to
                 XmAUTO_NO_CHANGE.     Otherwise,    it   will   be   set   to
                 XmAUTO_CHANGE.

       ListEndToggle():
                 If XmNselectionPolicy is set to XmEXTENDED_SELECT, moves  the
                 location  cursor  to the last item selected or deselected and
                 calls the XmNextendedSelectionCallback callbacks.

                 If XmNautomaticSelection is set to True, then the auto_selec-
                 tion_type  field  of the callback will be valid. If XmNselec-
                 tionPolicy  is  set  to  XmBROWSE_SELECT  and  the  currently
                 selected  item position matches the position of the item that
                 was selected before the browse selection began, or if  XmNse-
                 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur-
                 rently selected item positions matches the set of item  posi-
                 tions selected before the extended selection began, the call-
                 back  will  be  called  with   auto_selection_type   set   to
                 XmAUTO_NO_CHANGE.     Otherwise,    it   will   be   set   to
                 XmAUTO_CHANGE.

       ListExtendNextItem():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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 XmNextendedS-
                 electionCallback callbacks.

       ListExtendPrevItem():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  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
                 XmNextendedSelectionCallback callbacks.

       ListScrollCursorVertically(percentage):
                 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 y event passed to the routine.

       ListKbdActivate():
                 Calls the callbacks  for  XmNdefaultActionCallback.   If  the
                 List's  parent  is a manager, this action passes the event to
                 the parent.

       ListKbdBeginExtend():
                 If XmNselectionPolicy is set to XmEXTENDED_SELECT,  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 selec-
                 tion 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 XmNautomaticSelection is set to True, this action
                 calls  the   XmNextendedSelectionCallback   callbacks.    The
                 auto_selection_type  component of the callback structure will
                 be set to XmAUTO_BEGIN".

       ListKbdBeginSelect():
                 If the XmNselectionPolicy is set  to  XmSINGLE_SELECT,  dese-
                 lects any current selection and toggles the state of the item
                 at the location cursor.  The auto_selection_type component of
                 the callback structure will be set to XmAUTO_BEGIN".

                 If  the  XmNselectionPolicy  is set to XmBROWSE_SELECT, dese-
                 lects any current selection and selects the item at the loca-
                 tion  cursor.  If XmNautomaticSelection is set to True, calls
                 the XmNbrowseSelectionCallback callbacks.

                 If the XmNselectionPolicy is set to  XmMULTIPLE_SELECT,  tog-
                 gles  the selection state of the item at the location cursor.
                 Any previous selections remain.

                 If the XmNselectionPolicy is set to XmEXTENDED_SELECT,  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  loca-
                 tion  cursor  and leaves the current selection unchanged.  If
                 XmNautomaticSelection is set to True, this action  calls  the
                 XmNextendedSelectionCallback   callbacks.    The  auto_selec-
                 tion_type component of the callback structure will be set  to
                 XmAUTO_BEGIN".

       ListKbdCancel():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT 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 XmNautomaticSe-
                 lection is set to True, this action calls the  XmNextendedSe-
                 lectionCallback callbacks; otherwise, if the parent is a man-
                 ager, it passes the event to  the  parent.   The  auto_selec-
                 tion_type  component of the callback structure will be set to
                 XmAUTO_CANCEL".

       ListKbdDeSelectAll():
                 If the XmNselectionPolicy is set to XmSINGLE_SELECT, XmMULTI-
                 PLE_SELECT,  or  XmEXTENDED_SELECT  in  Add Mode, this action
                 deselects all items in the list.  If  the  XmNselectionPolicy
                 is set to XmEXTENDED_SELECT in Normal Mode, this action dese-
                 lects all items in the list (except the item at the  location
                 cursor  if the shell's XmNkeyboardFocusPolicy is XmEXPLICIT).
                 This action also calls the  appropriate  selection  callbacks
                 (XmNsingleSelectionCallback when XmNselectionPolicy is set to
                 XmSINGLE_SELECT, XmNmultipleSelectionCallback when  XmNselec-
                 tionPolicy is set to XmMULTIPLE_SELECT, XmNextendedSelection-
                 Callback   when   XmNselectionPolicy   is   set   to    XmEX-
                 TENDED_SELECT).

       ListKbdEndExtend():
                 If  XmNselectionPolicy  is  set  to  XmEXTENDED_SELECT,  this
                 action calls the XmNextendedSelectionCallback callbacks.

                 If XmNautomaticSelection is set to True, then the auto_selec-
                 tion_type  field  of the callback will be valid. If XmNselec-
                 tionPolicy  is  set  to  XmBROWSE_SELECT  and  the  currently
                 selected  item position matches the position of the item that
                 was selected before the browse selection began, or if  XmNse-
                 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur-
                 rently selected item positions matches the set of item  posi-
                 tions selected before the extended selection began, the call-
                 back  will  be  called  with   auto_selection_type   set   to
                 XmAUTO_NO_CHANGE.     Otherwise,    it   will   be   set   to
                 XmAUTO_CHANGE.

       ListKbdEndSelect():
                 Calls the appropriate  selection  callbacks  (XmNsingleSelec-
                 tionCallback   when   XmNselectionPolicy  is  set  to  XmSIN-
                 GLE_SELECT, XmNbrowseSelectionCallback when  XmNselectionPol-
                 icy  is  set to XmBROWSE_SELECT, XmNmultipleSelectionCallback
                 when XmNselectionPolicy is set to  XmMULTIPLE_SELECT,  XmNex-
                 tendedSelectionCallback  when  XmNselectionPolicy  is  set to
                 XmEXTENDED_SELECT).

                 If XmNautomaticSelection is set to True, then the auto_selec-
                 tion_type  field  of the callback will be valid. If XmNselec-
                 tionPolicy  is  set  to  XmBROWSE_SELECT  and  the  currently
                 selected  item position matches the position of the item that
                 was selected before the browse selection began, or if  XmNse-
                 lectionPolicy is set to XmEXTENDED_SELECT and the set of cur-
                 rently selected item positions matches the set of item  posi-
                 tions selected before the extended selection began, the call-
                 back  will  be  called  with   auto_selection_type   set   to
                 XmAUTO_NO_CHANGE.     Otherwise,    it   will   be   set   to
                 XmAUTO_CHANGE.

       ListKbdSelectAll():
                 If  XmNselectionPolicy   is   set   to   XmSINGLE_SELECT   or
                 XmBROWSE_SELECT, this action selects the item at the location
                 cursor.  If XmNselectionPolicy is set to XmEXTENDED_SELECT or
                 XmMULTIPLE_SELECT,  it  selects  all items in the list.  This
                 action also calls the appropriate selection callbacks  (XmNs-
                 ingleSelectionCallback when XmNselectionPolicy is set to XmS-
                 INGLE_SELECT, XmNbrowseSelectionCallback  when  XmNselection-
                 Policy  is  set to XmBROWSE_SELECT, XmNmultipleSelectionCall-
                 back when XmNselectionPolicy  is  set  to  XmMULTIPLE_SELECT,
                 XmNextendedSelectionCallback  when  XmNselectionPolicy is set
                 to XmEXTENDED_SELECT).

       ListLeftChar():
                 Scrolls the list one character to the left.

       ListLeftPage():
                 Scrolls the list one page to the left.

       ListNextItem():
                 Moves the location cursor to the next item in the list.

                 If the XmNselectionPolicy is  set  to  XmBROWSE_SELECT,  this
                 action  also  selects  the  next  item, deselects any current
                 selection, and  calls  the  XmNbrowseSelectionCallback  call-
                 backs.

                 If  the  XmNselectionPolicy is set to XmEXTENDED_SELECT, 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  XmNextendedSelectionCallback  callbacks.
                 In Add Mode, this action does not affect the selection or the
                 anchor.

       ListNextPage():
                 Scrolls the list to the next page, moving the location cursor
                 to a new item.

                 If  the  XmNselectionPolicy  is  set to XmBROWSE_SELECT, this
                 action also selects  the  new  item,  deselects  any  current
                 selection,  and  calls  the  XmNbrowseSelectionCallback call-
                 backs.

                 If the XmNselectionPolicy is set to  XmEXTENDED_SELECT,  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 XmNextendedSelectionCallback callbacks.
                 In Add Mode, this action does not affect the selection or the
                 anchor.

       ListPrevItem():
                 Moves the location cursor to the previous item in the list.

                 If  the  XmNselectionPolicy  is  set to XmBROWSE_SELECT, this
                 action also selects the previous item, deselects any  current
                 selection,  and  calls  the  XmNbrowseSelectionCallback call-
                 backs.

                 If the XmNselectionPolicy is set to  XmEXTENDED_SELECT,  this
                 action  in  Normal Mode also selects the previous item, dese-
                 lects any current selection, moves the current anchor to  the
                 previous  item,  and  calls  the XmNextendedSelectionCallback
                 callbacks.  In Add Mode, this  action  does  not  affect  the
                 selection or the anchor.

       ListPrevPage():
                 Scrolls  the  list  to the previous page, moving the location
                 cursor to a new item.

                 If the XmNselectionPolicy is  set  to  XmBROWSE_SELECT,  this
                 action  also  selects  the  new  item,  deselects any current
                 selection, and  calls  the  XmNbrowseSelectionCallback  call-
                 backs.

                 If  the  XmNselectionPolicy is set to XmEXTENDED_SELECT, 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  XmNextendedSelectionCallback  callbacks.
                 In  Add Mode this action does not affect the selection or the
                 anchor.

       ListProcessBtn1(string)
                 When Display's XmNenableBtn1Transfer resource is  not  XmOFF,
                 the  actions  for  selection  and  transfer are integrated on
                 <Btn1>.  When the button is  not  performing  a  transfer  or
                 drag,  the  action  that is performed depends on the value of
                 string, which can be one of the following actions:

                    o  ListButtonMotion

                    o  ListBeginExtend

                    o  ListEndExtend

                    o  ListBeginToggle

                    o  ListEndToggle

                    o  ListBeginSelect

                    o  ListEndSelect

       ListProcessBtn2
                 When Display's XmNenableBtn1Transfer resource has a value  of
                 XmBUTTON2_TRANSFER,  the  actions for extending selection are
                 bound on <Btn2>, and a drag starts  immediately.   When  Dis-
                 play's  XmNenableBtn1Transfer  resource has a value of XmBUT-
                 TON2_ADJUST, the action that  is  performed  depends  on  the
                 value of string, which can be one of the following actions:

                    o  ListBeginExtend

                    o  ListButtonMotion

                    o  ListEndExtend

       ListProcessDrag():
                 Drags  the  content of one or more selected list items.  Each
                 item is separated by a newline.  If BTransfer is  pressed  on
                 an  unselected  item,  it drags only that item, excluding any
                 other selected items.  This action sets the XmNconvertProc of
                 the  DragContext to a function that calls the XmNconvertCall-
                 back procedures, possibly multiple times, for the _MOTIF_DROP
                 selection.

       ListQuickNavigate
                 Navigates  to  an item. When List's XmNmatchBehavior resource
                 is XmQUICK_NAVIGATE, this action uses 1-character  navigation
                 to  navigate.  Refer  to  the XmNmatchBehavior resource for a
                 description of how this navigation works.

       ListRightChar():
                 Scrolls the list one character to the right.

       ListRightPage():
                 Scrolls the list one page to the right.

       PrimitiveHelp():
                 Calls the callbacks for  XmNhelpCallback  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.

       PrimitiveNextTabGroup():
                 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.

       PrimitivePrevTabGroup():
                 Moves the focus to the first item contained within the previ-
                 ous  tab  group.   If  the beginning of the tab group list is
                 reached, it wraps to the end of the tab group list.

   Additional Behavior
       The List widget has the following additional behavior:

       <Double Click>
                 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  call-
                 backs for XmNdefaultActionCallback.  The item's colors invert
                 to indicate that it is selected.  The  XmNdoubleClickInterval
                 resource  can  be  used to specify a time span that overrides
                 the display's multi-click time.

       <FocusIn>:
                 If the focus policy is Explicit, this action sets  the  focus
                 and draw the location cursor.

       <FocusOut>:
                 If  the  focus  policy  is  Explicit, this action removes the
                 focus and erase the location cursor.

   Virtual Bindings
       The bindings for virtual keys are  vendor  specific.   For  information
       about bindings for virtual buttons and keys, see VirtualBindings(3).


RELATED

       Core(3), XmCreateList(3), XmCreateScrolledList(3), XmFontListCreate(3),
       XmFontListAppendEntry(3), XmListAddItem(3),  XmListAddItems(3),  XmLis-
       tAddItemUnselected(3),   XmListAddItemsUnselected(3),   XmListDeleteAl-
       lItems(3), XmListDeleteItem(3), XmListDeleteItems(3), XmListDeleteItem-
       sPos(3),  XmListDeletePos(3),  XmListDeletePositions(3), XmListDeselec-
       tAllItems(3), XmListDeselectItem(3), XmListDeselectPos(3), XmListGetKb-
       XmListGetMatchPos(3),  XmListGetSelectedPos(3), XmListItemEx-
       ists(3), XmListItemPos(3), XmListPosToBounds(3), XmListReplaceItems(3),
       XmListReplaceItemsPos(3),  XmListReplaceItemsPos(3), XmListReplaceItem-
       sPosUnselected(3),    XmListReplaceItemsUnselected(3),     XmListSelec-
       tItem(3),    XmListSelectPos(3),   XmListSetAddMode(3),   XmListSetBot-
       tomItem(3),   XmListSetBottomPos(3),   XmListSetHorizPos(3),    XmList-
       SetItem(3),  XmListSetKbdItemPos(3),  XmListSetPos(3),  XmListUpdateSe-
       lectedList(3),   XmListYToPos(3),   XmPrimitive(3)   XmStringCreate(3),
       XmVaCreateList(3), and XmVaCreateManagedList(3).



                                                          XmList(library call)

openMotif 2.3.1 - Generated Sun Nov 30 20:04:32 CST 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.