## visu_tools visu_tools — Basic tools and variables that are used all around the program. |

## Synopsis

    #define             MAX_LINE_LENGTH
    #define             MASK_RGB_R
    #define             MASK_RGB_G
    #define             MASK_RGB_B
    #define             MASK_RGB_A
    #define             MASK_RGB_ALL

    void                (*VisuToolsInitFunc)                ();
    void                (*voidDataFunc)                     (gpointer data);

    typedef             Property;
    void                freeProperty                        (gpointer prop);

    float               fModulo                             (float a,
                                                             int b);
    gchar*              getValidPath                        (GList **pathList,
                                                             char *fileName,
                                                             int accessMode);
    gchar*              normalize_path                      (const gchar *path);
    void                visuWaitFunction                    ();
    #define             DBG_fprintf
    gboolean            visuToolsSubstitute_XML             (GString *output,
                                                             const gchar *filename,
                                                             const gchar *tag,
                                                             GError **error);

## Description

This module gives tools to handle strings (trim, append, allocate...), GList and GHashTable (compare, delete functions), the file system (test for existing file, for read/write permissions), mathematical functions (floating point modulo, matrix product, coordinates handling)...

## Details

### MAX_LINE_LENGTH

    #define MAX_LINE_LENGTH 256

This is the maximum number of characters read on a line of an input file.

### MASK_RGB_R

    #define MASK_RGB_R (1 << 0)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to red.

### MASK_RGB_G

    #define MASK_RGB_G (1 << 1)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to green.

### MASK_RGB_B

    #define MASK_RGB_B (1 << 2)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to blue.

### MASK_RGB_A

    #define MASK_RGB_A (1 << 3)

This value can be used to create a mask for methods that require one for reading rgb color array. This value actually correspond to the alpha channel.

### MASK_RGB_ALL

    #define MASK_RGB_ALL (15)

This value can be used to create a mask for methods that require one for reading rgb color array. This value is a shortcut for MASK_RGB_R | MASK_RGB_G | MASK_RGB_B.

### VisuToolsInitFunc ()

    void                (*VisuToolsInitFunc)                ();

These methods are used by V_Sim to initialise some part of the program. They are called once on start-up.

### voidDataFunc ()

    void                (*voidDataFunc)                     (gpointer data);

These methods are used when no specific argument is required except a user-defined object and when void is the return type.

`data` : | a pointer to some user defined object.

### Property

    typedef struct Property_struct Property;

A convenient name for Property_struct.

### freeProperty ()

    void                freeProperty                        (gpointer prop);

It calls `freeFunc` of `prop` on its `data` field (see Property), if `freeFunc` is not NULL. Then the Property itself is `g_free()`.

`prop` : | a Property.

### fModulo ()

    float               fModulo                             (float a,
                                                             int b);

This function is just like a`b` except it works with a float `a` argument. `a` can be negative, but the return value of the function is always positive.

`a` : | a float ;
`b` : | an int.
Returns : | the new float value after the modulo.

### getValidPath ()

    gchar*              getValidPath                        (GList **pathList,
                                                             char *fileName,
                                                             int accessMode);

`pathList` contains a list of directories (first is most prefered) and fileName is the file name which one likes have informations on. This routine look for the first directory where fileName can be writen or read (depending on accessMode parameter). The pointer to the GList indicates at the end the first valid entry in the GList.

`pathList` : | a pointer to a GList with all the possible path,
`fileName` : | a string,
`accessMode` : | a value from R_OK, W_OK and X_OK as described in unistd.h.
Returns : | the first valid complete path (from `pathList` plus `fileName`) if one can be found depnding on `accessMode` or NULL if none found.

### normalize_path ()

    gchar*              normalize_path                      (const gchar *path);

This function normalizes the path, i.e. it removes all . and .. It should work also on Windows. It must take an absolute path as argument, if not it is converted assuming the current working directory.

`path` : | a string, NULL terminated.
Returns : | a newly created string.

### visuWaitFunction ()

    void                visuWaitFunction                    ();

This function must be called in a blocking loop to update different things like the gtk for example.

### DBG_fprintf

    #define DBG_fprintf if(DEBUG) (void)fprintf

For developpers: use this macro instead of fprintf.

### visuToolsSubstitute_XML ()

    gboolean            visuToolsSubstitute_XML             (GString *output,
                                                             const gchar *filename,
                                                             const gchar *tag,
                                                             GError **error);

Read `filename` (must be XML file) and remove the `tag` zone from it. At that place, it puts the contain of `output`.

`output` : | a GString to store the substitution ;
`filename` : | the file to read the data from ;
`tag` : | the tag to substitute ;
`error` : | a location to store possible errors.
Returns : | TRUE if no error occured.