FreeBSD Manual Pages
XmtAskForFile(3) Library Functions Manual XmtAskForFile(3) 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, un- less 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 func- tions its contents are used as the default filename to be dis- played 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 ar- gument 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 argu- ment. pattern_buffer_len The length in characters of pattern_buffer, or 0 if that argu- ment 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 di- rectory) of the file selected by the user. It is guaranteed to be null-terminated and never to contain more than file- name_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 XmtAskFor- File() returns True this buffer contains the name of the direc- tory of the user's selected file. It is guaranteed to be null- terminated and never to contain more than direc- tory_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 XmtAskFor- File() returns True this buffer contains the pattern most re- cently 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 XmCreateFileSelectionDia- log(). 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, XmtAsk- ForFile() displays an error dialog (using XmtDisplayError()). On entry to XmtAskForFile() or XmtAskForFilename(), the contents of file- name_buffer are used as the default filename to display to the user. In ad- dition, 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 direc- tory_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 se- lection 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 di- alog, 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 ``Xmt- FileDialog''. These subpart resources are looked up every time the func- tions 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 over- | | | | ridden by direc- | | | | tory_buffer. | +------------+-------------------+----------------------+ | pattern | pattern_default | The pattern that | | | | filenames must | | | | match, unless over- | | | | ridden by pat- | | | | tern_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 ``xmt- FileDialog'' as a child of the XmDialogShell. Once this dialog has been created, it is cached for reuse by subsequent calls. SEE ALSO Chapter 26, Simple Input Dialogs, XmtAskForBoolean(), XmtAskForDouble(), XmtAskForInteger(), XmtAskForItem(), XmtAskForItemNumber(), XmtAskForString(). Xmt Motif Tools XmtAskForFile(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtAskForFilename&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>