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 ap-
     plication.  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 configura-
     tion 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 "bindings"), 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 *for-
     mat, ...)

     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,  return-
     ing  0 on success or -1 on failure.  It is equivalent to calling AG_Object-
     Save(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_Con-
     figFind() search paths.

     AG_ConfigSetPath()  sets  the path at index idx.  If there is no such entry
     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 registered
     search paths.

EXAMPLES
     The following code sets an integer option and a string.  The  configuration
     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 intro-
     duced 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+15.1.quarterly>

home | help