Home News About Download

Main Page Widgets Data Structures Related Pages Index

Support Contribute Contact Tracker

Ewl_Config: Functions for Manipulating Configuration Data

---

Detailed Description

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.

 # 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

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.

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.

 #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;
 }

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:

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

The colour values would be stored in the config as:

 /color/key = 255 255 255 255

In each case the const char *k parameter is the key to access.

Along with the get operations there are also set operations.

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

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.

Data Structures
struct	Ewl_Config
	Contains Ewl configuration data. More...
Typedefs
typedef Ewl_Config	Ewl_Config
Functions
void	ewl_config_cache_init (void)
int	ewl_config_can_save_system (Ewl_Config *cfg)
	Determines if the user can write the system config file.
void	ewl_config_color_get (Ewl_Config *cfg, const char *k, int *r, int *g, int *b, int *a)
	Retrieve color associated with a key.
void	ewl_config_color_set (Ewl_Config *cfg, const char *k, int r, int g, int b, int a, Ewl_Durability state)
	Set the value of key to the specified color.
void	ewl_config_destroy (Ewl_Config *cfg)
	Destroys the given config structure.
float	ewl_config_float_get (Ewl_Config *cfg, const char *k)
	Retrieve floating point value associated with a key.
void	ewl_config_float_set (Ewl_Config *cfg, const char *k, float v, Ewl_Durability state)
	Set the value of key to the specified float.
int	ewl_config_init (void)
void	ewl_config_instance_key_remove (Ewl_Config *cfg, const char *k)
	Removes the given key from the instance configuration data.
void	ewl_config_instance_keys_remove (Ewl_Config *cfg, const char *k)
	Removes all keys/value pairs from the instance config, which start with the string .
int	ewl_config_int_get (Ewl_Config *cfg, const char *k)
	Retrieve integer value associated with a key.
void	ewl_config_int_set (Ewl_Config *cfg, const char *k, int v, Ewl_Durability state)
	Set the value of key to the specified integer.
void	ewl_config_key_remove (Ewl_Config *cfg, const char *k)
	Removes key from configuration.
Ecore_List *	ewl_config_keys_get (Ewl_Config *cfg, const char *starts_with)
	Returns a list with all keys in the config starting with .
void	ewl_config_keys_remove (Ewl_Config *cfg, const char *k)
	Removes all keys/value pairs from all configs (system, user and instance), which start with the string .
Ewl_Config *	ewl_config_new (const char *app_name)
	Creats the Ewl_Config file for the given application.
void	ewl_config_shutdown (void)
const char *	ewl_config_string_get (Ewl_Config *cfg, const char *k)
	Retrieve string value associated with a key.
void	ewl_config_string_set (Ewl_Config *cfg, const char *k, const char *v, Ewl_Durability state)
	set the value of key to the specified string
void	ewl_config_system_key_remove (Ewl_Config *cfg, const char *k)
	Removes the given key from the system configuration data.
void	ewl_config_system_keys_remove (Ewl_Config *cfg, const char *k)
	Removes all keys/value pairs from the system config, which start with the string .
int	ewl_config_system_save (Ewl_Config *cfg)
	Writes out the system and user data to the system config file.
void	ewl_config_user_key_remove (Ewl_Config *cfg, const char *k)
	Removes the given key from the user configuration data.
void	ewl_config_user_keys_remove (Ewl_Config *cfg, const char *k)
	Removes all keys/value pairs from the user config, which start with the string .
int	ewl_config_user_save (Ewl_Config *cfg)
	Writes out the user config to the users config file.

---

Typedef Documentation

typedef struct Ewl_Config Ewl_Config

The Ewl_Config structure

---

Function Documentation

void ewl_config_cache_init

(

void

)

int ewl_config_can_save_system

(

Ewl_Config *

cfg

)

Determines if the user can write the system config file.

Parameters:

cfg,:

The Ewl_Config to work with

Returns:

Returns TRUE if the user can write to the system conf file, FALSE otherwise

void ewl_config_color_get	(	Ewl_Config *	cfg,
		const char *	k,
		int *	r,
		int *	g,
		int *	b,
		int *	a
	)

Retrieve color associated with a key.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to search
	r,:	the red value that is associated with the key
	g,:	the green value that is associated with the key
	b,:	the blue value that is associated with the key
	a,:	the alpha value that is associated with the key

Returns:

Returns no value

void ewl_config_color_set	(	Ewl_Config *	cfg,
		const char *	k,
		int	r,
		int	g,
		int	b,
		int	a,
		Ewl_Durability	state
	)

Set the value of key to the specified color.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to set in the configuration database
	r,:	the red value that will be associated with the key
	g,:	the green value that will be associated with the key
	b,:	the blue value that will be associated with the key
	a,:	the alpha value that will be associated with the key
	state,:	The state of the key being set, persistent or transient

Returns:

Returns no value

Sets the color value associated with the key k to v in the configuration database.

void ewl_config_destroy

(

Ewl_Config *

cfg

)

Destroys the given config structure.

Parameters:

cfg,:

The Ewl_Config to destroy

Returns:

Returns no value

float ewl_config_float_get	(	Ewl_Config *	cfg,
		const char *	k
	)

Retrieve floating point value associated with a key.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to search

Returns:

Returns the found float value on success, 0.0 on failure.

void ewl_config_float_set	(	Ewl_Config *	cfg,
		const char *	k,
		float	v,
		Ewl_Durability	state
	)

Set the value of key to the specified float.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to set in the configuration database
	v,:	the float value that will be associated with the key
	state,:	The state of the key being set, persistent or transient

Returns:

Returns no value

Sets the float value associated with the key k to v in the configuration database.

int ewl_config_init

(

void

)

void ewl_config_instance_key_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes the given key from the instance configuration data.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	The key to remove

Returns:

Returns no value

void ewl_config_instance_keys_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes all keys/value pairs from the instance config, which start with the string .

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	string that should be matched if the key is going to be removed. Passing "" will remove all keys from the config.

Returns:

Returns no value

int ewl_config_int_get	(	Ewl_Config *	cfg,
		const char *	k
	)

Retrieve integer value associated with a key.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to search

Returns:

Returns the found integer value on success, 0 on failure.

void ewl_config_int_set	(	Ewl_Config *	cfg,
		const char *	k,
		int	v,
		Ewl_Durability	state
	)

Set the value of key to the specified integer.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to set in the configuration database
	v,:	the integer value that will be associated with the key
	state,:	The state of the key being set, persistent or transient

Returns:

Returns TRUE on success, FALSE on failure.

Sets the integer value associated with the key k to v in the configuration database.

void ewl_config_key_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes key from configuration.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	The key to remove

Returns:

Returns no value

Ecore_List* ewl_config_keys_get	(	Ewl_Config *	cfg,
		const char *	starts_with
	)

Returns a list with all keys in the config starting with .

Parameters:

	cfg,:	The Ewl_Config to work with
	starts_with,:	all returned keys will start with it

Returns:

A list with all the matched keys

void ewl_config_keys_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes all keys/value pairs from all configs (system, user and instance), which start with the string .

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	string that should be matched if the key is going to be removed. Passing "" will remove all keys from the config

Returns:

Returns no value

Ewl_Config* ewl_config_new

(

const char *

app_name

)

Creats the Ewl_Config file for the given application.

Parameters:

app_name,:

The name of the app to open the config for

Returns:

Returns the Ewl_Config struct for this app

void ewl_config_shutdown

(

void

)

const char* ewl_config_string_get	(	Ewl_Config *	cfg,
		const char *	k
	)

Retrieve string value associated with a key.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to search

Returns:

Returns the found string value on success, NULL on failure.

void ewl_config_string_set	(	Ewl_Config *	cfg,
		const char *	k,
		const char *	v,
		Ewl_Durability	state
	)

set the value of key to the specified string

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	the key to set in the configuration database
	v,:	the string value that will be associated with the key
	state,:	The state of the key being set, persistent or transient

Returns:

Returns no value.

Sets the string value associated with the key k to v in the configuration database.

void ewl_config_system_key_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes the given key from the system configuration data.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	The key to remove

Returns:

Returns no value

void ewl_config_system_keys_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes all keys/value pairs from the system config, which start with the string .

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	string that should be matched if the key is going to be removed. Passing "" will remove all keys from the config.

Returns:

Returns no value

int ewl_config_system_save

(

Ewl_Config *

cfg

)

Writes out the system and user data to the system config file.

Parameters:

cfg,:

The Ewl_Config to save

Returns:

Returns TRUE on success, FALSE on failure

void ewl_config_user_key_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes the given key from the user configuration data.

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	The key to remove

Returns:

Returns no value

void ewl_config_user_keys_remove	(	Ewl_Config *	cfg,
		const char *	k
	)

Removes all keys/value pairs from the user config, which start with the string .

Parameters:

	cfg,:	The Ewl_Config to work with
	k,:	string that should be matched if the key is going to be removed. Passing "" will remove all keys from the config.

Returns:

Returns no value

int ewl_config_user_save

(

Ewl_Config *

cfg

)

Writes out the user config to the users config file.

Parameters:

cfg,:

The Ewl_Config to work with

Returns:

Returns TRUE on success or FALSE on failure

---

Copyright © Enlightenment.org

Enlightened Widget Library Documentation Generated: Sun Sep 27 01:49:46 2009