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. |
INITIALIZATION
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. |
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. The utility functions AG_FileDlgCheckReadAccess() and AG_FileDlgCheckWriteAccess() evaluate whether the selected file is readable or writeable. |
FORMAT-SPECIFIC OPTIONS
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
those parameters.
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. |
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. |