## dataNode

dataNode — Extends capabilities of node properties.

## Synopsis

    void                (*DataNodeCallbackMethod)           (VisuData *dataObj,
                                                             VisuNode *node,
                                                             gpointer data);
    gchar*              (*GetStringFromValueFunc)           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);
    gboolean            (*GetValueFromStringFunc)           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut,
                                                             gboolean *modify);
    DataNode*           nodeDataNew                         (const gchar *name,
                                                             GType type);
    DataNode*           nodeDataNew_withCallbacks           (const gchar *name,
                                                             GetValueFromStringFunc setAsString,
                                                             GetStringFromValueFunc getAsString);
    GList*              nodeDataGet_list                    ();
    gboolean            nodeDataGet_used                    (DataNode *data,
                                                             VisuData *dataObj);
    void                nodeDataSet_used                    (DataNode *data,
                                                             VisuData *dataObj,
                                                             gint nb);
    const gchar*        nodeDataGet_label                   (DataNode *data);
    void                nodeDataSet_label                   (DataNode *data,
                                                             const gchar *label);
    gchar*              nodeDataGet_valueAsString           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);
    gboolean            nodeDataSet_valueAsString           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut);
    void                nodeDataSet_callback                (DataNode *data,
                                                             DataNodeCallbackMethod callback,
                                                             gpointer user_data);
    gboolean            nodeDataGet_editable                (DataNode *data);
    void                nodeDataSet_editable                (DataNode *data,
                                                             gboolean status);
    void                nodeDataEmit_valueChanged           (DataNode *data,
                                                             VisuData *dataObj);

## Description

This module is a wrapper around node properties from VisuData. It adds some capabilities, such as a translatable name, a way to go from data to strings and reverse, callbacks when the properties is changed...

When creating a node property calling `visuDataAdd_nodeProperty()`, a DataNode can be created using `nodeDataNew()`. A DataNode may not be attached to a specific VisuData and is a global property found on each VisuData (or potentialy found). The adventage of doing this is to keep track of available properties for VisuData objects. To get all public properties, call `nodeDataGet_list()`.

## Details

### DataNodeCallbackMethod ()

    void                (*DataNodeCallbackMethod)           (VisuData *dataObj,
                                                             VisuNode *node,
                                                             gpointer data);

Interface for callbacks methods that are called whenever a data is changed on a node.

WARNING: it may be removed later.

`dataObj` : | the VisuData object on which the callback is done ;
`node` : | the VisuNode on which the callback is done ;
`data` : | a user defined pointer.

### GetStringFromValueFunc ()

    gchar*              (*GetStringFromValueFunc)           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);

For the given node, the values stored are printed into a string.

`data` : | a DataNode ;
`dataObj` : | a VisuData object ;
`node` : | a VisuNode.
Returns : | a newly created string (use `g_free()`).

### GetValueFromStringFunc ()

    gboolean            (*GetValueFromStringFunc)           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut,
                                                             gboolean *modify);

If the string is correctly formatted (that means it has the same format as the string returned by `GetValueAsStringFunc()`) the stored values are modified. The resulting string is created and put into `labelOut`. If the input string `labelIn` is unparsable, `labelOut` will contain current values.

`data` : | a DataNode ;
`dataObj` : | a VisuData object ;
`node` : | a VisuNode ;
`labelIn` : | a formatted string ;
`labelOut` : | a pointer to store a string ;
`modify` : | TRUE if the values have been modified.
Returns : | TRUE if the string was correctly parsed (modified or not).

### nodeDataNew ()

    DataNode*           nodeDataNew                         (const gchar *name,
                                                             GType type);

This method creates a new DataNode and registers it. A DataNode is characterised by a string used as a key to store it as a node property (see `visuDataAdd_nodeProperty()`). The stored data can be arrays or not. Notice that `name` is not copied.

`name` : | a string used to store the data as a node property ;
`type` : | the type of data stored (array or not).
Returns : | a newly created DataNode.

### nodeDataNew_withCallbacks ()

    DataNode*           nodeDataNew_withCallbacks           (const gchar *name,
                                                             GetValueFromStringFunc setAsString,
                                                             GetStringFromValueFunc getAsString);

As `nodeDataNew()`, but with custom `setAsString` and `getAsString` routines. This is used to allow to treat every node related values, not just node properties.

`name` : | a string used to store the data as a node property ;
`setAsString` : | a custom routine to change node values from a string ;
`getAsString` : | a custom routine to create a string from node values.
Returns : | a newly created DataNode.

### nodeDataGet_list ()

    GList*              nodeDataGet_list                    ();

All registered DataNode are stored in an intern list. This method is used to retrieve it.

Returns : | a GList of all registereed DataNode (this list is owned by V_Sim).

### nodeDataGet_used ()

    gboolean            nodeDataGet_used                    (DataNode *data,
                                                             VisuData *dataObj);

Access method to know if the given `dataObj` has a public node property of the type `data`.

`data` : | a DataNode ;
`dataObj` : | a VisuData object.
Returns : | TRUE if `dataObj` has a node property of the given type.

### nodeDataSet_used ()

    void                nodeDataSet_used                    (DataNode *data,
                                                             VisuData *dataObj,
                                                             gint nb);

A DataNode stores data for each node of a given VisuData. The number of data stored for each node is set with this method. When some part wants to set a new node property and wants to make it public, this method can be called. It also can be called when the node property is removed (using a null `nb` argument). If `nb` is changed for a positive value, the "propertyUsed" signal is emitted with `dataObj` as argument, instead if the value is changed for null, the "propertyUnused" signal is triggered also with `dataObj` as argument.

`data` : | a DataNode ;
`dataObj` : | a VisuData object ;
`nb` : | a positive or null integer.

### nodeDataGet_label ()

    const gchar*        nodeDataGet_label                   (DataNode *data);

A DataNode can have a label, if not its name is used.

`data` : | a DataNode ;
Returns : | the label of the node (in UTF8), this string is owned by V_Sim.

### nodeDataSet_label ()

    void                nodeDataSet_label                   (DataNode *data,
                                                             const gchar *label);

A DataNode can have a label, if not its name is used. Notice that `label` is not copied.

`data` : | a DataNode ;
`label` : | an UTF8 string (may be translated).

### nodeDataGet_valueAsString ()

    gchar*              nodeDataGet_valueAsString           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);

For the given node, the values stored are printed into a string.

`data` : | a DataNode ;
`dataObj` : | a VisuData object ;
`node` : | a VisuNode.
Returns : | a newly created string.

### nodeDataSet_valueAsString ()

    gboolean            nodeDataSet_valueAsString           (DataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut);

If the string is correctly formatted (that means it has the same format as the string returned by `nodeDataGet_valueAsString()`) the stored values are modified. The resulting string is created and put into `labelOut`. If the input string `labelIn` is unparsable, `labelOut` will contain current values. Notice that this method is callable only if the `data` is editable (see `nodeDataGet_editable()`).

`data` : | a DataNode ;
`dataObj` : | a VisuData object ;
`node` : | a VisuNode ;
`labelIn` : | a formatted string ;
`labelOut` : | a pointer to store a string.
Returns : | TRUE if the string was correctly parsed.

### nodeDataSet_callback ()

    void                nodeDataSet_callback                (DataNode *data,
                                                             DataNodeCallbackMethod callback,
                                                             gpointer user_data);

When `nodeDataSet_valueAsString()`, values may be modified. If true, the given callback method is called with `user_data` as argument.

`data` : | a DataNode ;
`callback` : | a DataNodeCallbackMethod method ;
`user_data` : | a pointer to a location used to store some user data.

### nodeDataGet_editable ()

    gboolean            nodeDataGet_editable                (DataNode *data);

If some callback method has been given with `nodeDataSet_callback()`, then the values are considered editable.

`data` : | a DataNode.
Returns : | TRUE if values are editable.

### nodeDataSet_editable ()

    void                nodeDataSet_editable                (DataNode *data,
                                                             gboolean status);

Set if the values are modifiable.

`data` : | a DataNode ;
`status` : | a boolean value.

### nodeDataEmit_valueChanged ()

    void                nodeDataEmit_valueChanged           (DataNode *data,
                                                             VisuData *dataObj);

Emit the 'valueChanged' signal. This method should be called after all changes have been done to a node property set of nodes. Then routines using this property can update itself.

`data` : | a DataNode ;
`dataObj` : | a VisuData object.