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

FreeBSD Manual Pages


home | help
XxExt18LIst(3x)						       XxExt18LIst(3x)

       The Internationalized Extended List widget

       #include	<Xm/Ext18List.h>

       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.

Normal Resources
       Name		     Class		  Type		      Default
       columnTitles	     ColumnTitles	  String *	      NULL
       doubleClickCallback   Callback		  Callback	      NULL
       entryData	     EntryData		  Xm18RowInfo*	      NULL
       findLabel	     XmString		  XmString	      Find
       firstColumn	     FirstLocation	  short		      0
       firstColumnPixmaps    FirstColumnPixmaps	  Boolean	      False
       firstRow		     FirstLocation	  short		      0
       fontList		     FontList		  FontList	      "fixed"
       height		     Dimension		  VerticalDimension   300
       numColumns	     NumColumns		  short		      0
       numRows		     NumRows		  short		      0
       selectedColumn	     SelectedColumn	  short		      0
       selectionPolicy	     SelectionPolicy	  SelectionPolicy     XmEXTENDED_
       showFind		     boolean		  boolean	      True
       singleSelection	     Callback		  Callback	      NULL
       sortFunctions	     Function		  Function	      NULL
       title		     Title		  String	      name of
       width		     Dimension		  Horizontal	      Dimension

       All  resource  names  begin with	XmN and	all resource class names begin
       with XmC.

       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.

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

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

       The label to be shown on	the find button.

       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  re-
       source, firstRow	should also be updated.

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

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

       This  is	an OSF/Motif style font	list. The first	font in	this list will
       be used to display all text in the Extended List	widget.	 The  Extended
       List widget currently supports only one font.

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

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

       This is the index of the	currently selected column. This	also the  col-
       umn by which the	list is	being sorted.

       Defines the interpretation of the select	action.	This resource can have
       the values XmSINGLE_SELECT or XmEXTENDED_SELECT.	Other values result in
       undefined behavior.

       This boolean manages and	unmanages the find button

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

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

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

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

Specifying Children Resources
       The  Extended  List 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
       provided	by the Xt Intrinsics.

       XmExt18List <named by application>

	    XmLabel title

	    XmScrollbar	vertBar

	    XmScrollBar	horizBar

	    XmFrame frame

	    XmPushButton find

	    XmText findText

Using the Resource Database
       The  Extended  List  widget is actually a collection of pieces. It pro-
       vides 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 Extended  List  widget  are	really
       part  of	the internal list sub-component. The Extended List widget will
       pass these values 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 Xm18RowInfo	Structure
       The Xm18RowInfo structure is used to contain the	 entryData  associated
       with each Row in	the Extended List.

       typedef struct _Xm18RowInfo{


	* Used by the IList widget


	    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 Extended List 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;

       } Xm18RowInfo;

       values	      This  is	an array of strings of length numColumns which
		      represents the strings displayed in each column of  this
		      row. The data is allocated and maintained	by the client.
		      If firstColumnPixmaps is True, then  value[0]  is	 never

       pixmap	      This is the pixmap displayed to the left of this row. If
		      firstColumnPixmaps is True then this value is never ref-
		      erenced  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

       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	Extended List widget; they ex-
       ist solely for the convenience of the programmer.

Translations and Actions
       The  following  are  the	 default translation bindings used by the icon

       ~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 icon button:

       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.

       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	ButtonDown() and ButtonUpOrLeave() action.

       Cleans up after ButtonDown() and	Motion().

Callback Routines
       All  procedures on the Extended List's singleSelectionCallback and dou-
       bleClickCallback	lists will have	a pointer to a	Xm18RowInfo  structure
       passed to them in the call_data field. This structure is	defined	above.

       Note:  if  a single SelectionCallback is	registered on an extended list
       in extended_se- lect_mode, the value of call_data is undefined.

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

       w	      the Extended List	widget

       client_data    the client data specified	by the application

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

Sort Function
       typedef	int  (Xm18SortFunction)	 (short	 column,  Xm18RowInfo  * row1,
			   Xm18RowInfo * row2);

       column	      the column currently being sorted

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

Convenience Routines

       Xm18RowInfo ** XmExt18ListGetSelectedRows (Widget w)

       w	      extended list widget

       Use  the	XmExt18ListGetSelectedRows function to find the	rows that cur-
       rently are selected in an extended list.	The Xm18RowInfo	** returned by
       this function contains a	NULL terminated	array of Xm18RowInfo pointers.
       The calling routine is responsible for  freeing	the  returned  pointer
       with  XtFree().	The  function  will return NULL	if no elements are se-

       Widget	 XmCreateExtended18List(Widget	  parent,     String	 name,
			    ArgList args, Cardinal num_args)

       parent	      parent	of    the   extended   list   widget   to   be
       name	      name   of	  the	extended    list    widget    to    be
       args	      arguments	   to	pass   to   XtCreateWidget   for   the
		      extended list
       num_args	      number of	arguments passed

       This convenience	routine	simply takes the passed	parameters  and	 calls
       XtCreateWidget, returning the widget created.

       void XmExt18ListUnselectAllItems( Widget	w )

       w	      the extended list	widget to be modified

       Unselects all rows of the passed	extended list widget and returns noth-

       void XmExt18ListUnselectItem(Widget w, Xm18RowInfo *row_info)

       w	      extended list widget
       row_info	      pointer to the row which is to  be		 unse-

       Unselects  the  row  designated by row_info of the passed extended list
       widget w

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


NAME | SYNOPSIS | DESCRIPTION | Normal Resources | columnTitles | doubleClickCallback | entryData | findLabel | firstColumn | firstColumnPixmaps | firstRow | fontList | height | numColumns | numRows | selectedColumn | selectionPolicy | showFind | singleSelectionCallback | sortFunctions | title | width | Specifying Children Resources | Using the Resource Database | The Xm18RowInfo Structure | Translations and Actions | ButtonDown(type) | Motion() | ButtonUpOrLeave() | Callback Routines | Sort Function | Convenience Routines | XmExt18ListGetSelectedRows | XmCreateExtended18List | XmExt18ListUnselectAllItems | XmExt18ListUnselectItem | COPYRIGHT

Want to link to this manual page? Use this URL:

home | help