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

FreeBSD Manual Pages

  
 
  

home | help
AG_CONFIG(3)	       FreeBSD Library Functions Manual		  AG_CONFIG(3)

NAME
     AG_Config -- agar configuration interface

SYNOPSIS
     #include <agar/core.h>

DESCRIPTION
     The AG_Config object records configuration	settings global	to an Agar ap-
     plication.	 This includes user preferences	which are to be	preserved af-
     ter the application has exited.  Settings are stored as AG_Variable(3)
     values.

     Library or	application-specific data may also be stored in	the configura-
     tion object.  Variable names should not start with	"ag_", the prefix is
     reserved for internal Agar	settings.

     Note that our AG_Variable(3) system implements pointers (or "bindings"),
     so	it is always possible for a parameter value to be specified as a
     pointer to	an external piece of data.

INTERFACE
     AG_Config * AG_ConfigObject(void)

     int AG_ConfigLoad(void)

     int AG_ConfigSave(void)

     int AG_ConfigFile(const char *path_key, const char	*name, const char
     *extension, char *dst_path, size_t	dst_len)

     The AG_ConfigObject() function returns a pointer to the global AG_Config
     object.

     The AG_ConfigLoad() function loads	the configuration data from disk, re-
     turning 0 on sucess or -1 on failure.  It is equivalent to	calling
     AG_ObjectLoad(3) on the agConfig object.  Note that AG_ConfigLoad() must
     be	called after the initialization	of all Agar libraries (i.e., if	an ap-
     plication uses Agar-GUI, then the AG_ConfigLoad() call must follow	the
     AG_InitGraphics() call).

     The AG_ConfigSave() function saves	the configuration data to disk,	re-
     turning 0 on success or -1	on failure.  It	is equivalent to calling
     AG_ObjectSave(3) on the agConfig object.

     The AG_ConfigFile() utility routine searches a colon-separated pathname
     setting (i.e., `load-path') for a file with the given name	and extension.
     If	the file is found, its full pathname is	copied into a target fixed-
     size buffer dst_path (limited to dst_len bytes).  AG_ConfigFile() returns
     0 if the file exists, or -1 if an error occured.

CONFIGURATION PARAMETERS
     The following parameters are registered by	Agar-Core:

     BOOL initial-run	Application is being ran for the first time (read-
			only).

     STRING load-path	Directory containing data files	for the	AG_Object(3)
			virtual	filesystem, as well as the AG_Config data it-
			self.  Default is platform-dependent.

     STRING save-path	Target directory for writing the AG_Object(3) virtual
			filesystem (usually the	same as	`load-path').

     STRING tmp-path	Directory for temporary	files.	Default	is platform-
			dependent (on POSIX platforms, the TMPDIR environment
			variable is honored).

EXAMPLES
     The following code	sets an	integer	option and a string.  The configura-
     tion is then immediately saved to disk:

	   AG_SetInt(agConfig, "my-setting", 1);
	   AG_SetString(agConfig, "my-string", "Foo bar");
	   AG_ConfigSave();

     The following Agar-GUI code displays a checkbox controlling the value of
     "my-setting":

	   AG_Checkbox *cb;

	   cb =	AG_CheckboxNew(win, 0, "My setting");
	   AG_BindVariable(cb, "state",	agConfig, "my-setting");

     The following code	binds "my-ext-setting" to an external variable,	and
     then reads	the configuration from disk.  If the saved configuration has
     "my-ext-setting" defined, then the	variable will be set accordingly:

	   int myExtSetting = 0;

	   AG_BindInt(agConfig,	"my-ext-setting", &myExtSetting);
	   AG_ConfigLoad();

SEE ALSO
     AG_Intro(3), AG_Object(3)

HISTORY
     The AG_Config interface first appeared in Agar 1.0

FreeBSD	13.0			 June 17, 2007			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | CONFIGURATION PARAMETERS | EXAMPLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Config&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help