Provided by: libmotif-dev_2.3.8-2build1_amd64 bug

NAME

       XmExt18List - The Internationalized Extended List widget

SYNOPSIS

       #include <Xm/Ext18List.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 successful. 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
       visible, 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_
                                                                      SELECT
       showFind              boolean              boolean             True
       singleSelection       Callback             Callback            NULL
       sortFunctions         Function             Function            NULL
       title                 Title                String              name of
                                                                      widget
       width                 Dimension            Horizontal          Dimension

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

columnTitles

       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.

doubleClickCallback

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

entryData

       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.

findLabel

       The label to be shown on the find button.

firstColumn

       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.

firstColumnPixmaps

       This  resource  specifies  that the pixmap stored in the row info structure 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 referenced. If False, then the Xm18RowInfo data pixmap is never referenced.

firstRow

       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.

fontList

       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.

height

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

numColumns

numRows

       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
       widget. Care should be taken when modifying these  resources  to  ensure  that  the  other
       values have also been modified.

selectedColumn

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

selectionPolicy

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

showFind

       This boolean manages and unmanages the find button

singleSelectionCallback

       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.

sortFunctions

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

title

       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.

width

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

       pixmap         This is the pixmap displayed to the left of this row. If firstColumnPixmaps
                      is  True  then  this value is never referenced 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 Extended List widget; they exist solely for the
       convenience of the programmer.

Translations and Actions

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

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

ButtonUpOrLeave()

       Cleans up after ButtonDown() and Motion().

Callback Routines

       All  procedures  on  the  Extended  List's singleSelectionCallback and doubleClickCallback
       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, depending on whether the first argument is
                      less than, equal to, or greater than the second.

Convenience Routines


XmExt18ListGetSelectedRows

       Xm18RowInfo ** XmExt18ListGetSelectedRows (Widget w)

       w              extended list widget

       Use the XmExt18ListGetSelectedRows function to find the rows that currently  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
       selected.

XmCreateExtended18List

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

       parent         parent of the extended list widget to be                created
       name           name of the extended list widget to be                created
       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.

XmExt18ListUnselectAllItems

       void XmExt18ListUnselectAllItems( Widget w )

       w              the extended list widget to be modified

       Unselects all rows of the passed extended list widget and returns nothing.

XmExt18ListUnselectItem

       void XmExt18ListUnselectItem(Widget w, Xm18RowInfo *row_info)

       w              extended list widget
       row_info       pointer to the row which is to be                unselected.

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

COPYRIGHT

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

                                                                                   XxExt18LIst(3)