## dataNode

dataNode — Extends capabilities of node properties.

## Synopsis

    void        (*DataNodeCallbackMethod)       (VisuData *dataObj,
                                                 VisuNode *node,
                                                 gpointer data);
    DataNode*   nodeDataNew                     (const gchar *name,
                                                 GType type);
    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);

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

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

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