NAME

SYNOPSIS

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

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

INITIALIZATION

AG_FileDlg *
AG_FileDlgNewMRU(AG_Widget *parent, const char *mruKey, Uint flags);

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 parent 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 separate 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 invoking AG_ExpandHoriz(3)).

AG_FILEDLG_VFILL

Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).

AG_FILEDLG_EXPAND

Shorthand for AG_FILEDLG_HFILL|AG_FILEDLG_VFILL.

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

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 AG_FileDlgAddType().
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 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

void
AG_FileDlgSetOptionContainer(AG_FileDlg *file_dlg, AG_Widget *container);

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 *unit);

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 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

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.

STRUCTURE DATA

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.

EXAMPLES

SEE ALSO

HISTORY