Top | ![]() |
![]() |
![]() |
![]() |
VisuConfigFileVisuConfigFile — Defines methods to access (read/write) to config files and to create different entries. |
enum | VisuConfigFileKind |
struct | VisuConfigFileClass |
#define | VISU_CONFIG_FILE_RESOURCE |
#define | VISU_CONFIG_FILE_PARAMETER |
struct | VisuConfigFileForeachFuncExport |
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.
VisuConfigFile *
visu_config_file_getStatic (VisuConfigFileKind kind
);
Retrieve the instance used by V_Sim to read resource or parameter files.
Since: 3.8
gboolean (*VisuConfigFileReadFunc) (VisuConfigFileEntry *entry
,gchar **lines
,int nbLines
,int position
,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.
entry |
the VisuConfigFileEntry that raises this callback. |
|
lines |
an array of strings ; |
|
nbLines |
an integer ; |
|
position |
an integer ; |
|
error |
a pointer to a GError pointer. |
void (*VisuConfigFileExportFunc) (GString *data
,VisuData *dataObj
);
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).
gboolean (*VisuConfigFileEnumFunc) (const gchar *label
,guint *value
);
Try to match label
with a enum value
.
Since: 3.8
VisuConfigFileEntry * visu_config_file_addEntry (VisuConfigFile *conf
,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.
conf |
a VisuConfigFile object ; |
|
key |
a string (should not be NULL) ; |
|
description |
a string (can be NULL) ;. |
[allow-none] |
nbLines |
an integer ; |
|
readFunc |
a VisuConfigFileReadFunc. |
[scope call] |
VisuConfigFileEntry * visu_config_file_ignoreEntry (VisuConfigFile *conf
,const gchar *key
,guint nbLines
);
Create a VisuConfigFileEntry that will ignore key
when found in a
configuration file. This is used for deprecated keys.
Since: 3.8
VisuConfigFileEntry * visu_config_file_addTokenizedEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,gboolean labelled
);
Defines a new VisuConfigFileEntry object characterized by
key
. When key
is found in a configuration file, the data line is
separated into tokens that can be retrieved later with
visu_config_file_entry_popToken()
for instance. If labelled
is
TRUE
, the associated label to an entry in the file can be later
retrieved with visu_config_file_entry_getLabel()
.
conf |
a VisuConfigFile object ; |
|
key |
a string (should not be |
|
description |
a string (can be |
[allow-none] |
labelled |
a boolean. |
Since: 3.8
VisuConfigFileEntry * visu_config_file_addBooleanEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,gboolean *location
,gboolean labelled
);
Defines a VisuConfigFileEntry that will be a single boolean to
read and to store in location
. If labelled
is TRUE
, it retrieves
and store a string before the boolean value. It can be accessed
later with visu_config_file_entry_getLabel()
.
conf |
a VisuConfigFile object ; |
|
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. |
|
labelled |
a boolean. |
Since: 3.7
VisuConfigFileEntry * visu_config_file_addBooleanArrayEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,guint nValues
,gboolean *location
,gboolean labelled
);
Defines a VisuConfigFileEntry that will be several booleans to
read and to store in location
. If labelled
is TRUE
, it retrieves
and store a string before the boolean value. It can be accessed
later with visu_config_file_entry_getLabel()
.
conf |
a VisuConfigFile object ; |
|
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 booleans when the entry is parsed. |
|
labelled |
a boolean. |
Since: 3.8
VisuConfigFileEntry * visu_config_file_addIntegerArrayEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,guint nValues
,int *location
,int clamp[2]
,gboolean labelled
);
Defines a VisuConfigFileEntry that will parse nValues
usable for stipple and
store them consecutively in location
.
conf |
a VisuConfigFile object ; |
|
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. |
|
labelled |
TRUE if the entry has a label. |
Since: 3.8
VisuConfigFileEntry * visu_config_file_addFloatArrayEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,guint nValues
,float *location
,float clamp[2]
,gboolean labelled
);
Defines a VisuConfigFileEntry that will parse nValues
floats and
store them consecutively in location
. The parsed values are
checked to be in clamp
.
conf |
a VisuConfigFile object ; |
|
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. |
|
labelled |
a boolean. |
Since: 3.7
VisuConfigFileEntry * visu_config_file_addEnumEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,guint *location
,VisuConfigFileEnumFunc toEnum
,gboolean labelled
);
Defines a VisuConfigFileEntry that will parse a string and convert
it to an enum value with toEnum
function and store it in
location
.
conf |
a VisuConfigFile object ; |
|
key |
a string (should not be NULL) ; |
|
description |
a string (can be NULL) ;. |
[allow-none] |
location |
a location to store an enum value. |
|
toEnum |
a method to convert a string to an enum value. |
[scope call] |
labelled |
a boolean. |
Since: 3.8
VisuConfigFileEntry * visu_config_file_addStringEntry (VisuConfigFile *conf
,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()
.
conf |
a VisuConfigFile object ; |
|
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. |
Since: 3.7
VisuConfigFileEntry * visu_config_file_addStippleArrayEntry (VisuConfigFile *conf
,const gchar *key
,const gchar *description
,guint nValues
,guint16 *location
);
Defines a VisuConfigFileEntry that will parse nValues
usable for stipple and
store them consecutively in location
.
conf |
a VisuConfigFile object ; |
|
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. |
Since: 3.8
void visu_config_file_addExportFunction (VisuConfigFile *conf
,VisuConfigFileExportFunc writeFunc
);
This stores the writeFunc
given. It will be called when resources or parameters
will be exported to disk.
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.
void visu_config_file_entry_setVersion (VisuConfigFileEntry *entry
,float version
);
Set the version number the entry appear in.
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
.
const gchar *
visu_config_file_entry_getKey (const VisuConfigFileEntry *entry
);
An entry is defined by its key.
Since: 3.8
const gchar *
visu_config_file_entry_getLabel (const VisuConfigFileEntry *entry
);
An entry can be defined as some values preceeded by a label. After
parsing an entry, this label, if it exists can be retrieve with
this function. See for instance
visu_config_file_addBooleanArrayEntry()
to define an entry with a label.
Since: 3.8
gboolean visu_config_file_entry_popToken (VisuConfigFileEntry *entry
,const gchar **value
);
Pop a string from a tokenified data line corresponding to entry
in
a configuration file.
entry |
a VisuConfigFileEntry object. |
|
value |
a location to store a string. |
[out caller-allocates] |
Since: 3.8
gboolean visu_config_file_entry_popTokenAsBoolean (VisuConfigFileEntry *entry
,guint nValues
,gboolean *values
);
Read nValues
as boolean from entry
and stores them in
values
. These tokens are poped from the current list of tokens of entry
.
entry |
a VisuConfigFileEntry object. |
|
nValues |
an integer. |
|
values |
an array of boolean. |
[array length=nValues] |
Since: 3.8
gboolean visu_config_file_entry_popTokenAsInt (VisuConfigFileEntry *entry
,guint nValues
,int *values
,const int clamp[2]
);
Like visu_config_file_entry_popTokenAsBoolean()
but for
integers. Additionally conduct a range check using clamp
.
entry |
a VisuConfigFileEntry object. |
|
nValues |
an integer. |
|
values |
an array of integers. |
[array length=nValues] |
clamp |
a range. |
Since: 3.8
gboolean visu_config_file_entry_popTokenAsColor (VisuConfigFileEntry *entry
,const ToolColor **color
);
Like visu_config_file_entry_popToken()
but convert the token as a ToolColor.
entry |
a VisuConfigFileEntry object. |
|
color |
a location to store a ToolColor. |
[out caller-allocates] |
Since: 3.8
gboolean visu_config_file_entry_popTokenAsFloat (VisuConfigFileEntry *entry
,guint nValues
,float *values
,const float clamp[2]
);
Like visu_config_file_entry_popTokenAsInt()
but for floats.
entry |
a VisuConfigFileEntry object. |
|
nValues |
an integer. |
|
values |
an array of floats. |
[array length=nValues] |
clamp |
a range. |
Since: 3.8
gboolean visu_config_file_entry_popTokenAsEnum (VisuConfigFileEntry *entry
,guint *value
,VisuConfigFileEnumFunc toEnum
);
Parse the next non null token in entry
and parse it with toEnum
function. The result, if valid, is stored in value
.
entry |
a VisuConfigFileEntry object. |
|
value |
a location to store an enum value. |
[out] |
toEnum |
a method to convert a string to an enum value. |
[scope call] |
Since: 3.8
gchar *
visu_config_file_entry_popAllTokens (VisuConfigFileEntry *entry
);
Join the remaining tokens of entry
into a string.
Since: 3.8
void visu_config_file_entry_setErrorMessage (VisuConfigFileEntry *entry
,const gchar *mess
,...
);
Set error to entry
and format a message.
entry |
a VisuConfigFileEntry object. |
|
mess |
a string. |
|
... |
additional values, like in printf. |
Since: 3.8
gboolean visu_config_file_load (VisuConfigFile *conf
,const char *filename
,GError **error
);
Try to load the resources/parameters from the file name given in parameter.
conf |
a VisuConfigFile object ; |
|
filename |
the path to file to read ; |
|
error |
a pointer to a GError pointer. |
[allow-none] |
gboolean
visu_config_file_loadCommandLine (GError **error
);
For every command line option (e.g. -o axes_line_width=3), call the corresponding ressource callback.
Since: 3.8
gboolean visu_config_file_save (VisuConfigFile *conf
,const char *fileName
,int *lines
,VisuData *dataObj
,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).
conf |
a VisuConfigFile object ; |
|
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] |
error |
a location to store a possible error. |
gboolean visu_config_file_saveResourcesToXML (const char *filename
,int *lines
,VisuData *dataObj
,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) ;. |
[out] |
dataObj |
a VisuData object (can be NULL) ;. |
[allow-none] |
error |
a location to store a possible error. |
Since: 3.7
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.
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).
Since: 3.7
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
gchar * visu_config_file_getValidPath (VisuConfigFile *conf
,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.
conf |
a VisuConfigFile object ; |
|
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. |
gchar * visu_config_file_getNextValidPath (VisuConfigFile *conf
,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.
conf |
a VisuConfigFile object ; |
|
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. |
const gchar *
visu_config_file_getDefaultFilename (VisuConfigFileKind kind
);
This methods is used to get the filename used for different config files.
GList *
visu_config_file_getPathList (VisuConfigFile *conf
);
V_Sim stores a list of paths where to look for resources or parameters files, this method is used to get these lists.
GList *
visu_config_file_getEntries (VisuConfigFile *conf
);
This routine should be used for introspections purpose, to know what resources or parameters are available.
gboolean visu_config_file_exportToXML (VisuConfigFile *conf
,const gchar *filename
,GError **error
);
Export all the registered entries for resources or parameters to an XML file.
conf |
a VisuConfigFile object ; |
|
filename |
a string in the encoding of the file system ; |
|
error |
a location to store an error. |
const gchar *
visu_config_file_getPath (VisuConfigFile *conf
);
The resource file can be read from different places.
Since: 3.6
struct VisuConfigFileClass { VisuObjectClass parent; };
A short way to identify _VisuConfigFileClass structure.
#define VISU_CONFIG_FILE_RESOURCE visu_config_file_getStatic(VISU_CONFIG_FILE_KIND_RESOURCE)
Default instance of VisuConfigFile object handling resource data.
Since: 3.8
#define VISU_CONFIG_FILE_PARAMETER visu_config_file_getStatic(VISU_CONFIG_FILE_KIND_PARAMETER)
Default instance of VisuConfigFile object handling parameter data.
Since: 3.8
“parsed”
signalvoid user_function (VisuConfigFile *visuObj, VisuConfigFileEntry *key, gpointer user_data)
The entry key
of a configuration file has just been successfully parsed.
visuObj |
the object emitting the signal. |
|
key |
the key that has been parsed. |
|
user_data |
user data set when the signal handler was connected. |
Flags: No Hooks
Since: 3.7