GNOME Data Access 5 manual: GdaTreeNode

## GdaTreeNode GdaTreeNode — A node in a GdaTree |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaTreeNode * | gda_tree_node_new ()
GdaTreeNode * | gda_tree_node_get_parent ()
GSList * | gda_tree_node_get_children ()
GdaTreeNode * | gda_tree_node_get_child_index ()
GdaTreeNode * | gda_tree_node_get_child_name ()
void | gda_tree_node_set_node_attribute ()
const GValue * | gda_tree_node_get_node_attribute ()
const GValue * | gda_tree_node_fetch_attribute ()

## Properties

gchar * | name | Read / Write

## Signals

void | node-changed | Run Last
void | node-deleted | Run Last
void | node-has-child-toggled | Run Last
void | node-inserted | Run Last

## Types and Values

| GdaTreeNode

## Object Hierarchy

        GObject
        ╰── GdaTreeNode

## 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()`).

## Functions

### gda_tree_node_new ()

    GdaTreeNode *
    gda_tree_node_new (const gchar *name);

Creates a new GdaTreeNode object

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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`

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

### GdaTreeNode

    typedef struct _GdaTreeNode GdaTreeNode;

## Property Details

### The `“name”` property

      “name”                     gchar *

Node's name attribute.

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“node-changed”` signal

    void
    user_function (GdaTreeNode *reporting,
                   GdaTreeNode *node,
                   gpointer     user_data)

Gets emitted when a `node` has changed

#### Parameters

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

Flags: Run Last

Since 4.2

### The `“node-deleted”` signal

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

Gets emitted when a `node` has been removed

#### Parameters

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

Flags: Run Last

Since 4.2

### The `“node-has-child-toggled”` signal

    void
    user_function (GdaTreeNode *reporting,
                   GdaTreeNode *node,
                   gpointer     user_data)

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

#### Parameters

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

Flags: Run Last

Since 4.2

### The `“node-inserted”` signal

    void
    user_function (GdaTreeNode *reporting,
                   GdaTreeNode *node,
                   gpointer     user_data)

Gets emitted when a `node` has been inserted

#### Parameters

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

Flags: Run Last

Since 4.2