NAME

XmtAskForFile(), XmtAskForFilename() - use a file selection dialog box to prompt the user to select a file and return the user's response.

SYNOPSIS

Boolean XmtAskForFile(Widget w, String query_name, String prompt_default, String directory_default, String pattern_default, FILE **value_return, String file_mode, String filename_buffer, int filename_buffer_len, String directory_buffer, int directory_buffer_len, String pattern_buffer, int pattern_buffer_len, String help_text_default)

Boolean XmtAskForFilename(Widget w, String query_name, String prompt_default, String directory_default, String pattern_default, String filename_buffer, int filename_buffer_len, String directory_buffer, int directory_buffer_len, String pattern_buffer, int pattern_buffer_len, String help_text_default)

ARGUMENTS

INPUTS

w: The shell widget over which the dialog will be displayed, or any descendant of that shell.
query_name: The name of this instantiation of the dialog; used to look up resources. NULL may be specified, but will result in a dialog that cannot be customized through the resource database.
prompt_default: The prompt message to be displayed in the dialog, unless an overriding value is found in the resource database.
directory_default: The initial directory to display in the file selection box, unless an overriding value is found in the resource database or in the directory_buffer argument.
pattern_default: The initial pattern to filter filenames against, unless an overriding value is found in the resource database or in the pattern_buffer argument.
file_mode: For XmtAskForFile() only, a string which specifies how the file should be opened. It will be passed unmodified to fopen().
filename_buffer: A character buffer owned by the caller. On entry to these functions its contents are used as the default filename to be displayed to the user.
filename_buffer_len: The length in characters of filename_buffer.
directory_buffer: A character string owned by the caller, or NULL. If it is non-NULL and non-empty on entry, then its contents are used as the initial directory to be displayed, overriding any value in the resource database and the directory_default argument.
directory_buffer_len: The length in characters of directory_buffer, or 0 if that argument should not be written into.
pattern_buffer: A character string owned by the caller, or NULL. If it is non-NULL and non-empty on entry, then its contents are used as the initial pattern to match filenames against, overriding any value in the resource database and the pattern_default argument.
pattern_buffer_len: The length in characters of pattern_buffer, or 0 if that argument should not be written into.
help_text_default: The help text to display when the user clicks the Help button, unless an overriding value is found in resource database. NULL may be specified.

OUTPUTS

value_return: For XmtAskForFile() only, the address of a variable of type FILE * owned by the caller. If XmtAskForFile() returns True, the file selected by the user has been opened and stored in this variable.
filename_buffer: A character buffer owned by the caller. When XmtAskFor File() returns True, this buffer contains the full name (including directory) of the file selected by the user. It is guaranteed to be null-terminated and never to contain more than filename_buffer_len-1 characters.
directory_buffer: A character string owned by the caller, or NULL. If it is non-NULL, and directory_buffer_len is not 0, then when XmtAskForFile() returns True this buffer contains the name of the directory of the user's selected file. It is guaranteed to be null-terminated and never to contain more than directory_buffer_len-1 characters.
pattern_buffer: A character string owned by the caller, or NULL. If it is non-NULL, and pattern_buffer_len is not 0, then when XmtAskForFile() returns True this buffer contains the pattern most recently used in the file selection box to match filenames against. It is guaranteed to be null terminated and never to contain more than pat tern_buffer_len-1 characters.

RETURNS

True if the user clicked the Ok button or double-clicked on a filename to dismiss the dialog; False if the user clicked the Cancel button.

DESCRIPTION

XmtAskForFile() and XmtAskForFilename() display an application modal Motif file selection dialog, of the type created by XmCreateFileSelectionDialog(). They process events in a local event loop until the user double-clicks on a filename or selects the Ok or Cancel buttons of the dialog, and then return control to the calling procedure. If the user clicks on the Cancel button, these functions return False immediately. Otherwise, they store the full name of the selected file into filename_buffer and return True.

In addition to these actions, XmtAskForFile() opens the selected file as specified by file_mode, and stores the opened file at the address specified by value_return. If the attempt to open the specified file fails, XmtAskForFile() displays an error dialog (using XmtDisplayError()).

On entry to XmtAskForFile() or XmtAskForFilename(), the contents of filename_buffer are used as the default filename to display to the user. In addition, if directory_buffer and pattern_buffer are non-NULL and are not empty, then they are used as the initial directory and the initial pattern for the file selection box. If these arguments are NULL, then the initial directory and pattern are looked up in the resource database, and if they are not found there, directory_default and pattern_default are used as the defaults.

If directory_buffer and pattern_buffer are non-NULL, and directory_buffer_len and pattern_buffer_len are not 0, then when these functions return True, they store the current directory and pattern of the file selection box into these buffers. You can use these returned values with the next invocation of these functions-see Chapter 26, Simple Input Dialogs for discussion of this point.

If help text is found in the resource database for this instance of the dialog, or if the help_text_default argument is non-NULL, then this text will be displayed (using XmtDisplayInformation()) when the user clicks on the Help but ton. If there is no help available for the dialog, then the Help button will be insensitive.

Customization

To allow customization, XmtAskForFile() and XmtAskForFilename() look up the following subpart resources of the toplevel shell. The name of the subpart is given by the query_name argument, and the class of the subpart is ``XmtFileDialog''. These subpart resources are looked up every time the functions are called, not simply when the widgets are created.

fBResource	Default	Description
message	prompt_default	The prompt for the dialog.
title	”Select a File“	The string in the dialog's titlebar.
directory	directory_default	The directory to display unless overridden by directory_buffer.
pattern	pattern_default	The pattern that filenames must match, unless overridden by pattern_buffer.
helpText	help_text_default	Online help for the dialog.

WIDGETS

XmtAskForFile() and XmtAskForFilename() create an XmDialog Shell widget named ``xmtFileDialogShell'' and an XmFileSelectionBox widget named ``xmtFileDialog'' as a child of the XmDialogShell. Once this dialog has been created, it is cached for reuse by subsequent calls.

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

SEE ALSO