Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmList(3)		   Library Functions Manual		     XmList(3)

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  be-
       comes  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  al-
       lows 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.  Re-
       leasing <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 de-
       select 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  se-
       lection 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 ac-
       tion 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> ac-
       tion.  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  se-
       lection.

       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  lo-
		 cale.	 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  en-
		 coding	 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_DE-
		 FERRED_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 ap-
		 plications  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 Xm-
       NdestinationCallback  procedures	are responsible	for any	data transfers
       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  an-
		 cestor	 is  found,  the  font	list is	initialized to the Xm-
		 TEXT_RENDER_TABLE value of the	ancestor widget.  If  no  such
		 widget	is found, the default is implementation	dependent. Re-
		 fer 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 in-
		 formation on the creation and structure of compound  strings.
		 XtGetValues  for  this	 resource returns the list items them-
		 selves, not a copy of the list	items.	The  application  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  in-
		 creases 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 be-
			   tween 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  ex-
		 actly	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, Xm-
		 ListDeselectAllItems, XmListDeselectItem,  XmListDeselectPos,
		 XmListSelectItem,   XmListSelectPos,  or  XmListUpdateSelect-
		 edList	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 se-
			   lect	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	XmMULTIPLE_SE-
			   LECT).

       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 ob-
		 soleted by XmNlayoutDirection,	but is kept here for  backward
		 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 de-
		 termine 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, re-
       fer 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 SetName			      |	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 ev-
       ery 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 ex-
		 ists 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, se- |
       |		     | lected_item_count,     se- |
       |		     | lected_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,  se- |
       |		     | lected_item_count,     se- |
       |		     | lected_item_positions	  |
       +---------------------+----------------------------+
       |XmCR_EXTENDED_SELECT | reason,	  event,    item, |
       |		     | item_length,    item_posi- |
       |		     | tion, selected_items,  se- |
       |		     | lected_item_count,     se- |
       |		     | lected_item_positions, se- |
       |		     | lection_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 re-
		 quested.  Possible values are CLIPBOARD, PRIMARY,  SECONDARY,
		 and _MOTIF_DROP.

       operation Indicates the type of transfer	operation requested.

		    o  When  the selection is PRIMARY, possible	values are Xm-
		       MOVE, 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 op-
       tion 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, se-
		 lects 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	XmEXTENDED_SE-
		 LECT).

       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  ac-
		 tion  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 an-
		 chor 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 ac-
		 tion 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  ac-
		 tion  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  ac-
		 tion  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 oc-
		 curs.	 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  ac-
		 tion  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  ex-
		 tended	 selection was done and	changes	the selection state of
		 the item under	the pointer and	all items between it  and  the
		 current  anchor point to the state of the item	at the current
		 anchor	point.	If XmNautomaticSelection is set	 to  True  and
		 the pointer has entered a new list item, calls	the XmNextend-
		 edSelectionCallback 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, se-
		 lects 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	XmEXTENDED_SE-
		 LECT).

       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  ac-
		 tion  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 ac-
		 tion 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  se-
		 lected	 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  se-
		 lected	 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 se-
		 lected	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 se-
		 lected	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 ac-
		 tion 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 ac-
		 tion 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  Xm-
		 NextendedSelectionCallback 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  an-
		 chor  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  ex-
		 tended	selection is being made	from the current anchor	point,
		 this action cancels the new selection and restores the	selec-
		 tion  state  of the items in that range to their state	before
		 the extended selection	was done.  If XmNautomaticSelection is
		 set  to True, this action calls the XmNextendedSelectionCall-
		 back callbacks; otherwise, if the parent  is  a  manager,  it
		 passes	the event to the parent.  The auto_selection_type com-
		 ponent	of the callback	structure will be set  to  XmAUTO_CAN-
		 CEL".

       ListKbdDeSelectAll():
		 If the	XmNselectionPolicy is set to XmSINGLE_SELECT, XmMULTI-
		 PLE_SELECT, or	XmEXTENDED_SELECT in Add Mode, this action de-
		 selects  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	XmEXTENDED_SE-
		 LECT).

       ListKbdEndExtend():
		 If XmNselectionPolicy is set to XmEXTENDED_SELECT,  this  ac-
		 tion 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 se-
		 lected	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  XmSINGLE_SE-
		 LECT,	XmNbrowseSelectionCallback  when XmNselectionPolicy is
		 set  to  XmBROWSE_SELECT,  XmNmultipleSelectionCallback  when
		 XmNselectionPolicy is set to XmMULTIPLE_SELECT, XmNextendedS-
		 electionCallback when	XmNselectionPolicy  is	set  to	 XmEX-
		 TENDED_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 se-
		 lected	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  Xm-
		 BROWSE_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, Xm-
		 NextendedSelectionCallback 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 ac-
		 tion also selects the next item, deselects any	current	selec-
		 tion, and calls the XmNbrowseSelectionCallback	callbacks.

		 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 ac-
		 tion also selects the new item, deselects any current	selec-
		 tion, and calls the XmNbrowseSelectionCallback	callbacks.

		 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 ac-
		 tion  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 se-
		 lection 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 ac-
		 tion also selects the new item, deselects any current	selec-
		 tion, and calls the XmNbrowseSelectionCallback	callbacks.

		 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 de-
		 scription 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 fo-
		 cus 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-
       dItemPos	 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),  Xm-
       VaCreateList(3),	and XmVaCreateManagedList(3).

								     XmList(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmList&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help