FileComplete(3)

NAME
FileComplete - an emacs-style file selection widget for the X toolkit built upon Athena widgets.

VITAL STATS
Application Header file	<Xfwf/FileComp.h>
Class Header file		<Xfwf/FileCompP.h>
Class				xfwffileCompleteWidgetClass
Class Name			XfwfFileComplete
Superclass			Form
 The file completion widget allows the application programmer to easily provide the user with a familiar, convenient and (hopefully) intuitive way to select files from the Unix filesystem.
  It borrows ideas from other popular windowing systems by allowing the user to double-click to select files or switch directories.
  It borrows from the popular copylefted emacs editor by allowing the user to type in filenames, use SpaceBar and Tab to complete filenames, and perform ~ expansion.
  Both of these input modes can be mixed for users who frequently switch gears.

USER INFORMATION
Preprocessing
  There is a certain amount of preprocessing that is done to the text buffer to save the user keystrokes. This preprocessing occurs whenever the user presses one of the special keys mentioned below or presses the Ok button.
  If a ~ or a / appears immediately after a /, all the text before and including that / is deleted. Therefore /var/tmp//goop//cis/src would become /cis/src. csh-style ~ expansion is also performed. ~/ expands to the user's home directory (as recorded in the HOME environment variable). ~username expands to username's home directory (as returned by getpwnam(3)).
  If the followLinks resource is set to always, the path in the buffer is normalized by statting .. until the root is reached. The path computed by this procedure is then substituted for the old path and the preprocessing is complete.
  If the followLinks resource is set to whenShorter, the path in the buffer is normalized as before, but only substituted if it is shorter than the old path. If a substitution is appropriate, preprocessing is complete.
  If the followLinks resource is set to never or the whenShorter was not shorter, the next stage of preprocessing occurs.
  If a sequence of path/dirname/../ is encountered, and it and path/ refer to the same directory (as determined by statting and comparing inode and device numbers for the two) then the dirname/../ will be deleted leaving only path. If it does not match, then .. statting similar to that above will be performed and substitutions will be performed or not based on the followLinks resource.
  A value of followLinks = never gives the fastest preprocessing and should be acceptable to most users. Programmers should not specify the value of this unless they absolutely have to. Keyboard Actions
  The user can type anywhere in the widget and keyboard input will appear in the text window at the top of the widget. There are three special keys that will not be interpreted as filename components. SpaceBar
  When the user presses the SpaceBar the widget will search the list of files it has stored internally for filenames whose prefix matches what the user has typed so far. If there is a unique completion, it will be entered into the buffer. The user may then press Return or press OK to select that file. If there are several completions, the widget will substitute the longest prefix that is common to all of the candidates. If this does not extend the currently typed text, the list widget in the bottom left will change to show all of the possible completions. The user may then type more characters to make the prefix unique, or click on one of the selections to substitute it into the buffer.
  If the completion is unique and a directory, the widget will change to that directory and list its files. Tab
  The Tab key is identical to the SpaceBar except it will not change the list widget unless there is a directory change. Return
  This tells the application that the filename currently in the text buffer is what you want. Pressing this key is equivalent to hitting the OK button and will invoke the application-specific actions that the FileComplete was created for. Mouse Actions
  When the user single-clicks on an item in the list widget, the filename is substituted into the text buffer at the top of the widget. When the user double-clicks the file is "selected". For files, this means the same thing that pressing the OK button does. For directories, if the dirnamesOk resource is true then double-clicking is the same as pressing the OK button. If the resource is false, then double-clicking will go into that directory.
  Therefore, if the dirnamesOk resource is true, you can not switch directories by double-clicking. You have to type the dirname or click on the dirname and press SpaceBar. If the dirnamesOk resource is false, you can not select a directory by double-clicking. You have to type the dirname or click on the dirname and press Return.
  There are also usually at least two buttons in a box in the bottom right section of the widget. The Ok and Cancel buttons appear by default, but can be disabled by the application.
  The Ok button signifies that you have selected a file for the program. It is the same as double clicking on a filename, or pressing Return. The current contents of the text buffer will be preprocessed and passed to the file completion widget's callback list.
  The Cancel button signifies that you do not want to perform the operation, instead you want to abort. The functions on the cancelCallback list will be invoked.
  Other buttons in the box could be available on a per-application basis to do other functions. Check your application's manual for details.

PROGRAMMER INFORMATION
  The FileComplete widget is divided into four areas. The top is an AsciiText widget called "text". Just below that is a status Label called "status". Below that is a pair of widgets. On the left is a ScrolledList called "files" that contains a list of files. On the right is a Box called "buttons" that holds an "Ok" and a "Cancel" Command widget called "ok" and "cancel" respectively. The following resources are specific to the FileComplete widget
Name | Class | Type | Default Value
filename | Filename | String | "./"
sortProc | SortProc | Function | NULL
statThreshold | StatThreshold | Int | 32
acceptableFilenameProc | AcceptableFilenameProc | AcceptableFileProc | any
filenameProcData | FilenameProcData | String | NULL
acceptableStatsProc | AcceptableStatsProc | AcceptableStatsProc | any
statsProcData | StatsProcData | String | NULL
okLabel | Label | String | "Ok"
callback | Callback | XtCallbackList | NULL
showOkButton | ShowButton | Boolean | True
cancelLabel | Label | String | "Cancel"
cancelCallback | Callback | XtCallbackList | NULL
showCancelButton | ShowButton | Boolean | True
dirnamesOk | DirnamesOk | Boolean | False
statLinks | StatLinks | Boolean | True
followLinks | FollowLinks | FollowLinks | never

filename
    The value in the text buffer. This can be used to set the initial directory displayed for the user. When retrieved, do not modify this String in place. This can lead to strange behavior.

sortProc
    This is a procedure used to sort the filenames in a directory. It should be of type XfwfFCSortProc, defined below. Beware that you can sort . and .. into a position not at the top of the directory. Therefore the programmer is encouraged not to sort the first two elements of the Xfwffileent array.

statThreshold
    If there is no acceptableStatsProc and there are more than statThreshold filenames in a directory, these entries will be statted in the background to prevent the application from "freezing". The user is encouraged to continue typing or selecting because if another directory is selected, the statting will be short circuited and unneeded processing will not occur.

acceptableFilenameProc
    This is a function of type XfwfFCAcceptableFilenameProc that returns True if a filename is allowed to appear in the list. Note that the procedure has no other information than the filename. The FileComplete class registers a type converter from String to AcceptableFileProc.

filenameProcData
    This is a pointer that is passed to the acceptableFilenameProc through the client_data argument. It is a String for convenience reasons.

acceptableStatsProc
    This is a function of type XfwfFCAcceptableStatsProc that returns True if a filename is allowed to appear in the list. This procedure has both the filename and the struct stat returned by the stat(2) system call available for perusal. Providing the widget with one of these procedures disables the background statting capability. This can cause the application to "freeze" during the statting of large directories. If an acceptableFilenameProc is provided and returns False for a filename, that file will not be statted and the acceptableStatsProc will not be consulted. The FileComplete class registers a type converter from String to AcceptableStatsProc.

statsProcData
    This is a pointer that is passed to the acceptableStatsProc through the client_data argument. It is a String for convenience reasons.

okLabel
    This is the label that will appear on the Ok button.

callback
    This is a callback list that will be called whenever the user presses the Ok button or the Return key.

showOkButton
    This Boolean resource determines whether the Ok button will exist or not.

cancelLabel
    This is the label that will appear on the Cancel button.

cancelCallback
    This is a callback list that will be called whenever the user presses the Cancel button.

showCancelButton
    This Boolean resource determines whether the Cancel button will exist or not.

dirnamesOk
    This Boolean resource affects the behavior of a double-click on a directory name. See the User Info section for more details.

statLinks
    This resource determines whether the widget will use lstat(2) or stat(2) to retrieve information about a file. If it is True, the widget will use lstat(2). This is the default because use of stat(2) can be a REAL pain on systems that use amd(8), the AutoMount Daemon.

followLinks
    This resource is of type enum XfwfFCFollowLinks and is either never, whenShorter, or always. It alters widget behavior as described above in the User Info section.

STRUCTURES AND TYPEDEFS
  The following types are defined in the FileComplete.h header file for the programmer's use.
typedef struct {
	char	*filename;
	char	*repr;
} Xfwffileent;
typedef void (*XfwfFCSortProc)( Xfwffileent *base, int nfiles );
typedef Boolean (*XfwfFCAcceptableFilenameProc)(
		char *filename,
		XtPointer client_data );
typedef Boolean (*XfwfFCAcceptableStatsProc)(
		char *filename,
		struct stat *filestats,
		XtPointer client_data );
enum XfwfFCFollowLinks {
  XfwfFCNever, XfwfFCWhenShorter, XfwfFCAlways
};
  The following values and convenience functions are declared in the public header file for use with the acceptableFilenameProc:
#define XfwfFCAnyFilename  ((XfwfFCAcceptableFilenameProc)0)
extern Boolean XfwfFCNoDotFiles( char *filename, XtPointer ignored );
extern Boolean XfwfFCNoTildeBackups( char *filename, XtPointer ignored );
extern Boolean XfwfFCNoTildeBackupsOrDotFiles( char *filename, XtPointer ignored );
extern Boolean XfwfFCRegexFiles( char *filename, XtPointer regex );
The converter defined by the class will turn a string value of "any", "nodotfiles", "notildebackups", "notildebackupsordotfiles", or "regexfiles" into the appropriate XfwfFCAcceptableFilenameProc value. The regex parameter to XfwfFCRegexFiles is an ed(1) style regular expression that will be used by the functions defined in <regex.h>. The following values are defined in the public header file for use with the acceptableStatsProc:
#define XfwfFCAnyStats  ((XfwfFCAcceptableStatsProc)0)
extern Boolean XfwfFCDirsOrRegexFiles(
		char *filename,
		struct stat *filestats,
		XtPointer regex );
The converter defined by the class will turn a string value of "any" or "dirorregexfiles" into the appropriate XfwfFCAcceptableStatsProc value. The regex parameter of XfwfFCDirsOrRegexFiles is passed to XfwfFCRegexFiles if the file is not a directory. The FileComplete widget registers a converter from String to FollowLinks that will convert "never", "whenshorter", and "always" to appropriate values. The following procedures are declared in the public header file in the event that a programmer needs to use the subwidgets of a FileComplete widget.
Widget XfwfFileCompleteText(Widget w);
Widget XfwfFileCompleteStatus(Widget w);
Widget XfwfFileCompleteFileList(Widget w);
Widget XfwfFileCompleteBox(Widget w);
There is also a convenience procedure to add buttons to the FileComplete's box.
Widget XfwfFileCompleteAddButton(
		Widget w,
		char *name,
		XtCallbackProc proc,
		XtPointer client_data );
This function returns the newly created widget so that the programmer can modify it using XtSetValues. The public header file declares another convenience procedure
void XfwfFileCompleteTrimToPath(Widget w);
This procedure deselects any item from the ScrolledList and trims off the trailing filename component of the current filespec, leaving only directory path elements. It is useful to clean up a reusable popup FileComplete widget just before it is popped up or just after it is popped down.

TRICKS
  There is a reason the widget provides type converters for the acceptableProcs and the ProcData is a String. It allows the user or programmer to control the list of files using nothing more complicated than the app-defaults. For example, this will make all FileComplete widgets show only directories, .c and .h files. It will also slow down all those FileComplete widgets since they have to stat every entry in the directory before accepting user input.
*FileComplete.acceptableStatsProc: dirorregexfiles
*FileComplete.statsProcData: .*\.[ch]
If you must have an acceptableStatsProc, try to eliminate as many files as you can using the acceptableFilenameProc first. Anything that doesn't survive the acceptableFilenameProc will not be statted and will save you a lot of time. Unfortunately, for most applications, you can rarely do this.

PROBLEMS
  This widget has only been tested on Sun4s, and not very well tested at that. If you have problems compiling, tell me. I'll try to fix it. If you have other problems using it, tell me.
  The getod function could be made much nicer by having it check the mount entries when it crosses device boundaries. This would result in much "nicer" filenames on systems that mount onto symlinks and may result in a performance enhancement.
  It would be nice if the widget could delay the statting of items that were not visible on the list and dynamically delete items that failed the predicates. This would require a much more sophisticated list widget, though.
  The box widget does not make the same assumptions about "preferred size" that the FileComplete widget does. This leads to ugly button layout. I need to abandon the box and do some custom layout. Better yet, I'll write a different form widget.

COPYRIGHT
Copyright (C) 1992 Robert Forsman This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

ACKNOWLEDGMENTS
This product includes software developed by the University of California, Berkeley and its contributors. Specifically, the getod.c module is derived from Berkeley's getcwd.c.
  Thanks to Brian Totty for creating the Free Widget Foundation and maintaining the distribution.
  Thanks to Jordan Breslow and Dan Greening for copyright assistance.
Jordan J. Breslow
a copyright and computer lawyer type guy
P.O. Box 12979
Oakland, CA  94604-2979
(510) 451-0544
Dan Greening
Software Transformation
1601 Saratoga-Sunnyvale Rd, #100
dgreen@sti.com
(408) 973-8081 x313
Cupertino, CA 95014

AUTHOR
Robert Forsman
thoth@lightning.cis.ufl.edu
University of Florida
Department of Computer and Information Science