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 configuration 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.
Library or application-specific data may also be stored in the configuration 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 *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, returning 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 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:
The following Agar-GUI code displays a checkbox controlling the value of "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:
The following code prints the currently configured paths:
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
HISTORY
The
AG_Config interface first appeared in
Agar 1.0.
AG_ConfigFind(), AG_ConfigAddPath(), AG_ConfigSetPath() and
AG_ConfigDelPath() were introduced in
Agar 1.6.0.