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

FreeBSD Manual Pages

  
 
  

home | help 
AG_CONFIG(3)		    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
       application.  This includes user	preferences which are to be  preserved
       after   the   application   has	 exited.    Settings   are  stored  as
       AG_Variable(3) values.

       Library or application-specific data may	also be	stored in the configu-
       ration 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	"bind-
       ings"), 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,
       returning 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 application 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 oc-
       cured.

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
			  itself.  Default is platform-dependent.

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

       STRING tmp-path	  Directory for	temporary files.  Default is platform-
			  dependent  (on  POSIX	platforms, the TMPDIR environ-
			  ment 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			  AG_CONFIG(3)

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

home | help