Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_DIRDLG(3)		     Library Functions Manual		    AG_DIRDLG(3)

NAME
     AG_DirDlg -- agar directory browser widget

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

DESCRIPTION
     The  AG_DirDlg  widget is a directory selection widget.  It provides an in-
     terface similar to AG_FileDlg(3) but restricts selection to directories.

INHERITANCE HIERARCHY
     AG_Object(3)-> AG_Widget(3)-> AG_DirDlg.

INITIALIZATION
     AG_DirDlg * AG_DirDlgNew(AG_Widget *parent, Uint flags)

     AG_DirDlg * AG_DirDlgNewMRU(AG_Widget *parent,  const  char  *mruKey,  Uint
     flags)

     int AG_DirDlgSetDirectory(AG_DirDlg *dd, const char *format, ...)

     int AG_DirDlgSetDirectoryS(AG_DirDlg *dd, const char *path)

     void AG_DirDlgSetDirectoryMRU(AG_DirDlg *dd, const char *mruKey, const char
     *defaultDir)

     The  AG_DirDlgNew()  function  allocates,	initializes,  and attaches a new
     AG_DirDlg	widget.   The  AG_DirDlgNewMRU()   variant   implicitely   calls
     AG_DirDlgSetDirectoryMRU()  with the given key.  Note that unless AG_DirDl-
     gSetDirectory() is used (see below), the default directory is set according
     to the AG_CONFIG_PATH_DATA setting of AG_Config(3).

     Acceptable flags include:

     AG_DIRDLG_MULTI	   Allow multiple directories to be selected at once.

     AG_DIRDLG_CLOSEWIN    Automatically close	the  AG_DirDlg	widget's  parent
			   window when a directory is selected.

     AG_DIRDLG_LOAD	   The	selected  directory must exist and be accessible
			   or an error is returned to the user.

     AG_DIRDLG_SAVE	   The selected directory must be writeable or an  error
			   is returned to the user.

     AG_DIRDLG_NOBUTTONS   Don't display "OK" and "Cancel" buttons.

     AG_DIRDLG_HFILL	   Expand horizontally in parent container.

     AG_DIRDLG_VFILL	   Expand vertically in parent container.

     AG_DIRDLG_EXPAND	   Shorthand for AG_DIRDLG_HFILL | AG_DIRDLG_VFILL.

     The  active  directory can be set programmatically with the AG_DirDlgSetDi-
     rectory() function.

     The AG_DirDlgSetDirectoryMRU() 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.foodir').  If AG_DirDlgSetDirectoryMRU() is used, subsequent di-
     rectory  changes  will  cause the current AG_Config(3) settings to be saved
     automatically.

OK/CANCEL ACTIONS
     By default, selecting a directory will trigger the following checks:

     1.   If AG_DIRDLG_LOAD or AG_DIRDLG_SAVE is set, check whether  the  direc-
	  tory is accessible or writeable.
     2.   Select the directory, raising a `dir-chosen' event.
     3.   If AG_DIRDLG_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_DIRDLG_CLOSEWIN is set.

     These default actions can be overridden using the functions below:

     void AG_DirDlgOkAction(AG_DirDlg *dd, void (*fn)(AG_Event	*),  const  char
     *fmt, ...)

     void  AG_DirDlgCancelAction(AG_DirDlg  *dd,  void	(*fn)(AG_Event *), const
     char *fmt, ...)

     int AG_DirDlgCheckReadAccess(AG_DirDlg *dd)

     int AG_DirDlgCheckWriteAccess(AG_DirDlg *dd)

     The AG_DirDlgOkAction() function configures an event  handler  function  to
     invoke  when a directory is selected, overriding the default behavior.  The
     event handler will be passed a string argument containing the absolute path
     to the selected directory.

     AG_DirDlgCancelAction() overrides the default behavior of the "Cancel" but-
     ton.

     The utility functions AG_DirDlgCheckReadAccess() and AG_DirDlgCheckWriteAc-
     cess() evaluate whether the selected directory is readable or writeable.

BINDINGS
     The AG_DirDlg widget does not provide any bindings.

EVENTS
     The AG_DirDlg widget generates the following events:

     dir-chosen(char *path)
	 The user has selected the given directory.  path is the  full	pathname
	 to the directory.

     dir-selected(char *path)
	 The user has browsed to the given directory.

STRUCTURE DATA
     For the AG_DirDlg object:

     char cwd[AG_PATHNAME_MAX]	 Absolute path of current working directory.

EXAMPLES
     See tests/loader.c in the Agar source distribution.

SEE ALSO
     AG_FileDlg(3), AG_Intro(3), AG_Limits(3), AG_Widget(3), AG_Window(3)

HISTORY
     The AG_DirDlg widget first appeared in Agar 1.4.1.

Agar 1.7			December 21, 2022		    AG_DIRDLG(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_DirDlg&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help