GdaTree

## GdaTree GdaTree — A tree-structure |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaTree;
    GdaTree *           gda_tree_new                        (void);
    void                gda_tree_add_manager                (GdaTree *tree,
                                                             GdaTreeManager *manager);
    void                gda_tree_clean                      (GdaTree *tree);
    gboolean            gda_tree_update_all                 (GdaTree *tree,
                                                             GError **error);
    gboolean            gda_tree_update_part                (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             GError **error);
    gboolean            gda_tree_update_children            (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             GError **error);
    GSList *            gda_tree_get_nodes_in_path          (GdaTree *tree,
                                                             const gchar *tree_path,
                                                             gboolean use_names);
    GdaTreeNode *       gda_tree_get_node                   (GdaTree *tree,
                                                             const gchar *tree_path,
                                                             gboolean use_names);
    gchar *             gda_tree_get_node_path              (GdaTree *tree,
                                                             GdaTreeNode *node);
    GdaTreeManager *    gda_tree_get_node_manager           (GdaTree *tree,
                                                             GdaTreeNode *node);
    void                gda_tree_set_attribute              (GdaTree *tree,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);
    void                gda_tree_dump                       (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             FILE *stream);

## Object Hierarchy

      GObject
       +----GdaTree

## Properties

      "is-list"                  gboolean              : Read

## Signals

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

## Description

The GdaTree is the top level object representing hierarchically structured data. From this object it is also possible (depending on the tree managers it uses), to clean (remove all the nodes) the whole tree, or to request a complete or partial update of the nodes.

It is also possible to set attributes to the tree itself (as it is possible to do for tree nodes), or to dump the whole or part of a tree in an indented and easy to read fashion.

## Details

### GdaTree

    typedef struct _GdaTree GdaTree;

### gda_tree_new ()

    GdaTree *           gda_tree_new                        (void);

Creates a new GdaTree object

Returns : | a new GdaTree object. [transfer full]

Since 4.2

### gda_tree_add_manager ()

    void                gda_tree_add_manager                (GdaTree *tree,
                                                             GdaTreeManager *manager);

Sets `manager` as a top GdaTreeManager object, which will be responsible for creating top level nodes in `tree`.

`tree` : | a GdaTree object
`manager` : | a GdaTreeManager object. [transfer none]

Since 4.2

### gda_tree_clean ()

    void                gda_tree_clean                      (GdaTree *tree);

Removes any node in `tree`

`tree` : | a GdaTree object

Since 4.2

### gda_tree_update_all ()

    gboolean            gda_tree_update_all                 (GdaTree *tree,
                                                             GError **error);

Requests that `tree` be populated with nodes. If an error occurs, then `tree`'s contents is left unchanged, and otherwise `tree`'s previous contents is completely replaced by the new one.

`tree` : | a GdaTree object
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | TRUE if no error occurred.

Since 4.2

### gda_tree_update_part ()

    gboolean            gda_tree_update_part                (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             GError **error);

Requests that `tree` be populated with nodes, starting from `node`

`tree` : | a GdaTree object
`node` : | a GdaTreeNode node in `tree`
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | TRUE if no error occurred.

Since 4.2

### gda_tree_update_children ()

    gboolean            gda_tree_update_children            (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             GError **error);

Update the children of `node` in `tree` (not recursively, to update recursively, use `gda_tree_update_part()`). If `node` is `NULL` then the top level nodes are updated.

`tree` : | a GdaTree object
`node` : | a GdaTreeNode node in `tree`, or `NULL`. [allow-none]
`error` : | a place to store errors, or `NULL`. [allow-none]
Returns : | TRUE if no error occurred.

Since 4.2.8

### gda_tree_get_nodes_in_path ()

    GSList *            gda_tree_get_nodes_in_path          (GdaTree *tree,
                                                             const gchar *tree_path,
                                                             gboolean use_names);

The returned list is a list of all the GdaTreeNode nodes below the node at the specified path.

As a corner case if `tree_path` is `NULL`, then the returned list contains all the top level nodes.

`tree` : | a GdaTree object
`tree_path` : | full path to the required nodes (if `use_names` is `TRUE`, then it must start with '/'), or `NULL`. [allow-none]
`use_names` : | if `TRUE`, then `tree_path` will be interpreted as a unix style path, and if `FALSE`, then `tree_path` will be interpreted similarly to the GtkTreePath's string representation.
Returns : | a new list of GdaTreeNode pointers, free it with `g_slist_free()`. [transfer container][element-type GdaTreeNode]

Since 4.2

### gda_tree_get_node ()

    GdaTreeNode *       gda_tree_get_node                   (GdaTree *tree,
                                                             const gchar *tree_path,
                                                             gboolean use_names);

Locates a GdaTreeNode using the `tree_path` path.

`tree` : | a GdaTree object
`tree_path` : | full path to the required nodes (if `use_names` is `TRUE`, then it must start with '/')
`use_names` : | if `TRUE`, then `tree_path` will be interpreted as a unix style path, and if `FALSE`, then `tree_path` will be interpreted similarly to the GtkTreePath's string representation.
Returns : | the requested GdaTreeNode pointer, or `NULL` if not found. [transfer none][allow-none]

Since 4.2

### gda_tree_get_node_path ()

    gchar *             gda_tree_get_node_path              (GdaTree *tree,
                                                             GdaTreeNode *node);

Get the path associated to `node` in `tree`.

`tree` : | a GdaTree
`node` : | a GdaTreeNode node in `tree`
Returns : | a new string, or `NULL` if `node` is not in `tree`. [transfer full]

Since 4.2

### gda_tree_get_node_manager ()

    GdaTreeManager *    gda_tree_get_node_manager           (GdaTree *tree,
                                                             GdaTreeNode *node);

Get the GdaTreeManager which created `node` in `tree`

`tree` : | a GdaTree
`node` : | a GdaTreeNode present in `tree`
Returns : | the GdaTreeManager, or `NULL` if `node` is not present in `tree`. [transfer none]

Since 4.2

### gda_tree_set_attribute ()

    void                gda_tree_set_attribute              (GdaTree *tree,
                                                             const gchar *attribute,
                                                             const GValue *value,
                                                             GDestroyNotify destroy);

Sets an attribute to `tree`, which will be accessible to any node in it.

`tree` : | a GdaTree object
`attribute` : | attribute name
`value` : | a GValue, or `NULL`
`destroy` : | a function to be called when `attribute` is not needed anymore, or `NULL`

Since 4.2

### gda_tree_dump ()

    void                gda_tree_dump                       (GdaTree *tree,
                                                             GdaTreeNode *node,
                                                             FILE *stream);

Dumps the contents of `tree` to `stream`, using a hierarchical view.

`tree` : | a GdaTree
`node` : | a GdaTreeNode to start the dump from, or `NULL` for a full dump. [allow-none]
`stream` : | a stream to send the dump to, or `NULL` for STDOUT. [allow-none]

Since 4.2

## Property Details

### The `"is-list"` property

      "is-list"                  gboolean              : Read

Tells if the GdaTree is a list or a tree.

Default value: FALSE

## Signal Details

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

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

Gets emitted when a `node` has changed in `tree`

`tree` : | the GdaTree
`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                      (GdaTree *tree,
                                                            gchar   *node_path,
                                                            gpointer user_data)      : Run Last

Gets emitted when a `node` has been removed from `tree`

`tree` : | the GdaTree
`node_path` : | the position the node held in `tree` as a tree path
`user_data` : | user data set when the signal handler was connected.

Since 4.2

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

    void                user_function                      (GdaTree     *tree,
                                                            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

`tree` : | the GdaTree
`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                      (GdaTree     *tree,
                                                            GdaTreeNode *node,
                                                            gpointer     user_data)      : Run Last

Gets emitted when a `node` has been inserted in `tree`

`tree` : | the GdaTree
`node` : | the GdaTreeNode which has inserted
`user_data` : | user data set when the signal handler was connected.

Since 4.2