1XxExt18LIst(3x)                                                XxExt18LIst(3x)
2
3
4

NAME

6       The Internationalized Extended List widget
7

SYNOPSIS

9       #include <Xm/Ext18List.h>
10

DESCRIPTION

12       This widget contains a multi-column list with headers along the top and
13       a search area along the bottom. The list has scrollbars along the right
14       and  bottom  edges that allow vertical and horizontal scrolling both by
15       column and by pixel. The portion of the list  data  that  is  currently
16       visible  can  be  altered by scrollbar actions, widget resource setting
17       and the redisplay of the list data after a string search has been  suc‐
18       cessful.  The  sorting  of  elements within a particular column is also
19       supported. To sort the list by the elements in a given  column,  select
20       the column's title.
21
22       To search for a particular string in the list, type the string value to
23       be searched for in the list's associated text field and then press  the
24       "Find"  pushbutton.  The  search for the string begins in the currently
25       selected row, after the location of the previously searched for string,
26       or  at  the  first column and first row if there is no column selected.
27       If the string is not found in  that  row,  then  the  search  continues
28       through  all rows after and then before, the currently selected row. If
29       the string is found, the display of the list is adjusted  to  make  the
30       string  visible. If the string was not found, or if the string is visi‐
31       ble, the application will issue a warning beep.
32
33       Pointer button one allows the user to select a  row  or  a  column  for
34       sorting.  The callbacks on the doubleClickCallback list are called when
35       the user double clicks pointer button one. If the list data can contain
36       a row pixmap to display at the extreme left of the row.
37

Normal Resources

39       Name                  Class                Type                Default
40       columnTitles          ColumnTitles         String *            NULL
41       doubleClickCallback   Callback             Callback            NULL
42       entryData             EntryData            Xm18RowInfo*        NULL
43       findLabel             XmString             XmString            Find
44       firstColumn           FirstLocation        short               0
45       firstColumnPixmaps    FirstColumnPixmaps   Boolean             False
46       firstRow              FirstLocation        short               0
47       fontList              FontList             FontList            "fixed"
48       height                Dimension            VerticalDimension   300
49       numColumns            NumColumns           short               0
50       numRows               NumRows              short               0
51       selectedColumn        SelectedColumn       short               0
52       selectionPolicy       SelectionPolicy      SelectionPolicy     XmEXTENDED_
53                                                                      SELECT
54       showFind              boolean              boolean             True
55       singleSelection       Callback             Callback            NULL
56       sortFunctions         Function             Function            NULL
57       title                 Title                String              name of
58                                                                      widget
59       width                 Dimension            Horizontal          Dimension
60
61       All  resource  names  begin with XmN and all resource class names begin
62       with XmC.
63

columnTitles

65       This is an array of length numColumns of strings displayed at  the  top
66       of each column. The data is allocated and maintained by the client.
67

doubleClickCallback

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

entryData

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

findLabel

79       The label to be shown on the find button.
80

firstColumn

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

firstColumnPixmaps

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

firstRow

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

fontList

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

height

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

numColumns

numRows

109       These resources specify the number  of  columns  and  rows  the  widget
110       expects to display. These resources are used as the maximum indices for
111       many of the other resources in this widget. Care should be  taken  when
112       modifying  these  resources  to  ensure that the other values have also
113       been modified.
114

selectedColumn

116       This is the index of the currently selected column. This also the  col‐
117       umn by which the list is being sorted.
118

selectionPolicy

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

showFind

125       This boolean manages and unmanages the find button
126

singleSelectionCallback

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

sortFunctions

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

title

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

width

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

Specifying Children Resources

146       The  Extended  List widget is composed of many simple widgets. In order
147       to achieve full functionality of the Toolkit, it is sometimes desirable
148       to  set  attribute  values directly on those widgets. The widget ids of
149       the sub-widgets can be obtained by using the XtNameToWidget()  function
150       provided by the Xt Intrinsics.
151
152       XmExt18List <named by application>
153
154            XmLabel title
155
156            XmScrollbar vertBar
157
158            XmScrollBar horizBar
159
160            XmFrame frame
161
162            XmPushButton find
163
164            XmText findText
165
166

Using the Resource Database

168       The  Extended  List  widget is actually a collection of pieces. It pro‐
169       vides the geometry layout for the collection as well as tying  together
170       the  pieces  to  form a consistent package.  Many of the resources that
171       are documented as being part of the Extended  List  widget  are  really
172       part  of the internal list sub-component. The Extended List widget will
173       pass these values through to the proper child when they are set at time
174       of creation or with XtSetValues or XtGetValues. However, when setting a
175       resource via the resource database you must use either the name of  the
176       child  or  the  general  specification (*) rather than the specific one
177       (.).
178

The Xm18RowInfo Structure

180       The Xm18RowInfo structure is used to contain the  entryData  associated
181       with each Row in the Extended List.
182
183       typedef struct _Xm18RowInfo{
184
185       /*
186
187        * Used by the IList widget
188
189        */
190
191            String * values;/* The array of column strings */
192
193            Pixmap pixmap;/* mini-icon pixmaps. */
194
195            Boolean selected;/* row selected. */
196
197            /*
198
199             * Provided for the convenience of the application programmer
200
201             */
202
203            short * sort_id;
204
205            XtPointer data;
206
207            /*
208
209             * Private to the Extended List widget (do not modify these)
210
211             */
212
213            short pix_width;/* of the pixmap. */
214
215            short pix_height;/* of the pixmap. */
216
217            short pix_depth;/* of the pixmap. */
218
219            Boolean old_sel_state;
220
221       } Xm18RowInfo;
222
223
224       values         This  is  an array of strings of length numColumns which
225                      represents the strings displayed in each column of  this
226                      row. The data is allocated and maintained by the client.
227                      If firstColumnPixmaps is True, then  value[0]  is  never
228                      referenced.
229
230       pixmap         This is the pixmap displayed to the left of this row. If
231                      firstColumnPixmaps is True then this value is never ref‐
232                      erenced  and  mayn remain unset. If no pixmap is desired
233                      for this row, even though  firstColumnPixmaps  is  True,
234                      set  the  value  of pixmap to None. Color pixmaps may be
235                      used.
236
237       sort_id        This is provided for the convenience of the  client  and
238                      is expected to be used as a sort index for this row. One
239                      value should be specified for each column  of  the  row.
240                      See "sortFunctions" below for details.
241
242       data           This  is  provided for the convenience of the client and
243                      may be used for any purpose. It is intended to  be  used
244                      as an identifier for the object pointed to by this row
245
246       selected       This  value  is True if this row is selected; may be set
247                      by the application.
248
249       Neither sort_id nor data are used by the  Extended  List  widget;  they
250       exist solely for the convenience of the programmer.
251

Translations and Actions

253       The  following  are  the  default translation bindings used by the icon
254       button:
255
256       ~Ctrl ~Shift <Btn1Down>:   ButtonDown()
257       Ctrl ~Shift <Btn1Down>:    ButtonDown(Toggle)
258       ~Ctrl Shift <Btn1Down>:    ButtonDown(Extend)
259       Button1 <Motion>:          Motion()
260       <Btn1Up>:                  ButtonUpOrLeave()
261
262       The following actions are supported by the icon button:
263

ButtonDown(type)

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

Motion()

271       Processes  motion  events  to allow the selection region to be modified
272       when in extended selection mode. It is  assumed  that  this  action  is
273       called between a ButtonDown() and ButtonUpOrLeave() action.
274

ButtonUpOrLeave()

276       Cleans up after ButtonDown() and Motion().
277

Callback Routines

279       All  procedures on the Extended List's singleSelectionCallback and dou‐
280       bleClickCallback lists will have a pointer to a  Xm18RowInfo  structure
281       passed to them in the call_data field. This structure is defined above.
282
283       Note:  if  a single SelectionCallback is registered on an extended list
284       in extended_se- lect_mode, the value of call_data is undefined.
285
286
287       void (callback)(Widget w, XtPointer client_data, XtPointer call_data)
288
289       w              the Extended List widget
290
291       client_data    the client data specified by the application
292
293       call_data      a pointer to an Xm18RowInfo structure  corrsponding  the
294                      the row selected
295
296

Sort Function

298       typedef  int  (Xm18SortFunction)  (short  column,  Xm18RowInfo  * row1,
299                           Xm18RowInfo * row2);
300
301       column         the column currently being sorted
302
303       row1, row2     the two rows being compared. The return value must be an
304                      integer  less than, equal to, or greater than 0, depend‐
305                      ing on whether the first argument is  less  than,  equal
306                      to, or greater than the second.
307
308

Convenience Routines

310
311
312
313

XmExt18ListGetSelectedRows

315       Xm18RowInfo ** XmExt18ListGetSelectedRows (Widget w)
316
317       w              extended list widget
318
319       Use  the XmExt18ListGetSelectedRows function to find the rows that cur‐
320       rently are selected in an extended list. The Xm18RowInfo ** returned by
321       this function contains a NULL terminated array of Xm18RowInfo pointers.
322       The calling routine is responsible for  freeing  the  returned  pointer
323       with  XtFree().  The  function  will  return  NULL  if  no elements are
324       selected.
325

XmCreateExtended18List

327       Widget    XmCreateExtended18List(Widget    parent,     String     name,
328                            ArgList args, Cardinal num_args)
329
330       parent         parent    of    the   extended   list   widget   to   be
331                      created
332       name           name   of   the   extended    list    widget    to    be
333                      created
334       args           arguments    to   pass   to   XtCreateWidget   for   the
335                      extended list
336       num_args       number of arguments passed
337
338       This convenience routine simply takes the passed parameters  and  calls
339       XtCreateWidget, returning the widget created.
340

XmExt18ListUnselectAllItems

342       void XmExt18ListUnselectAllItems( Widget w )
343
344       w              the extended list widget to be modified
345
346       Unselects all rows of the passed extended list widget and returns noth‐
347       ing.
348

XmExt18ListUnselectItem

350       void XmExt18ListUnselectItem(Widget w, Xm18RowInfo *row_info)
351
352       w              extended list widget
353       row_info       pointer to the row which is to  be                 unse‐
354       lected.
355
356       Unselects  the  row  designated by row_info of the passed extended list
357       widget w
358
360       Copyright (c) 1992 by Integrated Computer Solutions, Inc.
361
362
363
364                                                               XxExt18LIst(3x)
Impressum