Release Date: 1 February 2008
Namedw_file - file widget
C Prototype#include <X11/Xlib.h>
/*** Standard widget functions ***/
int dw_file_create (Frame parent);
/*** Functions specific to the File widget ***/
dw_file_invoke(int id, char *prompt, char *path,
char *access, int pinned,
/*** User-supplied callback functions ***/
int cbt(char *filepath);
/*** Function-like convenience macros ***/
dw_file_invoke_for_input (int id, void (*cbr)())
DescriptionThe File widget provides an environment-independent way of allowing the user to specify a file name. It returns the full path name of the selected file (or NULL, if the user selected "Cancel") by calling the "cbr()" result callback function. It is up to the calling program to actually open the file.
The details of how the user interaction is handled is completely up to the File widget. In the Daylight 4.3 version of this widget, the user can type in a file name, select from lists, sort the lists in various ways, change directories, and other convenience features.
By default, the File widget will present and return only suitable filenames, e.g. if a writable file is requested (argument access contains 'w') it will not allow the user to select a file which is not writable. If not NULL, the test callback ("cbt()") is called with each file which might be offered to the user. The filename is not shown if this function returns FALSE (0). This allows very flexible control of the File widget's interaction. For instance, the File widget could be set up to induce the user to select a readable text file with filename ending in ".smi". Note, however, that the File widget also provides the user with the ability to force display of all files, so the cbt() callback should be treated as giving hints to the user.
Two macros are offered for convenience in obtaining file names for generic "read" and "write" operations. These macros expand to dw_file_invoke() calls with these preset parameters:
dw_file_invoke_for_input dw_file_invoke_for_output ------------------------ ------------------------- prompt: "Select input file" "Select output file" path: NULL NULL access: "r" "w" pinned: FALSE FALSE cbt: NULL NULL
Although any number of File widgets can exist concurrently, only one is used in typical application programs.
dw_file_create(Frame parent) => int
Create a File widget as a child of XView Frame parent. The widget is initially empty and is not visible. A positive widget id is returned on success; 0 is returned on error.
dw_file_destroy(int id) => void
Destroy the given File widget.
dw_file_hide(int id) => void
Unconditionally hide the given File widget.
dw_file_invoke(int id, char *prompt, char *path, char *access, int pinned, int (*cbt)(), void (*cbr)()) => int
Invoke File widget `id' with given prompt. Initial directory will be `path'; if NULL it will be the current working directory. Argument `access' is a string which may contain if NULL or empty, any non-directory file name will be accepted. If the argument 'pinned' is TRUE, the widget will pin itself up (ala olwm) and not disappear when selection is completed (dw_file_hide() provides a more useful way of controlling this). If not NULL, callback function cbt() will be called with filenames to be offered to the user; the function can veto them on and individual basis by returning FALSE. Callback function cbr() is called with the selected file name as a full path name, or NULL if user selects "Cancel". TRUE (1) is returned on success, FALSE (0) on error.
dw_file_redraw(int id) => void
Refresh the given widget.
dw_file_reset(int id) => void
Clear the given File widget.
dw_file_setlabel(int id, char *label) => void
Set the label on the given File widget. A value of NULL sets the default label.
dw_file_show(int id) => void
Make the given File widget visible. This is not typically needed, since dw_file_invoke() automatically makes the widget visible.
Return ValueNo error messages are generated by this widget.
Release 4.2 is the first release of this widget. Release 4.3 corrected a bug which occasionally resulted in the widget causing a program crash when file names were "double-clicked" under window managers other than olwm.
BugsThis widget should probably be simplified; there are too many features.
Related TopicsDaylight Widget User's Guide
Daylight Widget Programmer's Guide