1XmFileSelectionBox(library call)              XmFileSelectionBox(library call)
2
3
4

NAME

6       XmFileSelectionBox — The FileSelectionBox widget class
7

SYNOPSIS

9       #include <Xm/FileSB.h>
10

DESCRIPTION

12       FileSelectionBox  traverses  through  directories,  views the files and
13       subdirectories in them, and then selects files.
14
15       A FileSelectionBox has five main areas:
16
17          ·  A text input field for displaying and editing  a  directory  mask
18             used to select the files to be displayed
19
20          ·  An  optional text input field for displaying and editing a filter
21             mask used to select the files to be displayed.
22
23          ·  A scrollable list of filenames
24
25          ·  A scrollable list of subdirectories
26
27          ·  A text input field for displaying and editing a filename
28
29          ·  A group of PushButtons, labeled OK,  Filter,  Cancel,  and  Help.
30             The  layout  direction of the buttons depends on the XmNlayoutDi‐
31             rection resource.
32
33       ####Additional children may be added to the FileSelectionBox after cre‐
34       ation.   FileSelectionBox inherits the layout functionality provided by
35       SelectionBox for any additional children.  To remove the list of  file‐
36       names,  the  list  of subdirectories, or both from the FileSelectionBox
37       after creation, unmanage the appropriate widgets and their labels.  The
38       list  and label widgets are obtained through a call to the XmFileSelec‐
39       tionBoxGetChild function.  To remove either the directory list  or  the
40       file  list,  unmanage  the  parent  of  the appropriate list widget and
41       unmanage the corresponding label.
42
43       The user can specify resources in a resource file for the automatically
44       created  widgets  and  gadgets  of FileSelectionBox. The following list
45       identifies the names of these widgets (or gadgets) and  the  associated
46       FileSelectionBox areas:
47
48       FilterLabel
49                 FilterText
50
51       Filter Text
52                 TextField
53
54       Directory List
55                 DirList
56
57       Directory List Label
58                 Dir
59
60       DirL      Label
61
62       DirText   TextField
63
64       The  directory  mask  is  a  string specifying the base directory to be
65       examined and a search pattern.  Ordinarily, the directory list displays
66       the subdirectories of the base directory, as well as the base directory
67       itself and its parent directory.  The file list ordinarily displays all
68       files and/or subdirectories in the base directory that match the search
69       pattern.
70
71       Optionally, the search pattern mask and the base directory can be  dis‐
72       played  in  two  separate text fields. This option is controlled by the
73       XmNpathMode resource. Using this alternate display does not change  the
74       meaning  of  resources that control the content of these fields: XmNdi‐
75       rectory, XmNdirMask, XmNpattern.
76
77       A procedure specified by the XmNqualifySearchDataProc resource extracts
78       the  base directory and search pattern from the directory mask.  If the
79       directory specification is empty,  the  current  working  directory  is
80       used.  If the search pattern is empty, a pattern that matches all files
81       is used.
82
83       An application can supply its own XmNqualifySearchDataProc as  well  as
84       its own procedures to search for subdirectories and files.  The default
85       XmNqualifySearchDataProc works as follows:  The  directory  mask  is  a
86       pathname  that  can  contain  zero  or  more wildcard characters in its
87       directory portion, its file portion, or both.  The directory components
88       of  the  directory mask — up to, but not including, the first component
89       with a wildcard character — specify the directory to be searched, rela‐
90       tive  to the current working directory.  The remaining components spec‐
91       ify the search pattern.  If the directory mask is empty or if its first
92       component  contains a wildcard character, the current working directory
93       is searched.  If no component of the directory mask contains a wildcard
94       character,  the  entire  directory mask is the directory specification,
95       and all files in that directory are matched.
96
97       The user can select a new directory to examine by scrolling through the
98       list  of  directories and selecting the desired directory or by editing
99       the directory mask.  Selecting a new directory from the directory  list
100       does  not  change  the  search pattern.  A user can select a new search
101       pattern by editing the directory mask or, when the FileSelectionBox has
102       the  optional XmNpathMode XmPATH_MODE_RELATIVE display, the filter text
103       field.  Double clicking or pressing KActivate on  a  directory  in  the
104       directory  list  initiates a search for files and subdirectories in the
105       new directory, using the current search pattern.
106
107       The user can select a file by scrolling through the list  of  filenames
108       and  selecting  the  desired  file or by entering the filename directly
109       into the text edit area.  Selecting a file from the  list  causes  that
110       filename to appear in the file selection text edit area.
111
112       The  user may select a new file as many times as desired.  The applica‐
113       tion is not notified until the user takes one of the following actions:
114
115          ·  Selects the OK PushButton
116
117          ·  Presses KActivate while the selection text edit area has the key‐
118             board focus
119
120          ·  Double clicks or presses KActivate on an item in the file list
121
122       FileSelectionBox  initiates a directory and file search when any of the
123       following occurs:
124
125          ·  The FileSelectionBox is initialized
126
127          ·  The function XtSetValues is used to change XmNdirMask,  XmNdirec‐
128             tory, XmNpattern, or XmNfileTypeMask
129
130          ·  The user activates the Filter PushButton
131
132          ·  The  user  double  clicks  or presses KActivate on an item in the
133             directory list
134
135          ·  The application calls XmFileSelectionDoSearch
136
137          ·  The user presses KActivate while the  directory  mask  text  edit
138             area has the keyboard focus
139
140       When a file search is initiated, the FileSelectionBox takes the follow‐
141       ing actions:
142
143          ·  Constructs  an  XmFileSelectionBoxCallbackStruct  structure  with
144             values appropriate for the action that initiated the search
145
146          ·  Calls the XmNqualifySearchDataProc with the callback structure as
147             the data input argument
148
149          ·  Sets XmNdirectoryValid and XmNlistUpdated to False
150
151          ·  Calls the XmNdirSearchProc with the qualified  data  returned  by
152             the XmNqualifySearchDataProc
153
154       If  XmNdirectoryValid is True, the FileSelectionBox takes the following
155       additional actions:
156
157          ·  Sets XmNlistUpdated to False
158
159          ·  Calls the XmNfileSearchProc with the qualified data  returned  by
160             the   XmNqualifySearchDataProc  (and  possibly  modified  by  the
161             XmNdirSearchProc)
162
163          ·  If XmNlistUpdated is True and the file list  is  empty,  displays
164             the  XmNnoMatchString  in  the file list and clears the selection
165             text and XmNdirSpec
166
167          ·  If XmNlistUpdated is True and the file list is  not  empty,  sets
168             the  selection  text and XmNdirSpec to the qualified dir returned
169             by the XmNqualifySearchDataProc (and  possibly  modified  by  the
170             XmNdirSearchProc)
171
172          ·  Sets the directory mask text and XmNdirMask to the qualified mask
173             returned by the XmNqualifySearchDataProc (and  possibly  modified
174             by the XmNdirSearchProc)
175
176          ·  Sets  XmNdirectory to the qualified dir returned by the XmNquali‐
177             fySearchDataProc (and possibly modified by the XmNdirSearchProc)
178
179          ·  Sets XmNpattern to the qualified pattern returned by the XmNqual‐
180             ifySearchDataProc (and possibly modified by the XmNdirSearchProc)
181
182       FileSelectionBox uses the XmQTactivatable trait.
183
184   Data Transfer Behavior
185       Child  widgets  of  a FileSelectionBox support the data transfer opera‐
186       tions and targets associated with their widget classes.
187
188       In addition, if the source of a data transfer is the directory list and
189       if  XmNdirSearchProc has its default value, the directory list supports
190       the FILE and FILE_NAME targets.
191
192       If the source of a data transfer is the file list and if XmNfileSearch‐
193       Proc  has  its  default  value,  the  file  list  supports the FILE and
194       FILE_NAME targets.
195
196       In either case, FileSelectionBox adds an  XmNconvertCallback  procedure
197       to the appropriate list.  This procedure adds FILE and FILE_NAME to the
198       TARGETS returned by the list.  It treats requests for conversion  of  a
199       selection to FILE and FILE_NAME exactly like requests for conversion to
200       TEXT.
201
202       If an application changes  XmNdirSearchProc  or  XmNfileSearchProc  and
203       wants  to  support  the FILE and FILE_NAME targets on the corresponding
204       list, it must provide support itself  by  adding  a  procedure  to  the
205       list's XmNconvertCallback list.
206
207   Descendants
208       FileSelectionBox  automatically  creates  the  descendants shown in the
209       following table.  An application can use XtNameToWidget to gain  access
210       to  the named descendant. In addition, a user or an application can use
211       the named descendant when specifying resource values.
212
213       ┌─────────────────┬───────────────────────┬────────────────────────────────────┐
214Named Descendant Class                 Identity                           
215       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
216       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
217       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
218Apply            XmPushButtonGadget    │ Apply button                       │
219       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
220Cancel           XmPushButtonGadget    │ Cancel button                      │
221       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
222Dir              XmLabelGadget         │ title above list of directories    │
223       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
224DirList          XmList                │ list of directories                │
225       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
226DirListSW        XmScrolledWindow      │ ScrolledWindow parent of DirList   
227       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
228FilterLabel      XmLabelGadget         │ title above filter box             │
229       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
230FilterText       XmText or XmTextField │ text within filter box             │
231       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
232Help             XmPushButtonGadget    │ Help button                        │
233       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
234Items            XmLabelGadget         │ title above list of filenames      │
235       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
236ItemsList        XmList                │ list of filenames                  │
237       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
238ItemsListSW      XmScrolledWindow      │ ScrolledWindow parent of ItemsList 
239       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
240OK               XmPushButtonGadget    │ OK button                          │
241       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
242Selection        XmLabelGadget         │ title above selection box          │
243       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
244Separator        XmSeparatorGadget     │ optional dividing line             │
245       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
246Text             XmText or XmTextField │ text within selection box          │
247       ├─────────────────┼───────────────────────┼────────────────────────────────────┤
248       └─────────────────┴───────────────────────┴────────────────────────────────────┘
249   Classes
250       FileSelectionBox inherits behavior, resources, and  traits  from  Core,
251       Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.
252
253       The class pointer is xmFileSelectionBoxWidgetClass.
254
255       The class name is XmFileSelectionBox.
256
257   New Resources
258       The  following table defines a set of widget resources used by the pro‐
259       grammer to specify data. The programmer can also set the resource  val‐
260       ues  for  the  inherited  classes to set attributes for this widget. To
261       reference a resource by name or by class in a .Xdefaults  file,  remove
262       the  XmN or XmC prefix and use the remaining letters. To specify one of
263       the defined values for a resource in a .Xdefaults file, remove  the  Xm
264       prefix and use the remaining letters (in either lowercase or uppercase,
265       but include any underscores between words).  The codes  in  the  access
266       column  indicate if the given resource can be set at creation time (C),
267       set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
268       not applicable (N/A).
269
270       ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
271       │                         │      XmFileSelectionBox R│esource Set     │                   │        │
272Name                     Class                    Type          Default           Access 
273       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
274       │XmNdirectory             │ XmCDirectory             │ XmString      │ dynamic           │ CSG    │
275       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
276       │XmNdirectoryValid        │ XmCDirectoryValid        │ Boolean       │ dynamic           │ SG     │
277       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
278       │XmNdirListItems          │ XmCDirListItems          │ XmStringTable │ dynamic           │ SG     │
279       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
280       │XmNdirListItemCount      │ XmCDirListItemCount      │ int           │ dynamic           │ SG     │
281       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
282       │XmNdirListLabelString    │ XmCDirListLabelString    │ XmString      │ dynamic           │ CSG    │
283       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
284       │XmNdirMask               │ XmCDirMask               │ XmString      │ dynamic           │ CSG    │
285       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
286       │XmNdirSearchProc         │ XmCDirSearchProc         │ XmSearchProc  │ default procedure │ CSG    │
287       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
288       │XmNdirSpec               │ XmCDirSpec               │ XmString      │ dynamic           │ CSG    │
289       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
290       │XmNdirTextLabelString    │ XmCDirTextLabelString    │ XmString      │ NULL              │ C      │
291       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
292       │XmNfileFilterStyle       │ XmCFileFilterStyle       │ XtEnum        │ XmFILTER_NONE     │ C      │
293       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
294       │XmNfileListItems         │ XmCItems                 │ XmStringTable │ dynamic           │ SG     │
295       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
296       │XmNfileListItemCount     │ XmCItemCount             │ int           │ dynamic           │ SG     │
297       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
298       │XmNfileListLabelString   │ XmCFileListLabelString   │ XmString      │ dynamic           │ CSG    │
299       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
300       │XmNfileSearchProc        │ XmCFileSearchProc        │ XmSearchProc  │ default procedure │ CSG    │
301       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
302       │XmNfileTypeMask          │ XmCFileTypeMask          │ unsigned char │ XmFILE_REGULAR    │ CSG    │
303       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
304       │XmNfilterLabelString     │ XmCFilterLabelString     │ XmString      │ dynamic           │ CSG    │
305       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
306       │XmNlistUpdated           │ XmCListUpdated           │ Boolean       │ dynamic           │ SG     │
307       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
308       │XmNnoMatchString         │ XmCNoMatchString         │ XmString      │ " [    ] "        │ CSG    │
309       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
310       │XmNpathMode              │ XmCPathMode              │ XtEnum        │ XmPATH_MODE_FULL  │ C      │
311       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
312       │XmNpattern               │ XmCPattern               │ XmString      │ dynamic           │ CSG    │
313       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
314       │XmNqualifySearchDataProc │ XmCQualifySearchDataProc │ XmQualifyProc │ default procedure │ CSG    │
315       ├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
316       └─────────────────────────┴──────────────────────────┴───────────────┴───────────────────┴────────┘
317       XmNdirectory
318                 Specifies the base directory used in combination with XmNpat‐
319                 tern in determining the files  and  directories  to  be  dis‐
320                 played.   The  default value is determined by the XmNqualify‐
321                 SearchDataProc  and  depends  on  the   initial   values   of
322                 XmNdirMask,  XmNdirectory, and XmNpattern.  If the default is
323                 NULL or empty, the current working directory is used.
324
325       XmNdirectoryValid
326                 Specifies an attribute that is  set  only  by  the  directory
327                 search  procedure.  The value is set to True if the directory
328                 passed to the directory  search  procedure  can  actually  be
329                 searched.   If  this value is False the file search procedure
330                 is not called, and XmNdirMask, XmNdirectory,  and  XmNpattern
331                 are not changed.
332
333       XmNdirListItems
334                 Specifies  the  items in the directory list.  XtGetValues for
335                 this resource returns the list items themselves, not  a  copy
336                 of  the  list  items.   The  application  must  not  free the
337                 returned items.
338
339       XmNdirListItemCount
340                 Specifies the number of items in  the  directory  list.   The
341                 value must not be negative.
342
343       XmNdirListLabelString
344                 Specifies  the  label  string  of  the  directory  list.  The
345                 default for this resource depends on the locale.   In  the  C
346                 locale the default is Directories.
347
348                 Now  that  some  default localized label strings are provided
349                 through message catalogs for the children of  composite  wid‐
350                 gets,  the  labelString  resources cannot be set on the child
351                 through default resource files.  Instead, the  resource  pro‐
352                 vided at the parent level must be used.
353
354       XmNdirMask
355                 Specifies  the  directory  mask used in determining the files
356                 and directories to be displayed.  The default value is deter‐
357                 mined by the XmNqualifySearchDataProc and depends on the ini‐
358                 tial values of XmNdirMask, XmNdirectory, and XmNpattern.
359
360       XmNdirSearchProc
361                 Specifies a directory search procedure to replace the default
362                 directory   search   procedure.   FileSelectionBox's  default
363                 directory search procedure fulfills the needs of most  appli‐
364                 cations.   Because it is impossible to cover the requirements
365                 of all applications, you can replace the default search  pro‐
366                 cedure.
367
368                 The  directory search procedure is called with two arguments:
369                 the FileSelectionBox widget and a pointer to an  XmFileSelec‐
370                 tionBoxCallbackStruct  structure.   The callback structure is
371                 generated by the XmNqualifySearchDataProc  and  contains  all
372                 information required to conduct a directory search, including
373                 the directory mask and a qualified base directory and  search
374                 pattern.  Once called, it is up to the search routine to gen‐
375                 erate a new list of directories and update the FileSelection‐
376                 Box widget by using XtSetValues.
377
378                 The  search  procedure must set XmNdirectoryValid and XmNlis‐
379                 tUpdated.  If it generates a new list of directories, it must
380                 also set XmNdirListItems and XmNdirListItemCount.
381
382                 If  the  search  procedure cannot search the specified direc‐
383                 tory, it must warn the user  and  set  XmNdirectoryValid  and
384                 XmNlistUpdated  to  False, unless it prompts and subsequently
385                 obtains a valid directory.  If the directory is valid but  is
386                 the  same  as  the current XmNdirectory, the search procedure
387                 must set XmNdirectoryValid to True, but it may elect  not  to
388                 generate  a  new  list of directories.  In this case, it must
389                 set XmNlistUpdated to False.
390
391                 If the search procedure generates a new list of  directories,
392                 it  must  set  XmNdirListItems to the new list of directories
393                 and XmNdirListItemCount to the number of items in  the  list.
394                 If  there are no directories, it sets XmNdirListItems to NULL
395                 and XmNdirListItemCount to 0 (zero).  In either case, it must
396                 set XmNdirectoryValid and XmNlistUpdated to True.
397
398                 The  search  procedure ordinarily should not change the call‐
399                 back structure.  But if the original directory is not  valid,
400                 the  search  procedure  may  obtain  a new directory from the
401                 user.  In this case, it should set  the  dir  member  of  the
402                 callback structure to the new directory, call the XmNqualify‐
403                 SearchDataProc with the callback struct as  the  input  argu‐
404                 ment, and copy the qualified data returned by the XmNqualify‐
405                 SearchDataProc into the callback struct.
406
407       XmNdirSpec
408                 Specifies the full file path specification.  This is the XmN‐
409                 textString  resource  in SelectionBox, renamed for FileSelec‐
410                 tionBox.  The default value is determined by  the  FileSelec‐
411                 tionBox  after  conducting  the  initial  directory  and file
412                 search.
413
414       XmNdirTextLabelString
415                 Uses the specified XmString as the label above the  TextField
416                 directory.  The  resource  takes  effect when the XmNpathMode
417                 resource has a value of XmPATH_MODE_RELATIVE. It  is  ignored
418                 when    the    XmNpathMode    resource   has   a   value   of
419                 XmPATH_MODE_FULL.
420
421                 Now that some default localized label  strings  are  provided
422                 through  message  catalogs for the children of composite wid‐
423                 gets, the labelString resources cannot be set  on  the  child
424                 through  default  resource files.  Instead, the resource pro‐
425                 vided at the parent level must be used.
426
427       XmNfileFilterStyle
428                 Specifies whether or not  the  "hidden"  files  (those  whose
429                 names  begin with . (period) in POSIX systems) will be listed
430                 in the file and directory scrolling lists (where the  default
431                 directory  search  procedure  is  used).  The possible values
432                 are:
433
434                 XmFILTER_NONE
435                           Does not filter hidden files.
436
437                 XmFILTER_HIDDEN_FILES
438                           Restricts the list of possible file names, such  as
439                           those beginning with . (period).
440
441       XmNfileListItems
442                 Specifies  the  items  in the file list.  This is the XmNlis‐
443                 tItems resource in SelectionBox, renamed  for  FileSelection‐
444                 Box.   XtGetValues  for  this resource returns the list items
445                 themselves, not a copy of the list  items.   The  application
446                 must not free the returned items.
447
448       XmNfileListItemCount
449                 Specifies  the number of items in the file list.  This is the
450                 XmNlistItemCount resource in SelectionBox, renamed for FileS‐
451                 electionBox.  The value must not be negative.
452
453       XmNfileListLabelString
454                 Specifies  the  label  string  of the file list.  This is the
455                 XmNlistLabelString  resource  in  SelectionBox,  renamed  for
456                 FileSelectionBox.   The  default for this resource depends on
457                 the locale.  In the C locale the default is Files.
458
459                 Now that some default localized label  strings  are  provided
460                 through  message  catalogs for the children of composite wid‐
461                 gets, the labelString resources cannot be set  on  the  child
462                 through  default  resource files.  Instead, the resource pro‐
463                 vided at the parent level must be used.
464
465       XmNfileSearchProc
466                 Specifies a file search procedure to replace the default file
467                 search  procedure.   FileSelectionBox's  default  file search
468                 procedure fulfills the needs of most  applications.   Because
469                 it  is  impossible  to cover the requirements of all applica‐
470                 tions, you can replace the default search procedure.
471
472                 The file search procedure is called with two  arguments:  the
473                 FileSelectionBox  widget and a pointer to an XmFileSelection‐
474                 BoxCallbackStruct structure.  The callback structure is  gen‐
475                 erated by the XmNqualifySearchDataProc (and possibly modified
476                 by  the  XmNdirSearchProc).   It  contains  all   information
477                 required  to  conduct  a file search, including the directory
478                 mask and a qualified base directory and search pattern.  Once
479                 this  procedure  is called, it is up to the search routine to
480                 generate a new list of files and update the  FileSelectionBox
481                 widget by using XtSetValues.
482
483                 The  search  procedure must set XmNlistUpdated.  If it gener‐
484                 ates a new list of files, it must also  set  XmNfileListItems
485                 and XmNfileListItemCount.
486
487                 It is recommended that the search procedure always generate a
488                 new list of files.  If the mask member of the callback struc‐
489                 ture is the same as the mask member of the callback struct in
490                 the preceding call to the search procedure, the procedure may
491                 elect  not  to generate a new list of files.  In this case it
492                 must set XmNlistUpdated to False.
493
494                 If the search procedure generates a new  list  of  files,  it
495                 must  set  XmNfileListItems to the new list of files and XmN‐
496                 fileListItemCount to the number of items  in  the  list.   If
497                 there are no files, it sets XmNfileListItems to NULL and XmN‐
498                 fileListItemCount to 0 (zero).  In either case  it  must  set
499                 XmNlistUpdated to True.
500
501                 In  constructing  the  list  of  files,  the search procedure
502                 should include only files of the types specified by the  wid‐
503                 get's XmNfileTypeMask.
504
505                 Setting  XmNdirSpec  is  optional, but recommended.  Set this
506                 attribute to the full file  specification  of  the  directory
507                 searched.  The directory specification is displayed below the
508                 directory and file lists.
509
510       XmNfileTypeMask
511                 Specifies the type of files listed in  the  file  list.   The
512                 possible values are
513
514                 XmFILE_REGULAR
515                           Restricts  the  file  list  to contain only regular
516                           files.
517
518                 XmFILE_DIRECTORY
519                           Restricts the file list to  contain  only  directo‐
520                           ries.
521
522                 XmFILE_ANY_TYPE
523                           Allows the list to contain all file types including
524                           directories.
525
526       XmNfilterLabelString
527                 Specifies the label string for the text entry field  for  the
528                 directory mask.  The default for this resource depends on the
529                 locale.  In the C locale the default is Filter.
530
531                 Now that some default localized label  strings  are  provided
532                 through  message  catalogs for the children of composite wid‐
533                 gets, the labelString resources cannot be set  on  the  child
534                 through  default  resource files.  Instead, the resource pro‐
535                 vided at the parent level must be used.
536
537       XmNlistUpdated
538                 Specifies an attribute that is set only by the directory  and
539                 file  search procedures.  This resource is set to True if the
540                 search procedure updated the directory or file list.
541
542       XmNnoMatchString
543                 Specifies a string to be displayed in the file  list  if  the
544                 list of files is empty.
545
546       XmNpattern
547                 Specifies  the search pattern used in combination with XmNdi‐
548                 rectory in determining the files and directories to  be  dis‐
549                 played.  The default value is determined by XmNqualifySearch‐
550                 DataProc and depends on the  initial  values  of  XmNdirMask,
551                 XmNdirectory,  and  XmNpattern.   If  the  default is NULL or
552                 empty, a pattern that matches all files is used.
553
554       XmNpathMode
555                 Specifies whether or not an additional  text  field  will  be
556                 used to display and edit the filter. The possible values are
557
558                 XmPATH_MODE_FULL
559                           Specifies  that  no  additional  text field will be
560                           used to display the filter. There will  just  be  a
561                           single text field to display XmNdirMask.
562
563                 XmPATH_MODE_RELATIVE
564                           Specifies  that  there  will be two text field dis‐
565                           plays, one to display the XmNdirectory and  one  to
566                           display  the XmNpattern. In this instance, the XmN‐
567                           filterLabelString  resource  applies  to  the  text
568                           field   for  XmNpattern  and  XmNdirTextLabelString
569                           applies to the text field for XmNdirectory.
570
571       XmNqualifySearchDataProc
572                 Specifies a search data qualification  procedure  to  replace
573                 the default data qualification procedure.  FileSelectionBox's
574                 default data qualification procedure fulfills  the  needs  of
575                 most  applications.   Because  it  is impossible to cover the
576                 requirements of all applications, you can replace the default
577                 procedure.
578
579                 The  data  qualification  procedure  is  called to generate a
580                 qualified directory mask, base directory, and search  pattern
581                 for  use  by the directory and file search procedures.  It is
582                 called with three arguments: the FileSelectionBox widget  and
583                 pointers  to two XmFileSelectionBoxCallbackStruct structures.
584                 The first callback structure contains the  input  data.   The
585                 second  callback  structure  contains  the output data, to be
586                 filled in by the data qualification procedure.
587
588                 If the input dir and pattern members are not NULL, the proce‐
589                 dure  must copy them to the corresponding members of the out‐
590                 put callback structure.
591
592                 If the input dir is NULL, the procedure constructs the output
593                 dir  as follows: If the input mask member is NULL, the proce‐
594                 dure uses the widget's XmNdirectory as the output dir; other‐
595                 wise, it extracts the output dir from the input mask.  If the
596                 resulting output dir is empty, the procedure uses the current
597                 working directory instead.
598
599                 If  the  input  pattern is NULL, the procedure constructs the
600                 output pattern as follows: If the input mask member is  NULL,
601                 the procedure uses the widget's XmNpattern as the output pat‐
602                 tern; otherwise, it extracts  the  output  pattern  from  the
603                 input  mask.   If  the resulting output pattern is empty, the
604                 procedure uses a pattern that matches all files instead.
605
606                 The data qualification procedure constructs the  output  mask
607                 from  the  output dir and pattern.  The procedure must ensure
608                 that the output dir, pattern, and mask are fully qualified.
609
610                 If the input value member is not  NULL,  the  procedure  must
611                 copy  it to the output value member; otherwise, the procedure
612                 must copy the widget's XmNdirSpec to the output value.
613
614                 The data qualification procedure must calculate  the  lengths
615                 of  the output value, mask, dir, and pattern members and must
616                 fill in the corresponding length members of the output  call‐
617                 back struct.
618
619                 The  data  qualification procedure must copy the input reason
620                 and event members to the corresponding output members.
621
622       The values of the XmNdirSearchProc and XmNfileSearchProc are  procedure
623       pointers of type XmSearchProc, defined as follows:
624
625       void (* XmSearchProc) (w, search_data)
626               Widget w;
627               XtPointer search_data;
628
629       w         The FileSelectionBox widget
630
631       search_data
632                 Pointer  to  an  XmFileSelectionBoxCallbackStruct  containing
633                 information for conducting a search
634
635       The value of  the  XmNqualifySearchDataProc  resource  is  a  procedure
636       pointer of type XmQualifyProc, defined as follows:
637
638       void (* XmQualifyProc) (w, input_data, output_data)
639               Widget w;
640               XtPointer input_data;
641               XtPointer output_data;
642
643       w         The FileSelectionBox widget
644
645       input_data
646                 Pointer  to  an  XmFileSelectionBoxCallbackStruct  containing
647                 input data to be qualified
648
649       output_data
650                 Pointer  to  an  XmFileSelectionBoxCallbackStruct  containing
651                 output data to be filled in by the qualification procedure
652
653   Inherited Resources
654       FileSelectionBox  inherits behavior and resources from the superclasses
655       described in the following tables.  For a complete description of  each
656       resource, refer to the reference page for that superclass.
657
658       ┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
659       │                        │            XmSelectionBo│x Resource Set   │                         │        │
660Name                    Class                   Type           Default                 Access 
661       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
662       │XmNapplyCallback        │ XmCCallback             │ XtCallbackList │ NULL                    │ C      │
663       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
664       │XmNapplyLabelString     │ XmCApplyLabelString     │ XmString       │ dynamic                 │ CSG    │
665       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
666       │XmNcancelCallback       │ XmCCallback             │ XtCallbackList │ NULL                    │ C      │
667       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
668       │XmNcancelLabelString    │ XmCCancelLabelString    │ XmString       │ dynamic                 │ CSG    │
669       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
670       │XmNchildPlacement       │ XmCChildPlacement       │ unsigned char  │ XmPLACE_ABOVE_SELECTION │ CSG    │
671       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
672       │XmNdialogType           │ XmCDialogType           │ unsigned char  │ XmDIALOG_FILE_SELECTION │ G      │
673       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
674       │XmNhelpLabelString      │ XmCHelpLabelString      │ XmString       │ dynamic                 │ CSG    │
675       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
676       │XmNlistItemCount        │ XmCItemCount            │ int            │ dynamic                 │ CSG    │
677       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
678       │XmNlistItems            │ XmCItems                │ XmStringTable  │ dynamic                 │ CSG    │
679       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
680       │XmNlistLabelString      │ XmCListLabelString      │ XmString       │ dynamic                 │ CSG    │
681       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
682       │XmNlistVisibleItemCount │ XmCVisibleItemCount     │ int            │ dynamic                 │ CSG    │
683       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
684       │XmNminimizeButtons      │ XmCMinimizeButtons      │ Boolean        │ False                   │ CSG    │
685       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
686       │XmNmustMatch            │ XmCMustMatch            │ Boolean        │ False                   │ CSG    │
687       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
688       │XmNnoMatchCallback      │ XmCCallback             │ XtCallbackList │ NULL                    │ C      │
689       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
690       │XmNokCallback           │ XmCCallback             │ XtCallbackList │ NULL                    │ C      │
691       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
692       │XmNokLabelString        │ XmCOkLabelString        │ XmString       │ dynamic                 │ CSG    │
693       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
694       │XmNselectionLabelString │ XmCSelectionLabelString │ XmString       │ dynamic                 │ CSG    │
695       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
696       │XmNtextAccelerators     │ XmCTextAccelerators     │ XtAccelerators │ default                 │ C      │
697       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
698       │XmNtextColumns          │ XmCColumns              │ short          │ dynamic                 │ CSG    │
699       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
700       │XmNtextString           │ XmCTextString           │ XmString       │ dynamic                 │ CSG    │
701       ├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
702       └────────────────────────┴─────────────────────────┴────────────────┴─────────────────────────┴────────┘
703       ┌──────────────────────────────────────────────────────────────────────────────────────┐
704       │                     │      XmBulletinBoard │Resource Set     │               │        │
705Name                 Class                Type           Default       Access 
706       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
707       │XmNallowOverlap      │ XmCAllowOverlap      │ Boolean        │ True          │ CSG    │
708       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
709       │XmNautoUnmanage      │ XmCAutoUnmanage      │ Boolean        │ False         │ CG     │
710       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
711       │XmNbuttonFontList    │ XmCButtonFontList    │ XmFontList     │ dynamic       │ CSG    │
712       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
713       │XmNbuttonRenderTable │ XmCButtonRenderTable │ XmRenderTable  │ dynamic       │ CSG    │
714       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
715       │XmNcancelButton      │ XmCWidget            │ Widget         │ Cancel button │ SG     │
716       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
717       │XmNdefaultButton     │ XmCWidget            │ Widget         │ OK button     │ SG     │
718       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
719       │XmNdefaultPosition   │ XmCDefaultPosition   │ Boolean        │ True          │ CSG    │
720       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
721       │XmNdialogStyle       │ XmCDialogStyle       │ unsigned char  │ dynamic       │ CSG    │
722       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
723       │XmNdialogTitle       │ XmCDialogTitle       │ XmString       │ NULL          │ CSG    │
724       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
725       │XmNfocusCallback     │ XmCCallback          │ XtCallbackList │ NULL          │ C      │
726       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
727       │XmNlabelFontList     │ XmCLabelFontList     │ XmFontList     │ dynamic       │ CSG    │
728       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
729       │XmNlabelRenderTable  │ XmCLabelRenderTable  │ XmRenderTable  │ dynamic       │ CSG    │
730       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
731       │XmNmapCallback       │ XmCCallback          │ XtCallbackList │ NULL          │ C      │
732       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
733       │XmNmarginHeight      │ XmCMarginHeight      │ Dimension      │ 10            │ CSG    │
734       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
735       │XmNmarginWidth       │ XmCMarginWidth       │ Dimension      │ 10            │ CSG    │
736       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
737       │XmNnoResize          │ XmCNoResize          │ Boolean        │ False         │ CSG    │
738       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
739       │XmNresizePolicy      │ XmCResizePolicy      │ unsigned char  │ XmRESIZE_ANY  │ CSG    │
740       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
741       │XmNshadowType        │ XmCShadowType        │ unsigned char  │ XmSHADOW_OUT  │ CSG    │
742       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
743       │XmNtextFontList      │ XmCTextFontList      │ XmFontList     │ dynamic       │ CSG    │
744       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
745       │XmNtextRenderTable   │ XmCTextRenderTable   │ XmRenderTable  │ dynamic       │ CSG    │
746       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
747       │XmNtextTranslations  │ XmCTranslations      │ XtTranslations │ NULL          │ C      │
748       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
749       │XmNunmapCallback     │ XmCCallback          │ XtCallbackList │ NULL          │ C      │
750       ├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
751       └─────────────────────┴──────────────────────┴────────────────┴───────────────┴────────┘
752       ┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
753       │                        │             XmManager │Resource Set        │                      │        │
754Name                    Class                 Type              Default              Access 
755       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
756       │XmNbottomShadowColor    │ XmCBottomShadowColor  │ Pixel             │ dynamic              │ CSG    │
757       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
758       │XmNbottomShadowPixmap   │ XmCBottomShadowPixmap │ Pixmap            │ XmUNSPECIFIED_PIXMAP │ CSG    │
759       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
760       │XmNforeground           │ XmCForeground         │ Pixel             │ dynamic              │ CSG    │
761       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
762       │XmNhelpCallback         │ XmCCallback           │ XtCallbackList    │ NULL                 │ C      │
763       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
764       │XmNhighlightColor       │ XmCHighlightColor     │ Pixel             │ dynamic              │ CSG    │
765       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
766       │XmNhighlightPixmap      │ XmCHighlightPixmap    │ Pixmap            │ dynamic              │ CSG    │
767       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
768       │XmNinitialFocus         │ XmCInitialFocus       │ Widget            │ dynamic              │ CSG    │
769       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
770       │XmNlayoutDirection      │ XmCLayoutDirection    │ XmDirection       │ dynamic              │ CG     │
771       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
772       │XmNnavigationType       │ XmCNavigationType     │ XmNavigationType  │ XmTAB_GROUP          │ CSG    │
773       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
774       │XmNpopupHandlerCallback │ XmCCallback           │ XtCallbackList    │ NULL                 │ C      │
775       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
776       │XmNshadowThickness      │ XmCShadowThickness    │ Dimension         │ dynamic              │ CSG    │
777       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
778       │XmNstringDirection      │ XmCStringDirection    │ XmStringDirection │ dynamic              │ CG     │
779       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
780       │XmNtopShadowColor       │ XmCTopShadowColor     │ Pixel             │ dynamic              │ CSG    │
781       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
782       │XmNtopShadowPixmap      │ XmCTopShadowPixmap    │ Pixmap            │ dynamic              │ CSG    │
783       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
784       │XmNtraversalOn          │ XmCTraversalOn        │ Boolean           │ True                 │ CSG    │
785       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
786       │XmNunitType             │ XmCUnitType           │ unsigned char     │ dynamic              │ CSG    │
787       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
788       │XmNuserData             │ XmCUserData           │ XtPointer         │ NULL                 │ CSG    │
789       ├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
790       └────────────────────────┴───────────────────────┴───────────────────┴──────────────────────┴────────┘
791       ┌───────────────────────────────────────────────────────────────────────┐
792       │                  │     Composite Reso│urce Set      │         │        │
793Name              Class             Type        Default Access 
794       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
795       │XmNchildren       │ XmCReadOnly       │ WidgetList  │ NULL    │ G      │
796       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
797       │XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL    │ CSG    │
798       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
799       │XmNnumChildren    │ XmCReadOnly       │ Cardinal    │ 0       │ G      │
800       ├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
801       └──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
802       ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
803       │                              │               Core Resource Se│t                │                      │        │
804Name                          Class                         Type           Default              Access 
805       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
806       │XmNaccelerators               │ XmCAccelerators               │ XtAccelerators │ dynamic              │ N/A    │
807       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
808       │XmNancestorSensitive          │ XmCSensitive                  │ Boolean        │ dynamic              │ G      │
809       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
810       │XmNbackground                 │ XmCBackground                 │ Pixel          │ dynamic              │ CSG    │
811       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
812       │XmNbackgroundPixmap           │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
813       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
814       │XmNborderColor                │ XmCBorderColor                │ Pixel          │ XtDefaultForeground  │ CSG    │
815       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
816       │XmNborderPixmap               │ XmCPixmap                     │ Pixmap         │ XmUNSPECIFIED_PIXMAP │ CSG    │
817       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
818       │XmNborderWidth                │ XmCBorderWidth                │ Dimension      │ 0                    │ CSG    │
819       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
820       │XmNcolormap                   │ XmCColormap                   │ Colormap       │ dynamic              │ CG     │
821       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
822       │XmNdepth                      │ XmCDepth                      │ int            │ dynamic              │ CG     │
823       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
824       │XmNdestroyCallback            │ XmCCallback                   │ XtCallbackList │ NULL                 │ C      │
825       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
826       │XmNheight                     │ XmCHeight                     │ Dimension      │ dynamic              │ CSG    │
827       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
828       │XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean        │ True                 │ C      │
829       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
830       │XmNmappedWhenManaged          │ XmCMappedWhenManaged          │ Boolean        │ True                 │ CSG    │
831       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
832       │XmNscreen                     │ XmCScreen                     │ Screen *       │ dynamic              │ CG     │
833       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
834       │XmNsensitive                  │ XmCSensitive                  │ Boolean        │ True                 │ CSG    │
835       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
836       │XmNtranslations               │ XmCTranslations               │ XtTranslations │ dynamic              │ CSG    │
837       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
838       │XmNwidth                      │ XmCWidth                      │ Dimension      │ dynamic              │ CSG    │
839       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
840       │XmNx                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
841       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
842       │XmNy                          │ XmCPosition                   │ Position       │ 0                    │ CSG    │
843       ├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
844       └──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
845   Callback Information
846       A pointer to the following structure is passed to each callback:
847
848       typedef struct
849       {
850               int reason;
851               XEvent * event;
852               XmString value;
853               int length;
854               XmString mask;
855               int mask_length;
856               XmString dir;
857               int dir_length;
858               XmString pattern;
859               int pattern_length;
860       } XmFileSelectionBoxCallbackStruct;
861
862       reason    Indicates why the callback was invoked
863
864       event     Points to the XEvent that triggered the callback
865
866       value     Specifies the current value of XmNdirSpec
867
868       length    Specifies  the  number of bytes in value This member is obso‐
869                 lete and exists for compatibility with earlier releases.
870
871       mask      Specifies the current value of XmNdirMask
872
873       mask_length
874                 Specifies the number of bytes in mask This member is obsolete
875                 and exists for compatibility with earlier releases.
876
877       dir       Specifies the current base directory
878
879       dir_length
880                 Specifies  the number of bytes in dir This member is obsolete
881                 and exists for compatibility with earlier releases.
882
883       pattern   Specifies the current search pattern
884
885       pattern_length
886                 Specifies the number of bytes in pattern This member is obso‐
887                 lete and exists for compatibility with earlier releases.
888
889   Translations
890       XmFileSelectionBox inherits translations from XmSelectionBox.
891
892   Accelerators
893       The  XmNtextAccelerators from XmSelectionBox are added to the selection
894       and directory mask (filter) Text descendants of XmFileSelectionBox.
895
896   Action Routines
897       The XmFileSelectionBox action routines are
898
899       SelectionBoxUpOrDown(Previous|Next|First|Last):
900                 If neither the selection text nor the directory mask (filter)
901                 text has the focus, this action does nothing.
902
903                 If  the  selection  text  has the focus, the term list in the
904                 following description refers to the file list, and  the  term
905                 text  refers  to  the  selection text.  If the directory mask
906                 text has the focus, list refers to the  directory  list,  and
907                 text refers to the directory mask text.
908
909                 When  called  with  an  argument of Previous, or 0 (zero) for
910                 compatibility, this action selects the previous item  in  the
911                 list and replaces the text with that item.
912
913                 When called with an argument of Next, or 1 for compatibility,
914                 this action selects the next item in the  list  and  replaces
915                 the text with that item.
916
917                 When  called  with an argument of First, or 2 for compatibil‐
918                 ity, this action selects the  first  item  in  the  list  and
919                 replaces the text with that item.
920
921                 When called with an argument of Last, or 3 for compatibility,
922                 this action selects the last item in the  list  and  replaces
923                 the text with that item.
924
925       SelectionBoxRestore():
926                 If neither the selection text nor the directory mask (filter)
927                 text has the focus, this action does nothing.
928
929                 If the selection text has the focus, this action replaces the
930                 selection  text  with the selected item in the file list.  If
931                 no item in the file list is selected, it clears the selection
932                 text.
933
934                 If  the  directory  mask  text  has  the  focus,  this action
935                 replaces the directory mask text with a  new  directory  mask
936                 constructed from the XmNdirectory and XmNpattern resources.
937
938   Additional Behavior
939       The FileSelectionBox widget has the following additional behavior:
940
941       <Key><osfCancel>:
942                 Calls  the  activate callbacks for the cancel button if it is
943                 sensitive.  If no cancel button exists and the parent of  the
944                 FileSelectionBox  is  a  manager,  it passes the event to the
945                 parent.
946
947       <Key><osfActivate> in Selection Text:
948                 Calls the selection text widget's  XmNactivateCallback  call‐
949                 backs.   If  XmNmustMatch is True and the selection text does
950                 not match an item in the file list, it calls the  XmNnoMatch‐
951                 Callback  callbacks with reason XmCR_NO_MATCH.  Otherwise, it
952                 calls the XmNokCallback callbacks with reason XmCR_OK.
953
954       <Key><osfActivate> in Directory Mask Text:
955                 Calls the directory mask  text  widget's  XmNactivateCallback
956                 callbacks,  initiates  a directory and file search, and calls
957                 the XmNapplyCallback callbacks with reason XmCR_APPLY.
958
959       <Btn1Down>(2+) or <Key><osfActivate> in Directory List:
960                 Calls the directory  list  widget's  XmNdefaultActionCallback
961                 callbacks,  initiates  a directory and file search, and calls
962                 the XmNapplyCallback callbacks with reason XmCR_APPLY.
963
964       <Btn1Down>(2+) or <Key><osfActivate> in File List:
965                 Calls the file list widget's  XmNdefaultActionCallback  call‐
966                 backs  and  calls  the  XmNokCallback  callbacks  with reason
967                 XmCR_OK.
968
969       <Key><osfSelect> in Directory List:
970                 Generates a new directory mask, using the selected list  item
971                 as  the  directory and the pattern extracted from the current
972                 directory mask text as the search  pattern.   If  the  search
973                 pattern is empty, it uses a pattern that matches all files in
974                 the directory.  Replaces the directory mask text with the new
975                 directory mask.
976
977       <Key><osfSelect> in File List:
978                 Replaces the selection text with the selected list item.
979
980       <Btn2Down> in File List:
981                 Drags  the  content  of one or more selected list items using
982                 the drag and drop facility. If <Btn2Down  is  pressed  on  an
983                 unselected  item,  drags  only that item, excluding any other
984                 selected items.
985
986                 This action sets the XmNconvertProc of the DragContext  to  a
987                 function  that calls the XmNconvertCallback procedures of the
988                 file list,  possibly  multiple  times,  for  the  _MOTIF_DROP
989                 selection.
990
991       <Btn2Down> in Directory List:
992                 Drags  the  content  of one or more selected list items using
993                 the drag and drop facility. If <Btn2Down  is  pressed  on  an
994                 unselected item, it drags only that item, excluding any other
995                 selected items.
996
997                 This action sets the XmNconvertProc of the DragContext  to  a
998                 function  that calls the XmNconvertCallback procedures of the
999                 directory list, possibly multiple times, for the  _MOTIF_DROP
1000                 selection.
1001
1002       <Apply Button Activated>:
1003                 Initiates  a  directory and file search.  Calls the XmNapply‐
1004                 Callback callbacks with reason XmCR_APPLY.
1005
1006       <OK Button Activated>:
1007                 If XmNmustMatch is True and the selection text does not match
1008                 an  item in the file list, calls the XmNnoMatchCallback call‐
1009                 backs with reason XmCR_NO_MATCH.  Otherwise, calls the XmNok‐
1010                 Callback callbacks with reason XmCR_OK.
1011
1012       <Cancel Button Activated>:
1013                 Calls  the  XmNcancelCallback callbacks with reason XmCR_CAN‐
1014                 CEL.
1015
1016       <Help Button Activated>:
1017                 Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
1018
1019       <Key><osfActivate>:
1020                 If no button, list widget, or text widget  has  the  keyboard
1021                 focus,  if  XmNmustMatch  is True and the selection text does
1022                 not match an item in the file list, it calls the  XmNnoMatch‐
1023                 Callback  callbacks with reason XmCR_NO_MATCH.  Otherwise, it
1024                 calls the XmNokCallback callbacks with reason XmCR_OK.
1025
1026   Virtual Bindings
1027       The bindings for virtual keys are  vendor  specific.   For  information
1028       about bindings for virtual buttons and keys, see VirtualBindings(3).
1029
1031       Composite(3), Constraint(3), Core(3), XmBulletinBoard(3), XmCreateFile‐
1032       SelectionBox(3),    XmCreateFileSelectionDialog(3),    XmFileSelection‐
1033       BoxGetChild(3),  XmFileSelectionDoSearch(3), XmManager(3), XmSelection‐
1034       Box(3) XmVaCreateFileSelectionBox(3),  and  XmVaCreateManagedFileSelec‐
1035       tionBox(3),.
1036
1037
1038
1039                                              XmFileSelectionBox(library call)
Impressum