Name

C Prototype

/*** Standard widget functions ***/

int dw_file_create (Frame parent);
void dw_file_destroy (int id);
void dw_file_hide (int id);
void dw_file_redraw (int id);
void dw_file_reset (int id);
void dw_file_setlabel(int id, char *label);
void dw_file_show (int id);

/*** Functions specific to the File widget ***/

dw_file_invoke(int id, char *prompt, char *path, char *access, int pinned,
int (*cbt)(), void (*cbr)());

/*** User-supplied callback functions ***/

int cbt(char *filepath);
void cbr(char *filepath);

/*** Function-like convenience macros ***/

dw_file_invoke_for_input (int id, void (*cbr)())
dw_file_invoke_for_output(int id, void (*cbr)())

Description

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 Value

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.

Bugs

Related Topics