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
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.
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.
The following parameters are registered by Agar-Core:
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 AG_Config interface first appeared in Agar 1.0|