.\" Copyright (c) 2006-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 5, 2006
.Dt AG_FILEDLG 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.1
.Sh NAME
.Nm AG_FileDlg
.Nd agar file browser widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.Nm
is a file selection widget.
It is typically used to implement file dialog boxes where actions are tied
to specific file extensions.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft AG_FileDlg *
.Fn AG_FileDlgNew "AG_Widget *parent" "Uint flags"
.Pp
.Ft AG_FileDlg *
.Fn AG_FileDlgNewMRU "AG_Widget *parent" "const char *mruKey" "Uint flags"
.Pp
.Ft int
.Fn AG_FileDlgSetDirectory "AG_FileDlg *file_dlg" "const char *path"
.Pp
.Ft void
.Fn AG_FileDlgSetDirectoryMRU "AG_FileDlg *file_dlg" "const char *mruKey" "const char *defaultDir"
.Pp
.Ft void
.Fn AG_FileDlgSetFilename "AG_FileDlg *file_dlg" "const char *fmt" "..."
.Pp
.Ft "AG_FileType *"
.Fn AG_FileDlgAddType "AG_FileDlg *file_dlg" "const char *descr" "const char *exts" "void (*fn)(AG_Event *)" "const char *fmt" "..."
.Pp
.nr nS 0
The
.Fn AG_FileDlgNew
function allocates, initializes, and attaches a new
.Nm
widget.
The
.Fn AG_FileDlgNewMRU
variant implicitely calls
.Fn AG_FileDlgSetDirectoryMRU
with the given key.
The
.Xr AG_Config 3
.Sq save-path
parameter is used as the default directory.
.Pp
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_FILEDLG_CLOSEWIN "
.It AG_FILEDLG_MULTI
Allow multiple files to be selected at once.
.It AG_FILEDLG_CLOSEWIN
Automatically close the
.Nm
widget's parent window when a file is selected.
.It AG_FILEDLG_LOAD
The selected file must exist and be readable or an error is returned to
the user.
.It AG_FILEDLG_SAVE
The selected file must be writeable or an error is returned to the user.
.It 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.
.El
.Pp
The working directory can be set manually with the
.Fn AG_FileDlgSetDirectory
function, which will return 0 on success and -1 on failure.
.Pp
The
.Fn AG_FileDlgSetDirectoryMRU
sets the working directory according to an
.Xr AG_Config 3
parameter named
.Fa mruKey
If the parameter does not exist, it will be set to
.Fa defaultDir
(it is customary to use a name such as
.Sq myapp.mru.foofiles ) .
If
.Fn AG_FileDlgSetDirectoryMRU
is used, subsequent directory changes will cause the current
.Xr AG_Config 3
settings to be saved automatically.
.Pp
The
.Fn AG_FileDlgSetFilename
function sets the filename to initially display in the textbox.
It is typically used in file saving dialogs.
.Pp
The
.Fn AG_FileDlgAddType
function registers a file format/extension, optionally associated with an
event handler function (see
.Xr AG_Event 3 )
to invoke when a file of that type if selected.
.Ft descr
is a description of the file format and
.Ft exts
is a comma-separated list of file extensions to associate with the type, or
an empty string.
.Pp
.Sh OK/CANCEL ACTIONS
By default, selecting a file will trigger the following checks:
.Pp
.Bl -enum -compact
.It
If
.Dv AG_FILEDLG_LOAD
or
.Dv AG_FILEDLG_SAVE
is set, check whether the file is readable or writeable.
.It
If
.Dv AG_FILEDLG_SAVE
is set and a file exists, display a "Replace file?" prompt.
.It
Execute the format-specific callback, as previously configured with
.Fn AG_FileDlgAddType .
.It
If
.Dv AG_FILEDLG_CLOSEWIN
is set, close the parent window.
.El
.Pp
The default action performed when a user clicks on "Cancel" is simply to
close the parent window if
.Dv AG_FILEDLG_CLOSEWIN
is set.
.Pp
These default actions can be overridden using the functions below:
.Pp
.nr nS 1
.Ft "void"
.Fn AG_FileDlgOkAction "AG_FileDlg *file_dlg" "void (*fn)(AG_Event *)" "const char *fmt" "..."
.Pp
.Ft "void"
.Fn AG_FileDlgCancelAction "AG_FileDlg *file_dlg" "void (*fn)(AG_Event *)" "const char *fmt" "..."
.Pp
.Ft "int"
.Fn AG_FileDlgCheckReadAccess "AG_FileDlg *file_dlg"
.Pp
.Ft "int"
.Fn AG_FileDlgCheckWriteAccess "AG_FileDlg *file_dlg"
.Pp
.nr nS 0
The
.Fn 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
.Ft AG_FileType
structure for the file type selected by the user (see
.Dq STRUCTURE DATA
for details).
.Pp
.Fn AG_FileDlgCancelAction
overrides the default behavior of the "Cancel" button.
.Pp
The utility functions
.Fn AG_FileDlgCheckReadAccess
and
.Fn AG_FileDlgCheckWriteAccess
evaluate whether the selected file is readable or writeable.
.Sh FORMAT-SPECIFIC OPTIONS
In many cases where we are using
.Nm
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
.Ft AG_FileType
objects (as returned by
.Fn AG_FileDlgAddType ) .
Whenever a file type is selected,
.Nm
will automatically display control widgets allowing the user to manipulate
those parameters.
.Pp
.nr nS 1
.Ft "void"
.Fn AG_FileDlgSetOptionContainer "AG_FileDlg *file_dlg" "AG_Widget *container"
.Pp
.Ft "AG_FileOption *"
.Fn AG_FileOptionNewBool "AG_FileType *type" "const char *descr" "const char *key" "int default"
.Pp
.Ft "AG_FileOption *"
.Fn AG_FileOptionNewInt "AG_FileType *type" "const char *descr" "const char *key" "int default" "int min" "int max"
.Pp
.Ft "AG_FileOption *"
.Fn AG_FileOptionNewFlt "AG_FileType *type" "const char *descr" "const char *key" "float default" "float min" "float max" "const char *unit"
.Pp
.Ft "AG_FileOption *"
.Fn AG_FileOptionNewDbl "AG_FileType *type" "const char *descr" "const char *key" "double default" "double min" "double max" "const char *unit"
.Pp
.Ft "AG_FileOption *"
.Fn AG_FileOptionGet "AG_FileType *type" "const char *key"
.Pp
.Ft "int"
.Fn AG_FileOptionBool "AG_FileType *type" "const char *key"
.Pp
.Ft "int"
.Fn AG_FileOptionInt "AG_FileType *type" "const char *key"
.Pp
.Ft "float"
.Fn AG_FileOptionFlt "AG_FileType *type" "const char *key"
.Pp
.Ft "double"
.Fn AG_FileOptionDbl "AG_FileType *type" "const char *key"
.Pp
.nr nS 0
The
.Fn AG_FileDlgSetOptionContainer
function arranges for the given container widget to hold the control
widgets that will be dynamically created.
.Pp
.Fn AG_FileOptionNewBool
registers a boolean option, manipulated by an
.Xr AG_Checkbox 3 .
.Fa descr
is a description string and
.Fa key
is a handle that the save/load routine will use to retrieve the option.
.Fa default
indicates the initial value of the option (1 = true, 0 = false).
.Pp
.Fn AG_FileOptionNewInt
registers an integer option, manipulated by an
.Xr AG_Numerical 3 .
.Fa default
is the initial value,
.Fa min
and
.Fa max
define the bounds.
.Pp
.Fn AG_FileOptionNewFlt
and
.Fn AG_FileOptionNewDbl
register single and double precision floating-point options, using
.Xr AG_Numerical 3 .
.Fa default
is the initial value,
.Fa min
and
.Fa max
define the bounds
and
.Fa unit ,
if not NULL, is the unit system to use (see
.Xr AG_Units 3 ) .
.Pp
.Fn AG_FileOptionGet
returns a pointer to the
.Ft AG_FileOption
structure for the given option name, or NULL if there is no such option.
.Fn AG_FileOptionBool ,
.Fn AG_FileOptionInt ,
.Fn AG_FileOptionFlt
and
.Fn AG_FileOptionDbl
return the value of the given option assuming it exists.
.Pp
.Sh BINDINGS
The
.Nm
widget does not provide any bindings.
.Sh EVENTS
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width "pushed (Cancel button) "
.It dblclick (dir list)
Change the working directory.
.It dblclick (file list)
Select the given file.
If either
.Dv AG_FILEDLG_LOAD
or
.Dv AG_FILEDLG_SAVE
is set, display an error if the file is not readable or writeable.
Otherwise, the
.Sq file-chosen
event is raised.
The widget will also request that its parent window be closed if the
.Dv AG_FILEDLG_CLOSEWIN
flag is set.
.It selected (file list)
Raise the
.Sq file-selected
event.
.It return (text input)
If the entered path is an existing directory, change the working directory.
Otherwise, assume that the path refers to a file and select it.
.Xr glob 3
is used on systems that support it.
.It pushed (OK button)
Select the current file, checking for needed permissions if either
.Dv AG_FILEDLG_LOAD
or
.Dv AG_FILEDLG_SAVE
is set.
Also closes parent window if
.Dv AG_FILEDLG_CLOSEWIN is set.
.It pushed (Cancel button)
Closes the parent window if
.Dv AG_FILEDLG_CLOSEWIN
is set, otherwise a no-op.
.El
.Pp
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -width 2n
.It Fn file-chosen "char *path" "AG_FileType *type"
User has selected the given file.
.Fa path
is the full pathname to the file.
If not NULL,
.Fa type
describes the file type that was selected by the user.
.It Fn file-selected "char *path"
User has moved selection over the given file, where
.Fa path
is the full pathname to it.
This event is typically used by file loader dialogs for previewing file
contents using an external widget.
.It Fn dir-selected "void"
The given directory was selected.
.El
.Sh STRUCTURE DATA
For the
.Ft AG_FileDlg
object:
.Pp
.Bl -tag -width "char cfile[AG_PATHNAME_MAX] " -compact
.It Ft char cwd[AG_PATHNAME_MAX]
Absolute path of current working directory.
.It Ft char cfile[AG_PATHNAME_MAX]
Absolute path of last selected file.
.El
.Pp
For the
.Ft AG_FileType
structure (as returned by
.Fn AG_FileDlgAddType ) :
.Pp
.Bl -tag -width "const char *descr " -compact
.It Ft AG_FileDlg *fd
Back pointer to the parent
.Ft AG_FileDlg
(read-only).
.It Ft const char *descr"
Description string (read-only).
.It Ft AG_Event *action
Callback function (as returned by
.Xr AG_SetEvent 3 )
to invoke when a file of this type is selected for a load/save operation.
.El
.Sh EXAMPLES
See
.Pa demos/loader
in the Agar source distribution.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Limits 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.