manpagez: man pages & more
man XmMultiList(3)
Home | html | info | man
XmMultiList(3)                                                XmMultiList(3)




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
                 resource  is  True,  then  values[0]  is never referenced. If
                 False, then the XmMultiListRowInfo data pixmap is never  ref-
                 erenced.

       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
                 resource   can  have  the  values  XmSINGLE_SELECT  or  XmEX-
                 TENDED_SELECT. 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 Set                |                      |        |
       |Name                          | 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
       defined 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
                 integer 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(3)

openMotif 2.3.1 - Generated Mon Dec 1 19:52:30 CST 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.