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

FreeBSD Manual Pages


home | help
AG_FILEDLG(3)	       FreeBSD Library Functions Manual		 AG_FILEDLG(3)

     AG_FileDlg	-- agar	file browser widget

     #include <agar/core.h>
     #include <agar/gui.h>

     AG_FileDlg	is a traditional file selection	widget.	 The widget displays a
     list of directories and shortcuts at the left, a list of files at the
     right and an input	textbox	and file type selector at the bottom.  On
     platforms with glob(3) support, glob patterns may be entered in the input

     Although AG_FileDlg is most often used to implement "Load"	or "Save
     as..." dialog windows, it may also	be embedded into any arbitrary con-
     tainer widget.  User-specified actions (with optional parameters) can be
     tied to specific file extensions.

     For selecting directories,	the AG_DirDlg(3) widget	may be used instead.

     AG_Object(3) -> AG_Widget(3) -> AG_FileDlg.

     AG_FileDlg	* AG_FileDlgNew(AG_Widget *parent, Uint	flags)

     AG_FileDlg	* AG_FileDlgNewMRU(AG_Widget *parent, const char *mruKey, Uint

     int AG_FileDlgSetDirectory(AG_FileDlg *file_dlg, const char *format, ...)

     int AG_FileDlgSetDirectoryS(AG_FileDlg *file_dlg, const char *path)

     void AG_FileDlgSetDirectoryMRU(AG_FileDlg *file_dlg, const	char *mruKey,
     const char	*defaultDir)

     void AG_FileDlgSetFilename(AG_FileDlg *file_dlg, const char *format, ...)

     void AG_FileDlgSetFilenameS(AG_FileDlg *file_dlg, const char *filename)

     AG_FileType * AG_FileDlgAddType(AG_FileDlg	*file_dlg, const char *descr,
     const char	*exts, int (*fn)(AG_Event *), const char *fnArgs, ...)

     void AG_FileDlgRefresh(AG_FileDlg *file_dlg)

     The AG_FileDlgNew() function allocates, initializes, and attaches a new
     AG_FileDlg	widget.	 The AG_FileDlgNewMRU()	variant	implicitely calls
     AG_FileDlgSetDirectoryMRU() with the given	key.  Note that	unless
     AG_FileDlgSetDirectory() is used (see below), the default directory is
     set according to the AG_Config(3) `save-path' parameter.

     Acceptable	flags include:

     AG_FILEDLG_MASK_EXT      Mask unknown files by extension.

     AG_FILEDLG_MASK_HIDDEN   Mask hidden files.

     AG_FILEDLG_MULTI	      Allow multiple files to be selected at once.

     AG_FILEDLG_CLOSEWIN      Automatically close the AG_FileDlg widget's par-
			      ent window when a	file is	selected.

     AG_FILEDLG_LOAD	      The selected file	must exist and be readable or
			      an error is returned to the user.

     AG_FILEDLG_SAVE	      The selected file	must be	writeable or an	error
			      is returned to the user.

     AG_FILEDLG_ASYNC	      Load/save	routines will be executed in a sepa-
			      rate thread.  This flag is available only	if
			      agar was compiled	with threads support.

     AG_FILEDLG_NOMASKOPTS    Don't display "Mask files	by extension" and
			      "Mask hidden files" checkboxes.

     AG_FILEDLG_NOTYPESELECT  Don't display the	"Type:"	selector dropbox.

     AG_FILEDLG_NOBUTTONS     Don't display "OK" and "Cancel" buttons.

     AG_FILEDLG_HFILL	      Expand horizontally in parent (equivalent	to in-
			      voking AG_ExpandHoriz(3)).

     AG_FILEDLG_VFILL	      Expand vertically	in parent (equivalent to in-
			      voking AG_ExpandVert(3)).


     The working directory can be set programmatically with the
     AG_FileDlgSetDirectory() function.

     The AG_FileDlgSetDirectoryMRU() sets the working directory	according to
     an	AG_Config(3) parameter named mruKey If the parameter does not exist,
     it	will be	set to defaultDir (it is customary to use a name such as
     `myapp.mru.foofiles').  If	AG_FileDlgSetDirectoryMRU() is used, subse-
     quent directory changes will cause	the current AG_Config(3) settings to
     be	saved automatically.

     The AG_FileDlgSetFilename() function sets the filename to initially dis-
     play in the textbox.  It is typically used	in file	saving dialogs.

     The AG_FileDlgAddType() function registers	a file format/extension, op-
     tionally associated with an event handler function	(see AG_Event(3)) to
     invoke when a file	of that	type if	selected.  descr is a description of
     the file format and exts is a comma-separated list	of file	extensions to
     associate with the	type, or an empty string.

     The AG_FileDlgRefresh() function updates the displayed directory struc-
     ture and current directory	contents.

     By	default, selecting a file will trigger the following checks:

     1.	  If AG_FILEDLG_LOAD or	AG_FILEDLG_SAVE	is set,	check whether the file
	  is readable or writeable.
     2.	  If AG_FILEDLG_SAVE is	set and	a file exists, display a "Replace
	  file?" prompt.
     3.	  Execute the format-specific callback,	as previously configured with
     4.	  If AG_FILEDLG_CLOSEWIN is set, close the parent window.

     The default action	performed when a user clicks on	"Cancel" is simply to
     close the parent window if	AG_FILEDLG_CLOSEWIN is set.

     These default actions can be overridden using the functions below:

     void AG_FileDlgOkAction(AG_FileDlg	*file_dlg, void	(*fn)(AG_Event *),
     const char	*fmt, ...)

     void AG_FileDlgCancelAction(AG_FileDlg *file_dlg, void (*fn)(AG_Event *),
     const char	*fmt, ...)

     int AG_FileDlgCheckReadAccess(AG_FileDlg *file_dlg)

     int AG_FileDlgCheckWriteAccess(AG_FileDlg *file_dlg)

     The AG_FileDlgOkAction() function configures an event handler function to
     invoke when a file	is selected, overriding	the default behavior.  The
     event handler will	be passed a string argument containing the absolute
     path to the selected file,	followed by a pointer to the AG_FileType
     structure for the file type selected by the user (see STRUCTURE DATA for

     AG_FileDlgCancelAction() overrides	the default behavior of	the "Cancel"

     The utility functions AG_FileDlgCheckReadAccess() and
     AG_FileDlgCheckWriteAccess() evaluate whether the selected	file is	read-
     able or writeable.

     In	many cases where we are	using AG_FileDlg to load or save files,	we may
     want to provide the user with format-specific options that	will affect
     the loading or saving process.  This interface controls a list of parame-
     ters associated with the AG_FileType objects (as returned by
     AG_FileDlgAddType()).  Whenever a file type is selected, AG_FileDlg will
     automatically display control widgets allowing the	user to	manipulate
     those parameters.

     void AG_FileDlgSetOptionContainer(AG_FileDlg *file_dlg, AG_Widget

     AG_FileOption * AG_FileOptionNewBool(AG_FileType *type, const char
     *descr, const char	*key, int default)

     AG_FileOption * AG_FileOptionNewInt(AG_FileType *type, const char *descr,
     const char	*key, int default, int min, int	max)

     AG_FileOption * AG_FileOptionNewFlt(AG_FileType *type, const char *descr,
     const char	*key, float default, float min,	float max, const char *unit)

     AG_FileOption * AG_FileOptionNewDbl(AG_FileType *type, const char *descr,
     const char	*key, double default, double min, double max, const char

     AG_FileOption * AG_FileOptionGet(AG_FileType *type, const char *key)

     int AG_FileOptionBool(AG_FileType *type, const char *key)

     int AG_FileOptionInt(AG_FileType *type, const char	*key)

     float AG_FileOptionFlt(AG_FileType	*type, const char *key)

     double AG_FileOptionDbl(AG_FileType *type,	const char *key)

     The AG_FileDlgSetOptionContainer()	function arranges for the given	con-
     tainer widget to hold the control widgets that will be dynamically	cre-

     AG_FileOptionNewBool() registers a	boolean	option,	manipulated by an
     AG_Checkbox(3).  descr is a description string and	key is a handle	that
     the save/load routine will	use to retrieve	the option.  default indicates
     the initial value of the option (1	= true,	0 = false).

     AG_FileOptionNewInt() registers an	integer	option,	manipulated by an
     AG_Numerical(3).  default is the initial value, min and max define	the

     AG_FileOptionNewFlt() and AG_FileOptionNewDbl() register single and dou-
     ble precision floating-point options, using AG_Numerical(3).  default is
     the initial value,	min and	max define the bounds and unit,	if not NULL,
     is	the unit system	to use (see AG_Units(3)).

     AG_FileOptionGet()	returns	a pointer to the AG_FileOption structure for
     the given option name, or NULL if there is	no such	option.
     AG_FileOptionBool(), AG_FileOptionInt(), AG_FileOptionFlt() and
     AG_FileOptionDbl()	return the value of the	given option assuming it ex-

     The AG_FileDlg widget does	not provide any	bindings.

     The AG_FileDlg widget generates the following events:

     file-chosen(char *path, AG_FileType *type)
	 User has selected the given file.  path is the	full pathname to the
	 file.	If not NULL, type describes the	file type that was selected by
	 the user.

     file-selected(char	*path)
	 User has moved	selection over the given file, where path is the full
	 pathname to it.  This event is	useful for things like previewing file
	 contents using	an external widget.

     dir-selected(char *path)
	 The given directory was selected.

     For the AG_FileDlg	object:

     char cwd[AG_PATHNAME_MAX]	   Absolute path of current working directory.
     char cfile[AG_PATHNAME_MAX]   Absolute path of last selected file.

     For the AG_FileType structure (as returned	by AG_FileDlgAddType()):

     AG_FileDlg	*fd	 Back pointer to the parent AG_FileDlg (read-only).
     char **exts	 List of associated file extensions.
     Uint nexts		 Count of file extensions.
     const char	*descr	 Description string (read-only).
     AG_Event *action	 Callback function (as returned	by AG_SetEvent(3)) to
			 invoke	when a file of this type is selected for a
			 load/save operation.

     See tests/loader.c	in the Agar source distribution.

     AG_DirDlg(3), AG_Intro(3),	AG_Limits(3), AG_Widget(3), AG_Window(3)

     The AG_FileDlg widget first appeared in Agar 1.0.

FreeBSD	13.0			October	5, 2006			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help