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

FreeBSD Manual Pages

  
 
  

home | help
XmMultiList(3x)						       XmMultiList(3x)

NAME
       XmMultiList -- The Multi-column List widget

SYNOPSIS
       #include	<Xm/MultiList.h>

DESCRIPTION
       This widget contains a multi-column list	with headers along the top and
       a search	area along the bottom. The list	has scrollbars along the right
       and  bottom  edges that allow vertical and horizontal scrolling both by
       column and by pixel. The	portion	of the list  data  that	 is  currently
       visible	can  be	 altered by scrollbar actions, widget resource setting
       and the redisplay of the	list data after	a string search	has been  suc-
       cessful.	 The  sorting  of  elements within a particular	column is also
       supported. To sort the list by the elements in a	given  column,	select
       the column's title.

       To search for a particular string in the	list, type the string value to
       be searched for in the list's associated	text field and then press  the
       "Find"  pushbutton.  The	 search	for the	string begins in the currently
       selected	row, after the location	of the previously searched for string,
       or  at  the  first column and first row if there	is no column selected.
       If the string is	not found in  that  row,  then	the  search  continues
       through	all rows after and then	before,	the currently selected row. If
       the string is found, the	display	of the list is adjusted	 to  make  the
       string  visible.	If the string was not found, or	if the string is visi-
       ble, the	application will issue a warning beep.

       Pointer button one allows the user to select a  row  or	a  column  for
       sorting.	 The callbacks on the doubleClickCallback list are called when
       the user	double clicks pointer button one. If the list data can contain
       a row pixmap to display at the extreme left of the row.

   Classes
       MultiList  inherits  behavior, resources, and traits from Core, Compos-
       ite, Constraint,	and XmManager.

       The class pointer is xmMultiListWidgetClass.

       The class name is XmMultiList.

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

       +-------------------------------------------------------------------------------------------------------------+
       |			   |		  XmMultiList Resource Set		|		    |	     |
       |Name			   | Class		   | Type			| Default	    | Access |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNcolumnTitles		   | XmCColumnTitles	   | XmString *			| NULL		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNdoubleClickCallback	   | XmCCallback	   | XtCallbackList		| NULL		    | C	     |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNentryData		   | XmCEntryData	   | XtPointer			| NULL		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNfindLabel		   | XmCFindLabel	   | XmString			| Find		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNfirstColumn		   | XmCFirstLocation	   | short			| 0		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNfirstColumnPixmaps	   | XmCFirstColumnPixmaps | Boolean			| False		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNfirstRow		   | XmCFirstLocation	   | short			| 0		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNfontList		   | XmCFontList	   | XmFontList			| dynamic	    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNheight		   | XmCHeight		   | Dimension			| 300		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNnumColumns		   | XmCNumColumns	   | short			| 0		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNnumRows		   | XmCNumRows		   | short			| 0		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNselectedColumn	   | XmCSelectedColumn	   | short			| 0		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNselectionPolicy	   | XmCSelectionPolicy	   | unsigned char		| XmEXTENDED_SELECT | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNshowFind		   | XmCShowFind	   | Boolean			| True		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNsingleSelectionCallback | XmCCallback	   | XtCallbackList		| NULL		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNsortFunctions	   | XmCFunction	   | XmMultiListSortFunction **	| NULL		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNtitle		   | XmCTitle		   | XmString			| NULL		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       |XmNwidth		   | XmCWidth		   | Dimension			| 300		    | CSG    |
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       +---------------------------+-----------------------+----------------------------+-------------------+--------+
       XmNcolumnTitles
		 This is an array of length numColumns of strings displayed at
		 the  top of each column. The data is allocated	and maintained
		 by the	client.

       XmNdoubleClickCallback
		 All routines in this list will	be called  whenever  the  user
		 double	clicks on a row	in the list.

       XmNentryData
		 This  resource	 is  the  data associated with each row	in the
		 list. The data	is an array of	XmMultiListRowInfo  structures
		 of  length numRows allocated by the client. The data is allo-
		 cated and maintained by the  client.  The  XmMultiListRowInfo
		 structure is defined below.

       XmNfindLabel
		 The label to be shown on the find button.

       XmNfirstColumn
		 This resource allows the client to adjust the current view of
		 the list data to have a new top left  column  location.  When
		 setting this resource,	firstRow should	also be	updated.

       XmNfirstColumnPixmaps
		 This  resource	 specifies  that  the pixmap stored in the row
		 info structure	should be used instead	of  XmMultiListRowInfo
		 values[0]. If pixmaps are present, the	rows may be dragged by
		 pressing on the pixmap	with pointer button three. If this re-
		 source	is True, then values[0]	is never referenced. If	False,
		 then the XmMultiListRowInfo data pixmap is never referenced.

       XmNfirstRow
		 This resource allows the client to adjust the current view of
		 the  list data	to have	a new top left row location. When set-
		 ting this resource, firstColumn should	also be	updated.

       XmNfontList
		 This is an OSF/Motif style font list. The first font in  this
		 list  will  be	used to	display	all text in the	MultiList wid-
		 get. The MultiList widget currently supports only one font.

       XmNheight This is the overall height value assigned  to	the  MultiList
		 widget.  Modifying  this  resource will affect	scrollbar size
		 and location.

       XmNnumColumns

       XmNnumRows
		 These resources specify the number of columns	and  rows  the
		 widget	 expects  to  display. These resources are used	as the
		 maximum indices for many of the other resources in this  wid-
		 get.  Care  should be taken when modifying these resources to
		 ensure	that the other values have also	been modified.

       XmNselectedColumn
		 This is the index of the currently selected column. This also
		 the column by which the list is being sorted.

       XmNselectionPolicy
		 Defines  the  interpretation  of  the select action. This re-
		 source	can have the values XmSINGLE_SELECT or	XmEXTENDED_SE-
		 LECT. Other values result in undefined	behavior.

       XmNshowFind
		 This boolean manages and unmanages the	find button

       XmNsingleSelectionCallback
		 All  routines	in  this list will be called whenever the user
		 clicks	on a line in the list.	 A  pointer  to	 the  XmMulti-
		 ListRowInfo  structure	 corresponding to the line selected is
		 passed	as call_data. If in extended select mode the value  of
		 call_data is undefined.

       XmNsortFunctions
		 This is an array of functions,	one for	each column, called to
		 determine the ordering	of the rows in the column, similar  to
		 qsort.

       XmNtitle	 This  is the title that is displayed at the top of the	Multi-
		 List widget.  If this value is	NULL, the title	area will  not
		 be shown.

       XmNwidth	 This  is  the	overall	 width value assigned to the MultiList
		 widget. Modifying this	resource will  affect  scrollbar  size
		 and location.

   Specifying Children Resources
       The  MultiList  widget  is composed of many simple widgets. In order to
       achieve full functionality of the Toolkit, it is	sometimes desirable to
       set  attribute  values directly on those	widgets. The widget ids	of the
       sub-widgets can be obtained by using the	XtNameToWidget() function pro-
       vided by	the Xt Intrinsics.

       XmMultiList <named by application>

				  XmLabel title

				  XmScrollbar vertBar

				  XmScrollBar horizBar

				  XmFrame frame

							  XmPushButton find

							  XmText findText

   Using the Resource Database
       The  MultiList  widget  is actually a collection	of pieces. It provides
       the geometry layout for the collection as well as  tying	 together  the
       pieces  to  form	 a consistent package.	Many of	the resources that are
       documented as being part	of the MultiList widget	are really part	of the
       internal	 list sub-component. The MultiList widget will pass these val-
       ues through to the proper child when they are set at time  of  creation
       or  with	 XtSetValues  or XtGetValues. However, when setting a resource
       via the resource	database you must use either the name of the child  or
       the general specification (*) rather than the specific one (.).

   The XmMultiListRowInfo Structure
       The XmMultiListRowInfo structure	is used	to contain the entryData asso-
       ciated with each	Row in the List.

       typedef struct {

				  String * values;	  /* The array of column strings */
				  Pixmap pixmap;	  /* mini-icon pixmaps.	*/
				  Boolean selected;	  /* row selected. */

				  /*
				   * Provided for the convenience of the application programmer
				   */

				  short	* sort_id;
				  XtPointer data;

				  /*
				   * Private to	the MultiList widget (do not modify these)
				   */

				  short	pix_width;	  /* of	the pixmap. */
				  short	pix_height;	  /* of	the pixmap. */
				  short	pix_depth;	  /* of	the pixmap. */

				  Boolean old_sel_state;

       } XmMultiListRowInfo;

       values			  This is an array of strings of  length  num-
       Columns	which  represents the strings displayed	in each	column of this
       row. The	data is	allocated and maintained by the	client.	If firstColum-
       nPixmaps	   is	 True,	  then	  value[0]    is   never   referenced.
       pixmap			  This is the pixmap displayed to the left  of
       this row. If firstColumnPixmaps is True then this value is never	refer-
       enced and mayn remain unset. If no pixmap is desired for	this row, even
       though  firstColumnPixmaps  is  True,  set the value of pixmap to None.
       Color pixmaps may be used.  sort_id		      This is provided
       for  the	convenience of the client and is expected to be	used as	a sort
       index for this row. One value should be specified for  each  column  of
       the     row.	See	"sortFunctions"	    below     for     details.
       data			  This is provided for the convenience of  the
       client and may be used for any purpose. It is intended to be used as an
       identifier for the object pointed to by this row

       selected			  This value is	True if	this row is  selected;
       may be set by the application.

       Neither	sort_id	 nor data are used by the MultiList widget; they exist
       solely for the convenience of the programmer.

       +----------------------------------------------------------------------------------------------------+
       |			|	      XmManager	Resource Set	    |			   |	    |
       |Name			| Class			| Type		    | Default		   | Access |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowColor	| XmCBottomShadowColor	| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowPixmap	| XmCBottomShadowPixmap	| Pixmap	    | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNforeground		| XmCForeground		| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhelpCallback		| XmCCallback		| XtCallbackList    | NULL		   | C	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightColor	| XmCHighlightColor	| Pixel		    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightPixmap	| XmCHighlightPixmap	| Pixmap	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNinitialFocus		| XmCInitialFocus	| Widget	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNlayoutDirection	| XmCLayoutDirection	| XmDirection	    | dynamic		   | CG	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNnavigationType	| XmCNavigationType	| XmNavigationType  | XmTAB_GROUP	   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNpopupHandlerCallback	| XmCCallback		| XtCallbackList    | NULL		   | C	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNshadowThickness	| XmCShadowThickness	| Dimension	    | dynamic		   | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNstringDirection	| XmCStringDirection	| XmStringDirection | dynamic		   | CG	    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |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    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       +------------------------+-----------------------+-------------------+----------------------+--------+
       +-----------------------------------------------------------------------+
       |		  |	Composite Resource Set	    |	      |	       |
       |Name		  | Class	      |	Type	    | Default |	Access |
       +------------------+-------------------+-------------+---------+--------+
       |XmNchildren	  | XmCReadOnly	      |	WidgetList  | NULL    |	G      |
       +------------------+-------------------+-------------+---------+--------+
       |XmNinsertPosition | XmCInsertPosition |	XtOrderProc | NULL    |	CSG    |
       +------------------+-------------------+-------------+---------+--------+
       |XmNnumChildren	  | XmCReadOnly	      |	Cardinal    | 0	      |	G      |
       +------------------+-------------------+-------------+---------+--------+
       +------------------+-------------------+-------------+---------+--------+
       +---------------------------------------------------------------------------------------------------------------+
       |			      |		      Core Resource SetName			      |	Class			      |	Type	       | Default	      |	Access |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNaccelerators		      |	XmCAccelerators		      |	XtAccelerators | dynamic	      |	N/A    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |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    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       +------------------------------+-------------------------------+----------------+----------------------+--------+
   Translations
       The following are the default translation bindings  used	 by  the  icon
       button:

       ~Ctrl ~Shift <Btn1Down>:	  ButtonDown()
       Ctrl ~Shift  <Btn1Down>:	  ButtonDown(Toggle)
       ~Ctrl Shift  <Btn1Down>:	  ButtonDown(Extend)
       Button1 <Motion>:	  Motion()
       <Btn1Up>:		  ButtonUpOrLeave()

       The following actions are supported by the MultiList:

	      ButtonDown(type)
			Processes  a  button  press action that	may begin with
			either a select	or a double click. The	type  argument
			can be either Toggle or	Extend.	These values determine
			which mode of an extended select will be initiated  on
			this  button  event. Consult the OSF/Motif Style Guide
			for details.

	      Motion()	Processes motion events	to allow the selection	region
			to  be modified	when in	extended selection mode. It is
			assumed	that this action is called between  a  Button-
			Down() and ButtonUpOrLeave() action.

	      ButtonUpOrLeave()
			Cleans up after	ButtonDown() and Motion().

Callback Routines
       All  procedures	on  the	 MultiList's  singleSelectionCallback and dou-
       bleClickCallback	lists will have	 a  pointer  to	 a  XmMultiListRowInfo
       structure  passed to them in the	call_data field. This structure	is de-
       fined above.

       Note: if	a single SelectionCallback is registered on  an	 MultiList  in
       extended_select_mode, the value of call_data is undefined.

		 void  (callback)(Widget  w,  XtPointer	client_data, XtPointer
		 call_data)

       w	 the MultiList widget

       client_data
		 the client data specified by the application

       call_data a pointer to an XmMultiListRowInfo structure corrsponding the
		 the row selected

Sort Function
       typedef	int  (XmMultiListSortFunction) (short column, XmMultiRowInfo *
       row1, XmMultiRowInfo * row2);

       column	 the column currently being sorted

       row1, row2
		 the two rows being compared. The return value must be an  in-
		 teger	less  than,  equal to, or greater than 0, depending on
		 whether the first argument is less than, equal	to, or greater
		 than the second.

RELATED
       Composite(3),   Constraint(3),  Core(3),	 XmCreateMultiList(3),	XmMan-
       ager(3),	 XmMultiListDeselectAllItems(3),   XmMultiListDeselectItem(3),
       XmMultiListDeselectItems(3), XmMultiListDeselectRow(3), XmMultiListGet-
       SelectedRowArray(3),    XmMultiListGetSelectedRows(3),	  XmMultiList-
       MakeRowVisible(3),    XmMultiListSelectAllItems(3),   XmMultiListSelec-
       tItems(3), XmMultiListSelectRow(3), and XmMultiListToggleRow(3).

COPYRIGHT
       Copyright (c) 1992 by Integrated	Computer Solutions, Inc.

							       XmMultiList(3x)

NAME | SYNOPSIS | DESCRIPTION | Callback Routines | Sort Function | RELATED | COPYRIGHT

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

home | help