NAME

XsraSelFile − select a file

SYNOPSIS

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

ret = XsraSelFile(display, prompt, ok, cancel, init_path, show_entry, path_return)
intret;
Display∗display;
unsigned char ∗prompt;
unsigned char ∗ok;
unsigned char ∗cancel;
char∗init_path;
int(∗show_entry)();
char∗∗path_return;

DESCRIPTION

XsraSelFile allows an X11 user to select a file by typing the path or by browsing in directory listings and selecting entries with the mouse.  The space bar can be pressed to complete filenames, and tilde is used for home directories. All of the usual key bindings can be used in the text widget, except for Return and Control-M, which are equivalent to pressing the OK button. The path can be scrolled using the large horizontal scroll bar, or by moving the insertion cursor in the text widget. The directory entries can be scrolled using the vertical scroll bars, or by holding a mouse button down and moving out of the listing. The scrolling speed varies with the distance from the listing. The directory entries are terminated with special characters that indicate the kind of entry, similar to the −F option of ls(1). The programmer’s interface is simple, providing an easy way for the application to obtain a filename from the user. XsraSelFile does not allow X events to be generated on any other widgets in the application by adding a grab for the dialog widget while it is active. 

ARGUMENTS

The display argument specifies the display on which to create the new application shell dialog widget.  If it is specified as NULL, the default display is opened by initializing the X toolkit.  The prompt argument specifies the prompt to print near the top of the new widget.  This should be a string containing no newlines.  If the prompt is specified as NULL, the string "Pathname:" is used.  The ok argument specifies the string to print in the OK button.  If it is specified as NULL, "OK" is used.  The cancel argument specifies the string to print in the Cancel button.  If it is specified as NULL, "Cancel" is used.  The initial path may be set using init_path.  If it is specified as NULL, the initial path will be the current directory.  The show_entry argument is a pointer to a function that is called to decide whether or not to display a particular directory entry.  If this argument is specified as NULL, all entries will be displayed.  Otherwise, the function is called with arguments as follows. 

int show_entry(real_name, shown_name_return, entry_stat)
char∗real_name;
char∗∗shown_name_return;
struct stat∗entry_stat;

The real_name argument is the name of the entry, and the entry_stat argument is a pointer to the stat buffer of the entry.  The contents of the real_name and entry_stat arguments should not be altered.  The shown_name_return argument is to be filled in by the function if a name other than the real name is to be shown.  The function should return true if the entry is to be displayed.  An example of a show_entry function can be found in callback.c. When the return key or the OK button is pressed, XsraSelFile returns, putting the full path of the selected file in path_return unless it is NULL.  XtMalloc is used to make a copy of the path.  The application writer is responsible for freeing the space. 

RETURN VALUE

The ret return value is 0 if the user presses the return key or the OK button.  Otherwise, the user has pressed the Cancel button and a value of −1 is returned. 

COMPILATION

The XsraSelFile package can be linked with Athena (Xaw) and/or Hewlett-Packard (Xw) widgets, by choosing the appropriate defines. See the Imakefile for details. 

RESOURCES

The font to be used by XsraSelFile is specified by putting the following in a resource file: selFile∗font :9x15 (The default font is 9x15.)

ENVIRONMENT

DISPLAY − the default host and display to use. 

SEE ALSO

X(1), xrdb(1), X Toolkit

BUGS

XsraSelFile must always be called with the same display argument.  When a directory is modified by a third party while the pointer is in that directory’s listing, the display will be updated and the pointer will be warped away to prevent the user from selecting ‘the wrong file’, which can be considered dangerous if the application is about to delete whatever the user selects.

COPYRIGHT

Copyright 1989 Software Research Associates, Inc., Tokyo, Japan

AUTHOR

Erik M. van der Poel, Software Research Associates, Inc., Tokyo, Japan

Amiga Unix  —  Last change: April 24 1989