.\" Copyright (c) 2007-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_CONFIG 3 .Os Agar 1.7 .Sh NAME .Nm AG_Config .Nd agar configuration interface .Sh SYNOPSIS .Bd -literal #include .Ed .Sh DESCRIPTION The .Nm object records configuration settings global to an Agar application. This includes user preferences which are to be preserved after the application has exited. .Pp Library or application-specific data may also be stored in the configuration object as .Xr AG_Variable 3 values. Variable names should not start with "ag_", the prefix is reserved for internal Agar settings. .Pp Note that our .Xr 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. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Nm . .Sh INTERFACE .nr nS 1 .Ft "AG_Config *" .Fn AG_ConfigObject "void" .Pp .Ft "int" .Fn AG_ConfigLoad "void" .Pp .Ft "int" .Fn AG_ConfigSave "void" .Pp .Ft "int" .Fn AG_ConfigFind "AG_ConfigPathGroup group" "const char *filename" "char *dst" "AG_Size dst_size" .Pp .Ft "void" .Fn AG_ConfigAddPath "AG_ConfigPathGroup group" "const char *format" "..." .Pp .Ft "void" .Fn AG_ConfigAddPathS "AG_ConfigPathGroup group" "const char *pathname" .Pp .Ft "void" .Fn AG_ConfigSetPath "AG_ConfigPathGroup group" "int index" "const char *format" "..." .Pp .Ft "void" .Fn AG_ConfigSetPathS "AG_ConfigPathGroup group" "int index" "const char *pathname" .Pp .Ft "void" .Fn AG_ConfigDelPath "AG_ConfigPathGroup group" "const char *format" "..." .Pp .Ft "void" .Fn AG_ConfigDelPathS "AG_ConfigPathGroup group" "const char *pathname" .Pp .nr nS 0 .Fn AG_ConfigObject returns a pointer to the global .Va agConfig object. .Pp .Fn AG_ConfigLoad loads the configuration data from disk, returning 0 on sucess or -1 on failure. It is equivalent to calling .Xr AG_ObjectLoad 3 on the .Va agConfig object. Note that .Fn AG_ConfigLoad must be called after the initialization of all Agar libraries (i.e., if an application uses Agar-GUI, then the .Fn AG_ConfigLoad call must follow .Fn AG_InitGraphics ) . .Pp The .Fn AG_ConfigSave function saves the configuration data to disk, returning 0 on success or -1 on failure. It is equivalent to calling .Xr AG_ObjectSave 3 on the .Va agConfig object. .Pp The .Fn AG_ConfigFind function searches a list of registered paths for the given file. .Fa group may be .Dv AG_CONFIG_PATH_DATA (for object and data files), or .Dv AG_CONFIG_PATH_FONTS (for fonts). If .Fa filename is found and and the file is accessible, then its absolute pathname is copied into the fixed-size buffer .Fa dst_path (limited to .Fa dst_len bytes), and .Fn AG_ConfigFind returns 0. If the file cannot be found, it returns -1. .Pp .Fn AG_ConfigAddPath adds the specified directory to the list of .Fn AG_ConfigFind search paths. .Pp .Fn AG_ConfigSetPath sets the path at index .Fa idx . If there is no such entry but .Fa idx is (last)-1, then the entry is created. Otherwise .Fn AG_ConfigFind will fail and return -1. .Pp .Fn AG_ConfigDelPath removes the given directory from the list of registered search paths. .Sh EXAMPLES The following code sets an integer option and a string. The configuration is then immediately saved to disk: .Bd -literal -offset indent .\" SYNTAX(c) AG_SetInt(agConfig, "my-setting", 1); AG_SetString(agConfig, "my-string", "Foo bar"); AG_ConfigSave(); .Ed .Pp The following Agar-GUI code displays a checkbox controlling the value of "my-setting": .Bd -literal -offset indent .\" SYNTAX(c) AG_Checkbox *cb; cb = AG_CheckboxNew(win, 0, "My setting"); AG_BindVariable(cb, "state", agConfig, "my-setting"); .Ed .Pp 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: .Bd -literal -offset indent .\" SYNTAX(c) int myExtSetting = 0; AG_BindInt(agConfig, "my-ext-setting", &myExtSetting); AG_ConfigLoad(); .Ed .Pp The following code prints the currently configured paths: .Bd -literal -offset indent .\" SYNTAX(c) 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); } } .Ed .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_Object 3 .Sh HISTORY The .Nm interface first appeared in Agar 1.0. .Fn AG_ConfigFind , .Fn AG_ConfigAddPath , .Fn AG_ConfigSetPath and .Fn AG_ConfigDelPath were introduced in Agar 1.6.0.