FileChooser(3)

Name
FileChooser - Another widget for choosing a file

Synopsis
#include <Xfwf/FChooser.h>
widget = XtCreateManagedWidget(name, xfwfFileChooserWidgetClass, ...);

Class Hierarchy
The following describes the classes from which XfwfFileChooser inherits resources:
Core-->Composite-->XfwfFileChooser

Widget Hierarchy

The XfwfFileChooser widget is a composite widget with the following internal structure:
    MenuButton dirMenuButton
    SimpleMenu dirMenu
    Viewport fileViewport
        List fileList
You can use these names to specify resources for FileChooser children, or use XtNameToWidget() to locate them programmatically.

Description
XfwfFileChooser provides a list of files in the current directory, and a dynamically-updated menu of ancestor directories. A file can be selected from the list, or a directory can be selected from either the list (a sub-directory) or the menu (an ancestor directory). When a directory is selected (from the menu or the list), the list is re-filled with the contents of the new directory. Callback procedures are called whenever the selected file or directory changes.

This widget is meant to function within, say, a Form, which would provide buttons and perhaps a Text item for entering new filenames. In this sense, it is different from the XfwfFileSelector widget that provides builtin additional functionality but at the cost of more screen real estate and some inflexibility in terms of input policy. The sample program distributed with the widget presents an example of such usage.

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

Resources
In addition to the resources defined by superclasses, this widget defines the following:
Name | Class | Type | Default
XtNwidth | Width | Dimension | 250
XtNheight | Height | Dimension | 500
XtNbackground | Background | Pixel | XtDefaultBackground
XtNcallback | Callback | Callback | NULL
XtNcurrentDirectory | Pathname | String | current directory
XtNcurrentFile | Filename | String | NULL
XtNsortMode | Int | Int | 2
XtNpattern | Filename | String | NULL

The XtNcurrentDirectory and XtNcurrentFile resources can be used to specify the initial contents and selection of the XfwfFileChooser widget. Changing them after creation results in the contents being recomputed appropriately and the callbacks being invoked (see below).

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
    SORT_NONE | 0 | No sorting
    SORT_NAME | 1 | File name
    SORT_NAME_DIRS_FIRST | 2 | File name, directories first
    SORT_SIZE_ASCENDING | 3 | Ascending file size
    SORT_SIZE_DESCENDING | 4 | Descending file size
    SORT_ACCESS_ASCENDING | 5 | Ascending access time
    SORT_ACCESS_DESCENDING | 6 | Descending access time

Callbacks

The XfwfFileChooser widget provides a single callback list, XtNcallback. This callback is called whenever the contents of the XfwfFileChooser change, either because the user selected a file or directory (or selected the background, which unselects any selected file) or because the XtNcurrentDirectry or XtNcurrentFile resources were changed programmatically. The call_data parameter of the call contains an instance of the following structure:

    typedef struct _XfwfFileChooserReturnStruct
    {
            String directory;
            String file;
    } XfwfFileChooserReturnStruct;

The "file" member is NULL if no file is selected in the fileList.

Public Functions
void XfwfFileChooserChangeDirectory(fcw,dir)
XfwfFileChooserWidget fcw;
char *dir;

    This routine changes the current directory of the XfwfFileChooser widget fcw to be dir, and invokes the callbacks.

void XfwfFileChooserRefresh(fcw)
XfwfFileChooserWidget fcw;

    This routine causes the XfwfFileChooser widget fcw 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 XfwfFileChooserCurrentDirectory(fcw)
XfwfFileChooserWidget fcw;

    Returns the value of the XtNcurrentDirectory resource for the XfwfFileChooser widget fcw.

void XfwfFileChooserCurrentFile(fcw)
XfwfFileChooserWidget fcw;

    Returns the value of the XtNcurrentFile resource for the XfwfFileChooser widget fcw.

Restrictions

The filter function is currently limited to shell-style pattern matching, even though the underlying directory management functions support arbitrary filter functions.

Layout parameters of the XfwfFileChooser widget's children cannot be changed, but other resources can using the names described above under "Widget Hierarchy".

The slider bars of the viewports do not "snap back" when a smaller directory is loaded, and the sliders are down at the bottom.

The stupid List widget doesn't notify when the background is selected, although it unhighlights the item. Blech. This means your callbacks won't always be called when you think they should.

Author

George Ferguson, ferguson@cs.rochester.edu.

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