NAME

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

Library or application-specific data may also be stored in the configuration 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

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, returning 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

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

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

HISTORY