GdaTreeNode

## GdaTreeNode GdaTreeNode — A node in a GdaTree |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaTreeNode;
    GdaTreeNode *       gda_tree_node_new                   (const gchar *name);
    GdaTreeNode *       gda_tree_node_get_parent            (GdaTreeNode *node);
    GSList *            gda_tree_node_get_children          (GdaTreeNode *node);
    GdaTreeNode *       gda_tree_node_get_child_index       (GdaTreeNode *node,
                                                             gint index);
    GdaTreeNode *       gda_tree_node_get_child_name        (GdaTreeNode *node,
                                                             const gchar *name);
    void                gda_tree_node_set_node_attribute    (GdaTreeNode *node,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);
    const GValue *      gda_tree_node_get_node_attribute    (GdaTreeNode *node,
                                                             const gchar *attribute);
    const GValue *      gda_tree_node_fetch_attribute       (GdaTreeNode *node,
                                                             const gchar *attribute);

## Object Hierarchy

      GObject
       +----GdaTreeNode

## Properties

      "name"                     gchar*                : Read / Write

## Signals

      "node-changed"                                   : Run Last
      "node-deleted"                                   : Run Last
      "node-has-child-toggled"                         : Run Last
      "node-inserted"                                  : Run Last

## Description

Every node in a GdaTree tree is represented by a single GdaTreeNode object. There is no distinction between nodes which have children and those which don't (leaf nodes).

The GdaTreeNode is very basic as it only has a "name" attribute: users are encouraged to subclass it to add more features if needed (and make use of them by defining a GdaTreeManagerNodeFunc function and calling `gda_tree_manager_set_node_create_func()`).

## Details

### GdaTreeNode

    typedef struct _GdaTreeNode GdaTreeNode;

### gda_tree_node_new ()

    GdaTreeNode *       gda_tree_node_new                   (const gchar *name);

Creates a new GdaTreeNode object

`name` : | a name, or `NULL`. [allow-none]
Returns : | a new GdaTreeNode. [transfer full]

Since 4.2

### gda_tree_node_get_parent ()

    GdaTreeNode *       gda_tree_node_get_parent            (GdaTreeNode *node);

Get the GdaTreeNode parent of `node` in the GdaTree node belongs to. If `node` is at the top level, then this method return `NULL`.

`node` : | a GdaTreeNode object
Returns : | the parent GdaTreeNode. [transfer none]

Since 4.2

### gda_tree_node_get_children ()

    GSList *            gda_tree_node_get_children          (GdaTreeNode *node);

Get a list of all `node`'s children, free it with `g_slist_free()` after usage

`node` : | a GdaTreeNode object
Returns : | a new GSList of GdaTreeNode objects, or `NULL` if `node` does not have any child. [transfer container][element-type GdaTreeNode]

Since 4.2

### gda_tree_node_get_child_index ()

    GdaTreeNode *       gda_tree_node_get_child_index       (GdaTreeNode *node,
                                                             gint index);

Get the GdaTreeNode child of `node` at position `index` (starting at 0).

`node` : | a GdaTreeNode object
`index` : | a index
Returns : | the GdaTreeNode, or `NULL` if not found. [transfer none]

Since 4.2

### gda_tree_node_get_child_name ()

    GdaTreeNode *       gda_tree_node_get_child_name        (GdaTreeNode *node,
                                                             const gchar *name);

Get the GdaTreeNode child of `node` which has the GDA_ATTRIBUTE_NAME set to `name`

`node` : | a GdaTreeNode object
`name` : | requested node's name
Returns : | the GdaTreeNode, or `NULL` if not found. [transfer none]

Since 4.2

### gda_tree_node_set_node_attribute ()

    void                gda_tree_node_set_node_attribute    (GdaTreeNode *node,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);

Set the value associated to a named attribute. The `attribute` string is used AS IT IS by this method (eg. no copy of it is made), and the memory it uses will be freed using the `destroy` function when no longer needed (if `destroy` is `NULL`, then the string will not be freed at all).

Attributes can have any name, but Libgda proposes some default names, see this section.

For example one would use it as:

`gda_tree_node_set_node_attribute (node, g_strdup (my_attribute), my_value, g_free); gda_tree_node_set_node_attribute (node, GDA_ATTRIBUTE_NAME, my_value, NULL);`

If there is already an attribute named `attribute` set, then its value is replaced with the new value (`value` is copied), except if `value` is `NULL`, in which case the attribute is removed.

`node` : | a GdaTreeNode
`attribute` : | attribute name
`value` : | a GValue, or `NULL`. [transfer none][allow-none]
`destroy` : | a function to be called when `attribute` is not needed anymore, or `NULL`

Since 4.2

### gda_tree_node_get_node_attribute ()

    const GValue *      gda_tree_node_get_node_attribute    (GdaTreeNode *node,
                                                             const gchar *attribute);

Get the value associated to the attribute named `attribute` for `node`. The difference with `gda_tree_node_fetch_attribute()` is that `gda_tree_node_fetch_attribute()` will also query `node`'s parents (recursively up to the top level node) if the attribute is not set for `node`.

Attributes can have any name, but Libgda proposes some default names, see this section.

`node` : | a GdaTreeNode
`attribute` : | attribute name as a string
Returns : | a read-only GValue, or `NULL` if not attribute named `attribute` has been set for `node`. [transfer none]

Since 4.2

### gda_tree_node_fetch_attribute ()

    const GValue *      gda_tree_node_fetch_attribute       (GdaTreeNode *node,
                                                             const gchar *attribute);

Get the value associated to the attribute named `attribute` for `node`. If the attribute is not set, then `node`'s parents is queries (recursively up to the top level node).

Attributes can have any name, but Libgda proposes some default names, see this section.

`node` : | a GdaTreeNode
`attribute` : | attribute name as a string
Returns : | a read-only GValue, or `NULL` if not attribute named `attribute` has been set for `node`. [transfer none]

Since 4.2

## Property Details

### The `"name"` property

      "name"                     gchar*                : Read / Write

Node's name attribute.

Default value: NULL

## Signal Details

### The `"node-changed"` signal

    void                user_function                      (GdaTreeNode *reporting,
                                                            GdaTreeNode *node,
                                                            gpointer     user_data)      : Run Last

Gets emitted when a `node` has changed

`reporting` : | the GdaTreeNode which emits the signal (may be a parent of `node`, or `node` itself)
`node` : | the GdaTreeNode which has changed
`user_data` : | user data set when the signal handler was connected.

Since 4.2

### The `"node-deleted"` signal

    void                user_function                      (GdaTreeNode *reporting,
                                                            gchar       *relative_path,
                                                            gpointer     user_data)          : Run Last

Gets emitted when a `node` has been removed

`reporting` : | the GdaTreeNode which emits the signal (a parent of the removed node)
`relative_path` : | the path the node held, relative to `reporting`
`user_data` : | user data set when the signal handler was connected.

Since 4.2

### The `"node-has-child-toggled"` signal

    void                user_function                      (GdaTreeNode *reporting,
                                                            GdaTreeNode *node,
                                                            gpointer     user_data)      : Run Last

Gets emitted when a `node` has has a child when it did not have any or when it does not have a ny children anymore when it had some

`reporting` : | the GdaTreeNode which emits the signal (may be a parent of `node`, or `node` itself)
`node` : | the GdaTreeNode which changed from having children to being a leaf or the other way around
`user_data` : | user data set when the signal handler was connected.

Since 4.2

### The `"node-inserted"` signal

    void                user_function                      (GdaTreeNode *reporting,
                                                            GdaTreeNode *node,
                                                            gpointer     user_data)      : Run Last

Gets emitted when a `node` has been inserted

`reporting` : | the GdaTreeNode which emits the signal (may be a parent of `node`, or `node` itself)
`node` : | the GdaTreeNode which has been inserted
`user_data` : | user data set when the signal handler was connected.

Since 4.2