visu_configFile

visu_configFile — Defines methods to access (read/write) to config files and to create different entries.

Synopsis

#define             VISU_CONFIG_FILE_PARAMETER
#define             VISU_CONFIG_FILE_RESOURCE
                    VisuConfigFileEntry;
void                (*VisuConfigFileExportFunc)         (GString *data,
                                                         VisuData *dataObj,
                                                         VisuGlView *view);
struct              VisuConfigFileForeachFuncExport;
gboolean            (*VisuConfigFileReadFunc)           (VisuConfigFileEntry *entry,
                                                         gchar **lines,
                                                         int nbLines,
                                                         int position,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);
VisuConfigFileEntry * visu_config_file_addBooleanEntry  (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         gboolean *location);
VisuConfigFileEntry * visu_config_file_addEntry         (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         int nbLines,
                                                         VisuConfigFileReadFunc readFunc);
void                visu_config_file_addExportFunction  (int kind,
                                                         VisuConfigFileExportFunc writeFunc);
VisuConfigFileEntry * visu_config_file_addFloatArrayEntry
                                                        (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         guint nValues,
                                                         float *location,
                                                         float clamp[2]);
void                visu_config_file_addKnownTag        (gchar *tag);
VisuConfigFileEntry * visu_config_file_addStringEntry   (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         gchar **location);
void                visu_config_file_entry_setReplace   (VisuConfigFileEntry *newEntry,
                                                         VisuConfigFileEntry *oldEntry);
void                visu_config_file_entry_setTag       (VisuConfigFileEntry *entry,
                                                         const gchar *tag);
void                visu_config_file_entry_setVersion   (VisuConfigFileEntry *entry,
                                                         float version);
void                visu_config_file_exportComment      (GString *buffer,
                                                         const gchar *comment);
void                visu_config_file_exportEntry        (GString *buffer,
                                                         const gchar *name,
                                                         const gchar *id_value,
                                                         const gchar *format_,
                                                         ...);
gboolean            visu_config_file_exportToXML        (const gchar *filename,
                                                         int kind,
                                                         GError **error);
const gchar *       visu_config_file_getDefaultFilename (int kind);
GList *             visu_config_file_getEntries         (int kind);
gchar *             visu_config_file_getNextValidPath   (int kind,
                                                         int accessMode,
                                                         GList **list,
                                                         int utf8);
GList *             visu_config_file_getPathList        (int kind);
const gchar *       visu_config_file_getPathToResources ();
gchar *             visu_config_file_getValidPath       (int kind,
                                                         int mode,
                                                         int utf8);
gboolean            visu_config_file_load               (int kind,
                                                         const char *filename,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);
gboolean            visu_config_file_save               (int kind,
                                                         const char *fileName,
                                                         int *lines,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);
gboolean            visu_config_file_saveResourcesToXML (const char *filename,
                                                         int *lines,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);

Object Hierarchy

  GBoxed
   +----VisuConfigFileEntry

Description

V_Sim uses two different configuration files. The first stores the configuration of the program itself and is called parameters file. The second stores differents values that control the way files are rendered. It is called resources file. For example, their is an entry in the parameters file that controls your favorite rendering method ; and there is an entry in the resources file that codes that vacancy elements are rendered by cube in the atomic rendering method. Most methods of this part uses a first argument usually called 'kind', that control if the method will apply on the parameters file or on the resources file. VISU_CONFIG_FILE_PARAMETER and VISU_CONFIG_FILE_RESOURCE are the two flags that should be used for the 'kind' argument.

There are different paths where these files can be stored. These paths are stored in V_Sim with an order : for example parameters file are first looked for in the current working directory, then in the $HOME/.v_sim directory and finally in the installation directory. This is transparent for the user and visu_config_file_getValidPath() is the right method to access to the best readable configuration file.

Different part of V_Sim can add entries in these files. The method visu_config_file_addEntry() is designed to this purpose. The entries are defined by their name and they appear in the configuration file as 'name:' followed by the data associated to this entry. In the parameters file, the data are on the same line. In the resources file, the data begin the line after and can be longer that one line. When a configuration file is read, the method associated to each entry (VisuConfigFileReadFunc()) is called with a copy of their data lines. The method visu_config_file_addExportFunction() should be used to add a callback when the configurations files are written, then each part of V_Sim that have entries can put some lines in the configuration files.

Details

VISU_CONFIG_FILE_PARAMETER

#define VISU_CONFIG_FILE_PARAMETER 0

This defines a parameter entry in the config files.


VISU_CONFIG_FILE_RESOURCE

#define VISU_CONFIG_FILE_RESOURCE 1

This defines a resource entry in the config files.


VisuConfigFileEntry

typedef struct _VisuConfigFileEntry VisuConfigFileEntry;

This is the common name of the structure.


VisuConfigFileExportFunc ()

void                (*VisuConfigFileExportFunc)         (GString *data,
                                                         VisuData *dataObj,
                                                         VisuGlView *view);

This prototype defines a method that is used to export some resources or parameters. The data argument is an empty GString where the export has to be written. If the argument dataObj is not null, only resources related to the VisuData object should be exported (for parameters files, dataObj is always NULL).

data :

an empty GString to store the export ;

dataObj :

a VisuData object ;. [allow-none]

view :

a VisuGlView object. [allow-none]

struct VisuConfigFileForeachFuncExport

struct VisuConfigFileForeachFuncExport {
  GString *data;
  VisuData *dataObj;
};

This structure can be used to encapsulate the arguments of an export method when used in a foreach glib loop.

GString *data;

the string where the values are exported to ;

VisuData *dataObj;

the current VisuData object, values are related to.

VisuConfigFileReadFunc ()

gboolean            (*VisuConfigFileReadFunc)           (VisuConfigFileEntry *entry,
                                                         gchar **lines,
                                                         int nbLines,
                                                         int position,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);

This prototype corresponds to methods called when an entry is found. The lines argument is an array of lines read from the files. These strings are copies and can be modified but not freed. There are nbLines and this value correspond to the number of lines defined for the entry. The error argument is used to store some text messages and error ids. They should be in UTF8. The error argument must be initialised with (GError*)0. The position argument give the number of the first line given in lines argument. If the dataObj argument is not null, some updates should be done with read values.

entry :

the VisuConfigFileEntry that raises this callback.

lines :

an array of strings ;

nbLines :

an integer ;

position :

an integer ;

dataObj :

a VisuData object ;. [allow-none]

view :

a VisuGlView object. [allow-none]

error :

a pointer to a GError pointer.

Returns :

TRUE if everything goes right, FALSE otherwise.

visu_config_file_addBooleanEntry ()

VisuConfigFileEntry * visu_config_file_addBooleanEntry  (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         gboolean *location);

Defines a VisuConfigFileEntry that will be a single boolean to read and to store in location.

kind :

an integer ;

key :

a string (should not be NULL) ;

description :

a string (can be NULL) ;. [allow-none]

location :

a pointer where to store a boolean when the entry is parsed.

Returns :

the newly created VisuConfigFileEntry object. [transfer full]

Since 3.7


visu_config_file_addEntry ()

VisuConfigFileEntry * visu_config_file_addEntry         (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         int nbLines,
                                                         VisuConfigFileReadFunc readFunc);

This creates a new VisuConfigFileEntry object with the given values. The key and description arguments are copied.

kind :

an integer ;

key :

a string (should not be NULL) ;

description :

a string (can be NULL) ;. [allow-none]

nbLines :

an integer ;

readFunc :

a VisuConfigFileReadFunc. [scope call]

Returns :

the newly created VisuConfigFileEntry object.

visu_config_file_addExportFunction ()

void                visu_config_file_addExportFunction  (int kind,
                                                         VisuConfigFileExportFunc writeFunc);

This stores the writeFunc given. It will be called when resources or parameters will be exported to disk.

kind :

an integer to identify resources or parameters ;

writeFunc :

a VisuConfigFileExportFunc method. [scope call]

visu_config_file_addFloatArrayEntry ()

VisuConfigFileEntry * visu_config_file_addFloatArrayEntry
                                                        (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         guint nValues,
                                                         float *location,
                                                         float clamp[2]);

Defines a VisuConfigFileEntry that will parse nValues floats and store them consecutively in location. The parsed values are checked to be in clamp.

kind :

an integer ;

key :

a string (should not be NULL) ;

description :

a string (can be NULL) ;. [allow-none]

nValues :

the number of floats to read.

location :

a pointer where to store floats when the entry is parsed.

clamp :

the min and max values allowed.

Returns :

the newly created VisuConfigFileEntry object. [transfer full]

Since 3.7


visu_config_file_addKnownTag ()

void                visu_config_file_addKnownTag        (gchar *tag);

If parameter entries have a tag, they are ignored except if their tag has been declared using this method.

tag :

a string (not nul or empty).

visu_config_file_addStringEntry ()

VisuConfigFileEntry * visu_config_file_addStringEntry   (int kind,
                                                         const gchar *key,
                                                         const gchar *description,
                                                         gchar **location);

Defines a VisuConfigFileEntry that will be a string to read and to store in location. If location already contains a string, it is g_free().

kind :

an integer ;

key :

a string (should not be NULL) ;

description :

a string (can be NULL) ;. [allow-none]

location :

a pointer where to store a string when the entry is parsed.

Returns :

the newly created VisuConfigFileEntry object. [transfer full]

Since 3.7


visu_config_file_entry_setReplace ()

void                visu_config_file_entry_setReplace   (VisuConfigFileEntry *newEntry,
                                                         VisuConfigFileEntry *oldEntry);

Use this method to declare that oldEntry has become obsolete and has been replaced by newEntry.

newEntry :

a VisuConfigFileEntry object ;

oldEntry :

idem.

visu_config_file_entry_setTag ()

void                visu_config_file_entry_setTag       (VisuConfigFileEntry *entry,
                                                         const gchar *tag);

This method is used to set a tag to the given entry. This tag is used to ignore or not the entry when the file is read. The tag argument is copied.

entry :

a VisuConfigFileEntry object ;

tag :

a string.

visu_config_file_entry_setVersion ()

void                visu_config_file_entry_setVersion   (VisuConfigFileEntry *entry,
                                                         float version);

Set the version number the entry appear in.

entry :

a VisuConfigFileEntry object ;

version :

the version the entry appear in.

visu_config_file_exportComment ()

void                visu_config_file_exportComment      (GString *buffer,
                                                         const gchar *comment);

Append to buffer the given comment, using the current output style (raw text or XML as instance).

buffer :

the buffer to add a comment to.

comment :

a comment.

Since 3.7


visu_config_file_exportEntry ()

void                visu_config_file_exportEntry        (GString *buffer,
                                                         const gchar *name,
                                                         const gchar *id_value,
                                                         const gchar *format_,
                                                         ...);

Append to buffer the given entry, using the current output style (raw text or XML as instance). id_value can be used to specify the entry apply to, for instance, the name of the VisuElement the colour property entry apply to.

buffer :

the buffer to write the entry to.

name :

the name of the entry.

id_value :

an id for the entry. [allow-none]

format_ :

the formatting string for the message.

... :

the values to print.

Since 3.7


visu_config_file_exportToXML ()

gboolean            visu_config_file_exportToXML        (const gchar *filename,
                                                         int kind,
                                                         GError **error);

Export all the registered entries for resources or parameters to an XML file.

filename :

a string in the encoding of the file system ;

kind :

either VISU_CONFIG_FILE_PARAMETER or VISU_CONFIG_FILE_RESOURCE ;

error :

a location to store an error.

Returns :

TRUE if the file is written with success.

visu_config_file_getDefaultFilename ()

const gchar *       visu_config_file_getDefaultFilename (int kind);

This methods is used to get the filename used for different config files.

kind :

an integer identifier.

Returns :

the filename of config file. The returned *gchar is owned by V_Sim and should not be freed or modified.

visu_config_file_getEntries ()

GList *             visu_config_file_getEntries         (int kind);

This routine should be used for introspections purpose, to know what resources or parameters are available.

kind :

either VISU_CONFIG_FILE_PARAMETER or VISU_CONFIG_FILE_RESOURCE ;

Returns :

a GList own by V_Sim. [element-type utf8][transfer none]

visu_config_file_getNextValidPath ()

gchar *             visu_config_file_getNextValidPath   (int kind,
                                                         int accessMode,
                                                         GList **list,
                                                         int utf8);

Test the entries of the given list to find a valid position to read or write a config file. It tests access for the specified file. After a call to this method the list argument points to the next entry in the list, after the one found.

kind :

an integer identifier ;

accessMode :

a value from R_OK, W_OK and X_OK as described in unistd.h ;

list :

a pointer to a valid *GList ;. [element-type filename][inout][transfer none]

utf8 :

if 1, the path is return in UTF-8 format, otherwise, the locale of the file system is used.

Returns :

the first valid path find in the given list of paths.

visu_config_file_getPathList ()

GList *             visu_config_file_getPathList        (int kind);

V_Sim stores a list of paths where to look for resources or parameters files, this method is used to get these lists.

kind :

an integer identifier.

Returns :

the list of the parameters or resources paths. This list is read-only. [transfer none][element-type filename]

visu_config_file_getPathToResources ()

const gchar *       visu_config_file_getPathToResources ();

The resource file can be read from different places.

Returns :

the path used to read the last resource file.

Since 3.6


visu_config_file_getValidPath ()

gchar *             visu_config_file_getValidPath       (int kind,
                                                         int mode,
                                                         int utf8);

Test the entries of the hadoc list to find a valid position to read or write a config file. It tests access for the specified file.

kind :

an integer identifier ;

mode :

a value from R_OK, W_OK and X_OK as described in unistd.h.

utf8 :

if 1, the path is return in UTF-8 format, otherwise, the locale of the file system is used.

Returns :

the first valid path find in the list of known paths.

visu_config_file_load ()

gboolean            visu_config_file_load               (int kind,
                                                         const char *filename,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);

Try to load the resources/parameters from the file name given in parameter.

kind :

an integer to identify the kind of file ;

filename :

the path to file to read ;

dataObj :

a VisuData object, sometime needed to update values (can be NULL) ;. [allow-none]

view :

a VisuGlView object, sometime needed to update values (can be NULL). [allow-none]

error :

a pointer to a GError pointer. [allow-none]

Returns :

TRUE if everything goes right. If error is not NULL it should be freed with g_error_free().

visu_config_file_save ()

gboolean            visu_config_file_save               (int kind,
                                                         const char *fileName,
                                                         int *lines,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);

Try to export the resources/parameters to the file name given in parameter. If lines argument is not NULL, and everything went right, it stores the number of written lines. If the argument dataObj is not null, only resources related to the VisuData object should be exported (for parameters files, dataObj is always NULL). The same for view.

kind :

an integer to identify the kind of file ;

fileName :

the path to file to read ;

lines :

a pointer to an integer (can be NULL) ;

dataObj :

a VisuData object (can be NULL) ;. [allow-none]

view :

a VisuGlView object (can be NULL) ;. [allow-none]

error :

a location to store a possible error.

Returns :

TRUE if everything goes right.

visu_config_file_saveResourcesToXML ()

gboolean            visu_config_file_saveResourcesToXML (const char *filename,
                                                         int *lines,
                                                         VisuData *dataObj,
                                                         VisuGlView *view,
                                                         GError **error);

Same routine as visu_config_file_save() but use an XML format instead.

filename :

the path to file to read ;

lines :

a pointer to an integer (can be NULL) ;

dataObj :

a VisuData object (can be NULL) ;. [allow-none]

view :

a VisuGlView object (can be NULL) ;. [allow-none]

error :

a location to store a possible error.

Returns :

TRUE if everything goes right.

Since 3.7