## 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_ALL

    void        setFileSystemInUTF8             (int val);
    int         getFileSystemInUTF8             ();
    gchar*      getStringInUTF8                 (const gchar *str);

    float       fModulo                         (float a,
                                                 int b);
    void        freeGPointer                    (gpointer ele);
    void        (*freeUserDataFunc)             (gpointer data);
    void        freeString                      (gpointer ele);
    void        freeFloat                       (gpointer ele);
    void        freeInt                         (gpointer ele);
    gchar*      getValidPath                    (GList **pathList,
                                                 char *fileName,
                                                 int accessMode);
    void        getGeneralPaths                 ();
    gchar*      normalize_path                  (gchar *path);
    void        (*voidDataFunc)                 (gpointer data);
    void        visuWaitFunction                ();
    void        allocationProblems              ();
    #define     DBG_fprintf

## 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_ALL

    #define MASK_RGB_ALL (7)

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.

### setFileSystemInUTF8 ()

    void        setFileSystemInUTF8             (int val);

A call to this method stores a flag to identify the file system as in UTF-8 or not. If system is not in UTF-8, the programmer needs to convert from locale to UTF-8 to use file names in the GTK interface and have to do some transformations from UTF-8 to locale when strings are retrieve from the GTK interface.

`val` : | a boolean to specify if the file system is in UTF-8 or not.

### getFileSystemInUTF8 ()

    int         getFileSystemInUTF8             ();

This method can retrieve the flag for the coding of the file system. This flag must have been initialized by a call to `setFileSystemInUTF8` before using this method. If system is not in UTF-8, the programmer needs to convert from locale to UTF-8 to use file names in the GTK interface and have to do some transformations from UTF-8 to locale when strings are retrieve from the GTK interface.

Returns : | 1 if the flag of the file system is on UTF-8, 0 otherwise.

### getStringInUTF8 ()

    gchar*      getStringInUTF8                 (const gchar *str);

Convert the given string from the locale of the file system to UTF-8.

`str` : | a string to convert.
Returns : | a newly allocated string, must be freed by a call to g_free after use.

### 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.

### freeGPointer ()

    void        freeGPointer                    (gpointer ele);

It deallocates `ele`. `ele` must have been allocated with malloc or realloc. This function can be used as a freed method for a GHashTable of which values are of complex structure.

`ele` : | the gpointer to be freed.

### freeUserDataFunc ()

    void        (*freeUserDataFunc)             (gpointer data);

This prototype is used when a method must be given to free some data.

`data` : | some allocated data.

### freeString ()

    void        freeString                      (gpointer ele);

It deallocates `ele`. `ele` must be a char* and have been allocated with malloc or realloc. This function can be used as a freed method for a GHashTable of which values are char*.

`ele` : | the char* to be freed.

### freeFloat ()

    void        freeFloat                       (gpointer ele);

It deallocates `ele`. `ele` must be a float* and have been allocated with malloc or realloc. This function can be used as a freed method for a GHashTable of which values are float*.

`ele` : | the float* to be freed.

### freeInt ()

    void        freeInt                         (gpointer ele);

It deallocates `ele`. `ele` must be a int* and have been allocated with malloc or realloc. This function can be used as a freed method for a GHashTable of which values are int*.

`ele` : | the int* to be freed.

### 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.

### getGeneralPaths ()

    void        getGeneralPaths                 ();

This method sets the paths. On Unix systems, this method sets the paths from macros defined by configure. On Win32 systems, it reads paths in a v_sim.ini file found in the current directory or in the C:\windows.

### normalize_path ()

    gchar*      normalize_path                  (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.

### 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.

### visuWaitFunction ()

    void        visuWaitFunction                ();

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

### allocationProblems ()

    void        allocationProblems              ();

Print a message.

### DBG_fprintf

    #define DBG_fprintf if(DEBUG) (void)fprintf

For developpers : use this macro instead of fprintf.