AG_FileDlg is a traditional file selection widget.
It 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.
If supports filesystem monitoring via
AG_AddEventSink(3). 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.|
AG_FileDlgNew() allocates, initializes, and attaches a new AG_FileDlg.
The AG_FileDlgNewMRU() variant calls AG_FileDlgSetDirectoryMRU() with mruKey. Unless AG_FileDlgSetDirectory() is used (see below), the default directory is set according to the AG_CONFIG_PATH_DATA setting of AG_Config(3).
AG_FileDlgNewCompact() and AG_FileDlgNewCompactMRU() implicitely set the AG_FILEDLG_COMPACT flag as well as the contents of the display label.
Acceptable flags include:
The working directory can be retrieved as a newly-allocated string using AG_FileDlgGetDirectory(), or copied into a fixed-size buffer with AG_FileDlgCopyDirectory(). AG_FileDlgSetDirectory().
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 current filename can be retrieved as a newly-allocated string using AG_FileDlgGetFilename(), or copied into a fixed-size buffer with AG_FileDlgCopyFilename().
The AG_FileDlgSetFilename() function sets the filename to initially display in the textbox. It is typically used in file saving dialogs.
AG_FileDlgAddType() registers a new type-specific event handler for a given file format (and associated set of filename extensions). If fn is non-NULL, it sets a type-specific callback to invoke when a file of the selected type is selected by the user. descr is a description of the file format and exts is a comma-separated list of filename extensions or special directives (enclosed in "<>"). Syntax for extensions include:
Type-specific handlers do not override the general "file-chosen" event handler when one exists (if both are set then the type-specific handler is run first, followed by "file-chosen").
AG_FileDlgAddImageTypes() registers a common handler for all image types recognized by AG_SurfaceFromFile(3) (such as BMP, PNG and JPEG).
AG_FileDlgCopyTypes() copies the set of AG_FileType (and any associated type-specific options), from one AG_FileDlg to another.
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.
AG_FileDlgCheckReadAccess() and AG_FileDlgCheckWriteAccess() evaluate whether the selected file is readable or writeable.
When we are using
AG_FileDlg to load and save files, we may want to provide the user with format-specific
options that will affect the loading or saving process.
Format-specific options are associated with a file type (an
AG_FileType as returned by
AG_FileDlgAddType()). When a file type is selected,
AG_FileDlg displays basic widgets enabling the user to manipulate those options.
AG_FileDlgSetOptionContainer() 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.
|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. The AG_FILEDLG_COMPACT option as well as AG_FileDlgNewCompact(), AG_FileDlgNewCompactMRU(), AG_FileDlgGetDirectory(), AG_FileDlgCopyDirectory(), AG_FileDlgGetFilename(), AG_FileDlgCopyFilename(), AG_FileDlgCopyTypes() and AG_FileDlgAddImageTypes() routines appeared in Agar 1.6.0.|