Table of Contents

Name

FileSelector - A Hierarchical File Selector Widget

Synopsis

#include <X11/Intrinsic.h> #include <X11/FileSel.h>

widget = XtCreatePopupShell(name, fileSelectorWidgetClass, ...);

Class Hierarchy

Core-->Composite-->XfwfFileSelector

Description

XfwfFileSelector is a hierarchical file selector widget that allows a user to move through the directory tree and select files.

This widget can either be used as a stand-alone widget with it own OK and Cancel buttons, or as part of a larger widget. When used as part of a larger composite widget, the OK and Cancel buttons can be turned off and replaced by global ter­ mination buttons for the larger widget.

The File Selector has two scrolled text lists side by side. The left list contains the current directory path from the root to the current directory, listed one directory per line. The right list shows the files in the current direc­ tory that pass a user-specified filter function, and are sorted by a user specified sorting order. Files can be selected by typing them in by clicking on the appropriate file in the right list. Clicking on a directory will enter that directory and list its files and directories.

The source code in the Dir directory of the FWF distribution contains system-independent file listing functions that are required by FileSelector.

Resources

In addition to the resources defined by superclasses, this widget defines the following:
Name
Class Type Default
XtNwidth
Width Dimension 500
XtNheight
Height Dimension 250
XtNbackground
Background Pixel "white"
XtNokButtonCallback
Callback Callback NULL XtNcancelButtonCallback Callback Callback NULL XtNselectionChangeCallback Callback Callback NULL
XtNshowOkButton
Boolean Boolean True
XtNshowCancelButton
Boolean Boolean True
XtNflagLinks
Boolean Boolean False
XtNcheckExistence
Boolean Boolean True
XtNfileSelected
Boolean Boolean False

XtNcurrentDirectory
Pathname String NULL
XtNcurrentFile
Filename String NULL
XtNtitle
Label String "File Selector"
XtNsortMode
Value Int 2
XtNpattern
File String NULL

The XtNokButtonCallback, NcancelButtonCallback, and XtNse­ lectionChangeCallback callback resources are used to specify any functions to be called when the OK button is pressed, the Cancel button is pressed, or a new item is selected. The OK and Cancel buttons can be enabled or disabled by changing the XtNshowOkButton, and XtNshowCancelButton resources. The buttons are typically disabled when the file selector is included in a parent widget.

The XtNflagLinks resource allows symbolic links to be spe­ cially identified with an `@' sign after the file name. This identification is only done if XtNflagLinks is true.

The XtNcheckExistence resource determines whether file names have to exist before they can be selected. Typically this resource is set to True when searching for a file to read or modify, but set to False if the user should be able to enter new file names.

XtNfileSelected is a read only resource which indicates if a file is currently selected. XtNcurrentDirectory and XtNcur­ rentFile allow the current path and file name to be speci­ fied. The title of the file selector is specified via XtNtitle.

The filter pattern is specified in the string XtNpattern. The method used to sort the file list is specified in XtNsortMode. The sort mode is encoded as an integer. The integers are defined in the DirMgr.h file which is part of the libDir directory management package included in the FWF release. Sample XtNsortMode values are depicted below:

XtNsortMode Name
Value Sort By
DIR_MGR_SORT_NONE
0 No sorting
DIR_MGR_SORT_NAME
1 File name
DIR_MGR_SORT_NAME_DIRS_FIRST
2 File name, directories first
DIR_MGR_SORT_SIZE_ASCENDING
3 Ascending file size
DIR_MGR_SORT_SIZE_DESCENDING
4 Descending file size DIR_MGR_SORT_ACCESS_ASCENDING 5 Ascending access time DIR_MGR_SORT_ACCESS_DESCENDING 6 Descending access time

Callbacks

Three callbacks are supported by the FileSelector widget. The first two, okButtonCallback and cancelButtonCallback are called when the FileSelector OK or Cancel buttons are pressed. The final callback, selectionChangeCallback, occurs whenever the currently selected file changes, and can be used to update the sensitivity of user buttons, etc. The cancelButtonCallback returns no data. The other two call­ backs notify the user of data through the data structures described below:

typedef struct _XfwfFileSelectorOkButtonReturnStruct {
char *path;
char *file;
char *file_box_text;
} XfwfFileSelectorOkButtonReturnStruct;

typedef struct _XfwfFileSelectorSelectionChangeReturnStruct {
Boolean file_selected;
char *path;
char *file;
} XfwfFileSelectorSelectionChangeReturnStruct;

Public Functions

void XfwfFileSelectorChangeDirectory(fsw,dir) XfwfFileSelectorWidget fsw;
char *dir;

This routine changes the current directory of the File Selector widget <fsw> to be the directory <dir>.

void XfwfFileSelectorRefresh(fsw)
XfwfFileSelectorWidget fsw;

This routine causes the FileSelector widget to re-read the current directory, refreshing the widget. Changes to the file system will not automatically propogate to the widget. This routine forces the refresh.

void XfwfFileSelectorGetStatus(fsw,ssp)
XfwfFileSelectorWidget fsw;
XfwfFileSelectorStatusStruct *ssp;

This routine obtains current information form the File­ Selector widget pertaining to the selection state of the widget. The structure pointed to by <ssp> is filled in with the currently selected file and direc­ tory, as well as the current contents of the file box text. This routine allows status information to be queried from the widget at any time. The structure <ssp> which is passed into the routine is described below:

typedef struct _XfwfFileSelectorStatusStruct {
Boolean file_selected; char *path; char *file; char *file_box_text; } XfwfFileSelectorStatusStruct;

Restrictions

The filter function is currently limited to shell-style pat­ tern matching, even though the underlying directory managem­ net functions support arbitrary filter functions. The chil­ dren widgets of the FileSelector can not be configured by the user. The layout semantics of the widget are not always pretty. We should be able to add new buttons to the widget. Not all resources can be changed dynamically. The slider bars of the viewports do not "snap back" when a smaller directory is loaded, and the sliders are down at the bottom.

Author

Brian Totty, totty@cs.uiuc.edu
Department of Computer Science,
University of Illinois at Urbana-Champaign 1304 W. Springfield Avenue
Urbana, IL 61801


Table of Contents