SYNOPSIS
|
DESCRIPTION
![]() 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. |
INHERITANCE HIERARCHY
AG_Object(3)-> AG_Widget(3)-> AG_FileDlg. |
INTERFACE
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. |
OK/CANCEL ACTIONS
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. |
FORMAT-SPECIFIC OPTIONS
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. |
BINDINGS
The AG_FileDlg widget does not provide any bindings. |
EVENTS
The
AG_FileDlg widget generates the following events:
|
STRUCTURE DATA
For the
AG_FileDlg object:
For the AG_FileType structure (as returned by AG_FileDlgAddType()):
|
EXAMPLES
See tests/loader.c in the Agar source distribution. |
SEE ALSO
AG_DirDlg(3), AG_Intro(3), AG_Limits(3), AG_Widget(3), AG_Window(3) |
HISTORY
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. |