|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.|
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 users 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.
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.
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.
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 dialogs 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.
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.
Chapter 26, Simple Input Dialogs,
XmtAskForBoolean(), XmtAskForDouble(), XmtAskForInteger(), XmtAskForItem(), XmtAskForItemNumber(), XmtAskForString().
|Xmt||XMTASKFORFILE (3)||Motif Tools|