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 textbox.
Although AG_FileDlg is most often used to implement "Load" or "Save as..." dialog windows, it may also be embedded into any arbitrary container 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.|
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:
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, subsequent directory changes will cause the current AG_Config(3) settings to be saved automatically.
The AG_FileDlgSetFilename() function sets the filename to initially display in the textbox. It is typically used in file saving dialogs.
The AG_FileDlgAddType() function registers a file format/extension, optionally 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 structure and current directory contents.
By default, selecting a file will trigger the following checks:
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:
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 details).
AG_FileDlgCancelAction() overrides the default behavior of the "Cancel" button.
The utility functions AG_FileDlgCheckReadAccess() and AG_FileDlgCheckWriteAccess() evaluate whether the selected file is readable 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 parameters 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
The AG_FileDlgSetOptionContainer() function arranges for the given container widget to hold the control widgets that will be dynamically created.
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 bounds.
AG_FileOptionNewFlt() and AG_FileOptionNewDbl() register single and double 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 exists.
|The AG_FileDlg widget does not provide any bindings.|
AG_FileDlg widget generates the following events:
For the AG_FileType structure (as returned by AG_FileDlgAddType()):
|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.|