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.

       Library or application-specific data may	also be	stored in the configu-
       ration  object  as  AG_Variable(3)  values.   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.

INHERITANCE HIERARCHY
       AG_Object(3) -> AG_Config.

INTERFACE
       AG_Config * AG_ConfigObject(void)

       int AG_ConfigLoad(void)

       int AG_ConfigSave(void)

       int AG_ConfigFind(AG_ConfigPathGroup group, const char *filename,  char
       *dst, AG_Size dst_size)

       void  AG_ConfigAddPath(AG_ConfigPathGroup  group,  const	 char *format,
       ...)

       void AG_ConfigAddPathS(AG_ConfigPathGroup group,	const char *pathname)

       void AG_ConfigSetPath(AG_ConfigPathGroup	group, int index,  const  char
       *format,	...)

       void  AG_ConfigSetPathS(AG_ConfigPathGroup group, int index, const char
       *pathname)

       void AG_ConfigDelPath(AG_ConfigPathGroup	 group,	 const	char  *format,
       ...)

       void AG_ConfigDelPathS(AG_ConfigPathGroup group,	const char *pathname)

       AG_ConfigObject() returns a pointer to the global agConfig object.

       AG_ConfigLoad()	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 AG_InitGraphics()).

       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_ConfigFind() function searches a list of	registered  paths  for
       the  given file.	 group may be AG_CONFIG_PATH_DATA (for object and data
       files), or AG_CONFIG_PATH_FONTS (for fonts).  If	filename is found  and
       and  the	 file is accessible, then its absolute pathname	is copied into
       the  fixed-size	buffer	dst_path  (limited  to	dst_len	 bytes),   and
       AG_ConfigFind() returns 0.  If the file cannot be found,	it returns -1.

       AG_ConfigAddPath()   adds  the  specified  directory  to	 the  list  of
       AG_ConfigFind() search paths.

       AG_ConfigSetPath() sets the path	at index idx.  If there	is no such en-
       try but	idx  is	 (last)-1,  then  the  entry  is  created.   Otherwise
       AG_ConfigFind() will fail and return -1.

       AG_ConfigDelPath()  removes the given directory from the	list of	regis-
       tered search paths.

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();

       The following code prints the currently configured paths:

	     char path[AG_PATHNAME_MAX];
	     int i, j;

	     for (i = 0; i < AG_CONFIG_PATH_LAST; i++) {
		     for (j = 0; ; j++)	{
			     if	(AG_ConfigGetPath(i,j, path, sizeof(path))==0) {
				     break;
			     }
			     AG_LabelNew(win, 0, "%s[%d] = %s",
				 agConfigPathGroupNames[i], j, path);
		     }
	     }

SEE ALSO
       AG_Intro(3), AG_Object(3)

HISTORY
       The AG_Config interface first appeared in Agar  1.0.   AG_ConfigFind(),
       AG_ConfigAddPath(),  AG_ConfigSetPath() and AG_ConfigDelPath() were in-
       troduced	in Agar	1.6.0.

Agar 1.7		       December	21, 2022		  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+Ports+14.3.quarterly>

home | help