Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 data-
		   base.

	    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 data-
		   base	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, overrid-
		   ing any  value  in  the  resource  database	and  the  pat-
		   tern_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 but-
		   ton,	 unless	an overriding value is found in	resource data-
		   base. 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	 guar-
		   anteed 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  pat-
		   tern	 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 char-
		   acters.
       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 Can-
	    cel	button.

DESCRIPTION
       XmtAskForFile() and XmtAskForFilename() display	an  application	 modal
       Motif  file selection dialog, of	the type created by XmCreateFileSelec-
       tionDialog(). 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	 file-
       name_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	 XmtDisplayEr-
       ror()).

       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_buf-
       fer_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  dia-
       log, 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 sub-
       part 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 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
       ``xmtFileDialog'' 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://www.freebsd.org/cgi/man.cgi?query=XmtAskForFile&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help