## dataNode

dataNode — Extends capabilities of node properties.

## Synopsis

    #define             VISU_DATA_NODE_TYPE
    #define             VISU_DATA_NODE                      (obj)
    #define             VISU_DATA_NODE_CLASS                (klass)
    #define             IS_VISU_DATA_NODE_TYPE              (obj)
    #define             IS_VISU_DATA_NODE_CLASS             (klass)
    #define             VISU_DATA_NODE_GET_CLASS            (obj)
                        VisuDataNodeClass;
                        VisuDataNode;
    gboolean            (*VisuDataNodeFromStringFunc)       (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut,
                                                             gboolean *modify);
    gchar *             (*VisuDataNodeToStringFunc)         (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);
    void                (*VisuDataNodeCallbackMethod)       (VisuData *dataObj,
                                                             VisuNode *node,
                                                             gpointer data);
    GType               visu_data_node_get_type             (void);
    GObject*            visu_data_node_new                  (const gchar *name,
                                                             GType type);
    GObject*            visu_data_node_newWithCallbacks     (const gchar *name,
                                                             VisuDataNodeFromStringFunc setAsString,
                                                             VisuDataNodeToStringFunc getAsString);
    GList*              nodeDataGet_list                    (void);
    void                visu_data_node_setLabel             (VisuDataNode *data,
                                                             const gchar *label);
    const gchar*        visu_data_node_getLabel             (VisuDataNode *data);
    void                visu_data_node_setUsed              (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             gint nb);
    gboolean            visu_data_node_getUsed              (VisuDataNode *data,
                                                             VisuData *dataObj);
    gboolean            visu_data_node_setValueAsString     (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node,
                                                             gchar *labelIn,
                                                             gchar **labelOut);
    gchar*              visu_data_node_getValueAsString     (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);
    void                visu_data_node_setCallback          (VisuDataNode *data,
                                                             VisuDataNodeCallbackMethod callback,
                                                             gpointer user_data);
    void                visu_data_node_setEditable          (VisuDataNode *data,
                                                             gboolean status);
    gboolean            visu_data_node_getEditable          (VisuDataNode *data);
    void                visu_data_node_emitValueChanged     (VisuDataNode *data,
                                                             VisuData *dataObj);

## Object Hierarchy

      GObject
       +----VisuDataNode

## Signals

      "propertyUnused"                                 : Run Last / No Recursion / No Hooks
      "propertyUsed"                                   : Run Last / No Recursion / No Hooks
      "valueChanged"                                   : Run Last / No Recursion / No Hooks

## 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 `visu_node_property_newPointer()` for instance, a VisuDataNode can be created using `visu_data_node_new()`. A VisuDataNode may not be attached to a specific VisuData and is a global property found on each VisuData (or potentialy found). The advantage of doing this is to keep track of available properties for VisuData objects. To get all public properties, call `nodeDataGet_list()`.

## Details

### VISU_DATA_NODE_TYPE

    #define VISU_DATA_NODE_TYPE	     (visu_data_node_get_type ())

return the type of VisuDataNode.

### VISU_DATA_NODE()

    #define VISU_DATA_NODE(obj)	     (G_TYPE_CHECK_INSTANCE_CAST(obj, VISU_DATA_NODE_TYPE, VisuDataNode))

Cast the given `obj` into VisuDataNode type.

`obj` : | a GObject to cast.

### VISU_DATA_NODE_CLASS()

    #define VISU_DATA_NODE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST(klass, VISU_DATA_NODE_TYPE, VisuDataNodeClass))

Cast the given `klass` into VisuDataNodeClass.

`klass` : | a GObjectClass to cast.

### IS_VISU_DATA_NODE_TYPE()

    #define IS_VISU_DATA_NODE_TYPE(obj)    (G_TYPE_CHECK_INSTANCE_TYPE(obj, VISU_DATA_NODE_TYPE))

Test if the given `ogj` is of the type of VisuDataNode object.

`obj` : | a GObject to test.

### IS_VISU_DATA_NODE_CLASS()

    #define IS_VISU_DATA_NODE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE(klass, VISU_DATA_NODE_TYPE))

Test if the given `klass` is of the type of VisuDataNodeClass class.

`klass` : | a GObjectClass to test.

### VISU_DATA_NODE_GET_CLASS()

    #define VISU_DATA_NODE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS(obj, VISU_DATA_NODE_TYPE, VisuDataNodeClass))

It returns the class of the given `obj`.

`obj` : | a GObject to get the class of.

### VisuDataNodeClass

    typedef struct _VisuDataNodeClass VisuDataNodeClass;

An opaque structure.

### VisuDataNode

    typedef struct _VisuDataNode VisuDataNode;

An opaque structure.

### VisuDataNodeFromStringFunc ()

    gboolean            (*VisuDataNodeFromStringFunc)       (VisuDataNode *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 VisuDataNode ;
`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).

### VisuDataNodeToStringFunc ()

    gchar *             (*VisuDataNodeToStringFunc)         (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);

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

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

### VisuDataNodeCallbackMethod ()

    void                (*VisuDataNodeCallbackMethod)       (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.

### visu_data_node_get_type ()

    GType               visu_data_node_get_type             (void);

This method returns the type of VisuDataNode, use VISU_DATA_NODE_TYPE instead.

Returns : | the type of VisuDataNode.

### visu_data_node_new ()

    GObject*            visu_data_node_new                  (const gchar *name,
                                                             GType type);

This method creates a new VisuDataNode and registers it. A VisuDataNode is characterised by a string used as a key to store it as a node property (see `visu_node_property_newPointer()`). The stored data can be arrays or not. Notice that `name` is 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 VisuDataNode.. transfer full.

### visu_data_node_newWithCallbacks ()

    GObject*            visu_data_node_newWithCallbacks     (const gchar *name,
                                                             VisuDataNodeFromStringFunc setAsString,
                                                             VisuDataNodeToStringFunc getAsString);

As `visu_data_node_new()`, 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 ;. scope call
`getAsString` : | a custom routine to create a string from node values.. scope call
Returns : | a newly created VisuDataNode.. transfer full.

### nodeDataGet_list ()

    GList*              nodeDataGet_list                    (void);

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

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

### visu_data_node_setLabel ()

    void                visu_data_node_setLabel             (VisuDataNode *data,
                                                             const gchar *label);

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

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

### visu_data_node_getLabel ()

    const gchar*        visu_data_node_getLabel             (VisuDataNode *data);

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

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

### visu_data_node_setUsed ()

    void                visu_data_node_setUsed              (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             gint nb);

A VisuDataNode 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 VisuDataNode ;
`dataObj` : | a VisuData object ;
`nb` : | a positive or null integer.

### visu_data_node_getUsed ()

    gboolean            visu_data_node_getUsed              (VisuDataNode *data,
                                                             VisuData *dataObj);

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

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

### visu_data_node_setValueAsString ()

    gboolean            visu_data_node_setValueAsString     (VisuDataNode *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 `visu_data_node_getValueAsString()`) 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 `visu_data_node_getEditable()`).

`data` : | a VisuDataNode ;
`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.

### visu_data_node_getValueAsString ()

    gchar*              visu_data_node_getValueAsString     (VisuDataNode *data,
                                                             VisuData *dataObj,
                                                             VisuNode *node);

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

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

### visu_data_node_setCallback ()

    void                visu_data_node_setCallback          (VisuDataNode *data,
                                                             VisuDataNodeCallbackMethod callback,
                                                             gpointer user_data);

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

`data` : | a VisuDataNode ;
`callback` : | a VisuDataNodeCallbackMethod method ;. scope call
`user_data` : | a pointer to a location used to store some user data.

### visu_data_node_setEditable ()

    void                visu_data_node_setEditable          (VisuDataNode *data,
                                                             gboolean status);

Set if the values are modifiable.

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

### visu_data_node_getEditable ()

    gboolean            visu_data_node_getEditable          (VisuDataNode *data);

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

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

### visu_data_node_emitValueChanged ()

    void                visu_data_node_emitValueChanged     (VisuDataNode *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 VisuDataNode ;
`dataObj` : | a VisuData object.

## Signal Details

### The `"propertyUnused"` signal

    void                user_function                      (VisuDataNode *data,
                                                            GObject      *dataObj,
                                                            gpointer      user_data)      : Run Last / No Recursion / No Hooks

The given property `data` gets unused by `dataObj`.

`data` : | the VisuDataNode emitting the signal.
`dataObj` : | the VisuData its working on.
`user_data` : | user data set when the signal handler was connected.

Since 3.3

### The `"propertyUsed"` signal

    void                user_function                      (VisuDataNode *data,
                                                            GObject      *dataObj,
                                                            gpointer      user_data)      : Run Last / No Recursion / No Hooks

The given property `data` gets used by `dataObj`.

`data` : | the VisuDataNode emitting the signal.
`dataObj` : | the VisuData its working on.
`user_data` : | user data set when the signal handler was connected.

Since 3.3

### The `"valueChanged"` signal

    void                user_function                      (VisuDataNode *data,
                                                            GObject      *dataObj,
                                                            gpointer      user_data)      : Run Last / No Recursion / No Hooks

The given property `data` used by `dataObj` has its value changed.

`data` : | the VisuDataNode emitting the signal.
`dataObj` : | the VisuData its working on.
`user_data` : | user data set when the signal handler was connected.

Since 3.3