Provided by: libmotif-dev_2.3.3-5ubuntu1_amd64 bug

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

       List uses the XmQTspecifyRenderTable, XmQTscrollFrame, and XmQTnavigator traits, and holds
       the XmQTtransfer trait.

   Selection
       Each list has one of four selection models:

          ·  Single Select

          ·  Browse Select

          ·  Multiple Select

          ·  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 selection 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 discontiguous ranges of items.
       Pressing  <Ctrl><Btn1>  on  an  item toggles its selection state but does not deselect any
       other selected  items.   Dragging  <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 COMPOUND_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 COMPOUND_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_COMPOUND_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  selection  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 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
                 XmRegisterSegmentEncoding and XmMapSegmentEncoding.

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

   Classes
       List inherits behavior, resources, and traits from Core and XmPrimitive.

       The class pointer is xmListWidgetClass.

       The class name is XmList.

   New Resources
       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  .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).

       ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
Binary file (standard input) matches