Enlightenment CVS committal
Author : dj2
Project : e17
Module : libs/ewl
Dir : e17/libs/ewl/doc/tutorials/widgets
Modified Files:
ewl_config.dox
Log Message:
- add config tutorial
===================================================================
RCS file: /cvs/e/e17/libs/ewl/doc/tutorials/widgets/ewl_config.dox,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -3 -r1.1 -r1.2
--- ewl_config.dox 26 Feb 2008 04:24:10 -0000 1.1
+++ ewl_config.dox 26 Feb 2008 05:42:14 -0000 1.2
@@ -1,4 +1,163 @@
/**
* @addtogroup Ewl_Config
* @section config_tut Tutorial
+ *
+ * The configuration system in Ewl based around Ewl_Config, is designed to
+ * handle the configuration requirements of Ewl and any applications based
+ * off of Ewl. All of the configuration information is stored in plain text
+ * files. You can also define system-wide and user specific settings. It is
+ * also possible to set temporary settings that won't be saved back to
permanent storage.
+ *
+ * Ewl stores its configuration information in the ewl.cfg file. This file
+ * will be located in <prefix>/etc/ewl.cfg. If the user wishes to set
+ * overrides they can be placed in $HOME/.ewl/config/ewl.cfg.
+ *
+ * @code
+ * # Ewl default configuration file.
+ *
+ * #/ewl/debug/enable = 0
+ * #/ewl/debug/level = 0
+ * #/ewl/debug/segv = 0
+ * #/ewl/debug/backtrace = 0
+ * #/ewl/debug/evas/render = 0
+ * #/ewl/debug/gc/reap = 0
+ * #/ewl/theme/print/keys = 0
+ * #/ewl/theme/print/signals = 0
+ *
+ * /ewl/cache/evas/font = 2097152
+ * /ewl/cache/evas/image = 8388608
+ *
+ * /ewl/engine/name = evas_software_x11
+ *
+ * /ewl/theme/name = e17
+ * /ewl/theme/icon/theme = Tango
+ * /ewl/theme/icon/size = 22
+ * @endcode
+ *
+ * You can view the Ewl command line flags, assuming you've passed the argc
and
+ * argv variables to ewl_init, by passing --ewl-help on the command line.
+ *
+ * Any line beginning with a # symbol is ignored. Ewl typically uses a
hierarchical
+ * key name layout to make life simpler.
+ *
+ * It is also possible to override some of these settings on the command line
through
+ * the use of command line flags. The command line settings will be used
during the
+ * current session but not saved back to the configuration files.
+ *
+ * @section Application Configuration
+ * You can hook into the Ewl_Config system to create configuration data
+ * for your own application. This will provide you with the system-wide,
+ * user specific and allow you to override based on your command line switches.
+ *
+ * Your configuration files will be stored in <ewl
prefix>/etc/ewl/apps/<name>.cfg
+ * for the global settings and $HOME/.ewl/config/apps/<name>.cfg for the user
+ * specific settings.
+ *
+ * Below is a simple example of loading an apps configuration data, reading
+ * some values, setting some values and saving everything back again.
+ *
+ * Below is an example of using Ewl_Config in your application. I'll give the
+ * complete listing and then explain what's going on afterwards.
+ *
+ * @code
+ * #include <Ewl.h>
+ * #include <stdio.h>
+ *
+ * int
+ * main(int argc, char ** argv)
+ * {
+ * Ewl_Config *cfg;
+ * int r, g, b, a;
+ *
+ * if (!ewl_init(&argc, argv))
+ * {
+ * fprintf(stderr, "Failed to initialize Ewl.\n");
+ * return 1;
+ * }
+ *
+ * if (!(cfg = ewl_config_new("application name")))
+ * {
+ * fprintf(stderr, "Failed to read configuration data.\n");
+ * ewl_shutdown();
+ * return 1;
+ * }
+ *
+ * printf("String %s\n", ewl_config_string_get(cfg, "/path/to/string");
+ * printf("Int %d\n", ewl_config_inti_get(cfg, "/path/to/int");
+ *
+ * ewl_config_color_get(cfg, "/path/to/color", &r, &g, &b, &a);
+ *
+ * ewl_config_string_set(cfg, "/path/to/set", "string to set",
EWL_STATE_PERSISTENT);
+ * ewl_config_int_set(cfg, "/path/to/tmp/int", 10, EWL_STATE_TRANSIENT);
+ *
+ * if (ewl_config_can_save_system(cfg))
+ * ewl_config_system_save(cfg);
+ * else
+ * ewl_config_user_save(cfg);
+ *
+ * ewl_config_destroy(cfg);
+ * ewl_shutdown();
+ * return 0;
+ * }
+ * @endcode
+ *
+ * I'm going to skip over the common Ewl stuff and just focus on the
Ewl_Config
+ * code in there. All of your application data will be stored in the
Ewl_Config *cfg
+ * variable. We'll need to pass this to each of the Ewl_Config calls we make.
+ *
+ * The first step is to initialize our configuration data. This is done by
+ * calling Ewl_config *ewl_config_new(const char *app_name);. This will look
+ * for a configuation file with the name <app name>.cfg in the directories
+ * listed above. The system values will be loaded first, then any user values
+ * will be loaded to override.
+ *
+ * With the configuration successfully loaded we can now start getting values
+ * out of it. There are currently four calls to get information:
+ *
+ * @code
+ * const char *ewl_config_string_get(Ewl_Config *cfg, const char *k);
+ * int ewl_config_int_get(Ewl_Config *cfg, const char *k);
+ * float ewl_config_float_get(Ewl_Config *cfg, const char *k);
+ * void ewl_config_color_get(Ewl_Config *cfg, const char *k,
+ * int *r, int *g, int *b, int *a);
+ * @endcode
+ *
+ * The colour values would be stored in the config as:
+ * @code
+ * /color/key = 255 255 255 255
+ * @endcode
+ *
+ * In each case the const char *k parameter is the key to access.
+ *
+ * Along with the get operations there are also set operations.
+ *
+ * @code
+ * void ewl_config_string_set(Ewl_Config *cfg, const char *k,
+ * const char *v, Ewl_State_Type state);
+ * void ewl_config_int_set(Ewl_Config *cfg, const char *k,
+ * int v, Ewl_State_Type state);
+ * void ewl_config_float_set(Ewl_Config *cfg, const char *k,
+ * float v, Ewl_State_Type state);
+ * void ewl_config_color_set(Ewl_Config *cfg, const char *k,
+ * int r, int g, int b, int a,
+ * Ewl_State_Type state);
+ * @endcode
+ *
+ * These are all pretty self explanatory except, possibly, for the
Ewl_State_Type
+ * state setting for each call. The state lets you tell Ewl if the set value
+ * should be saved to disk on a save call, or if it's only for this run of
+ * the application. The possible settings are:
+ *
+ * EWL_STATE_TRANSIENT :: The value will not be saved to disk
+ *
+ * EWL_STATE_PERSISTENT :: The value will be saved to disk
+ *
+ * By using the states you can set your command line flags into the
configuration
+ * data and not have to worry about them being stored by accident.
+ *
+ * If you allow the user to change the application configuration settings
+ * you'll probably want to save those settings back to disk. You can save
+ * to the system directory or the user directory, depending on user
privileges.
+ * You don't have to try to save to the system directory, you can always just
+ * store to the user directory.
*/
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
enlightenment-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
