## GdaTreeManager

GdaTreeManager — Base class for all the tree managers

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        GdaTreeManager;
    GSList *            (*GdaTreeManagerNodesFunc)          (GdaTreeManager *manager,
                                                             GdaTreeNode *node,
                                                             const GSList *children_nodes,
                                                             gboolean *out_error,
                                                             GError **error);
    GdaTreeManager *    gda_tree_manager_new_with_func      (GdaTreeManagerNodesFunc update_func);
    void                gda_tree_manager_add_manager        (GdaTreeManager *manager,
                                                             GdaTreeManager *sub);
    const GSList *      gda_tree_manager_get_managers       (GdaTreeManager *manager);
    void                gda_tree_manager_add_new_node_attribute
                                                            (GdaTreeManager *manager,
                                                             const gchar *attribute,
                                                             const GValue *value);
    GdaTreeNode *       (*GdaTreeManagerNodeFunc)           (GdaTreeManager *manager,
                                                             GdaTreeNode *parent,
                                                             const gchar *name);
    void                gda_tree_manager_set_node_create_func
                                                            (GdaTreeManager *manager,
                                                             GdaTreeManagerNodeFunc func);
    GdaTreeManagerNodeFunc gda_tree_manager_get_node_create_func
                                                            (GdaTreeManager *manager);
    GdaTreeNode *       gda_tree_manager_create_node        (GdaTreeManager *manager,
                                                             GdaTreeNode *parent,
                                                             const gchar *name);

## Object Hierarchy

      GObject
       +----GdaTreeManager
             +----GdaTreeMgrLdap
             +----GdaTreeMgrColumns
             +----GdaTreeMgrLabel
             +----GdaTreeMgrSchemas
             +----GdaTreeMgrSelect
             +----GdaTreeMgrTables

## Properties

      "func"                     gpointer              : Read / Write / Construct
      "recursive"                gboolean              : Read / Write / Construct

## Description

A GdaTreeManager object is responsible for creating nodes in the tree(s) for which it operates.

When creating nodes, a GdaTreeManager object can (depending on its implementation), get some named attributes from the node below which it has to create nodes, using the `gda_tree_node_fetch_attribute()` or `gda_tree_node_get_node_attribute()`. For example the GdaTreeMgrColumns manager (which creates a node for each column of a table) needs the table name and the schema in which the table is; both can be specified using an object's property, or, if not specified that way, are fetched as attributes.

The GdaTreeManager itself is an abstract type (which can't be instantiated). Use an existing sub class or subclass it yourself.

## Details

### GdaTreeManager

    typedef struct _GdaTreeManager GdaTreeManager;

### GdaTreeManagerNodesFunc ()

    GSList *            (*GdaTreeManagerNodesFunc)          (GdaTreeManager *manager,
                                                             GdaTreeNode *node,
                                                             const GSList *children_nodes,
                                                             gboolean *out_error,
                                                             GError **error);

### gda_tree_manager_new_with_func ()

    GdaTreeManager *    gda_tree_manager_new_with_func      (GdaTreeManagerNodesFunc update_func);

Use this method to create a new GdaTreeManager if it's more convenient than subclassing; all is needed is the `update_func` function which is responsible for creating or updating the children nodes of a specified GdaTreeNode.

`update_func` : | the function to call when the manager object is requested to create or update its list of GdaTreeNode nodes. [scope call]
Returns : | a new GdaTreeManager. [transfer full]

Since 4.2

### gda_tree_manager_add_manager ()

    void                gda_tree_manager_add_manager        (GdaTreeManager *manager,
                                                             GdaTreeManager *sub);

Adds a sub manager to `manager`. Use this method to create the skeleton structure of a GdaTree. Note that a single GdaTreeManager can be used by several GdaTree objects or several times in the same GdaTree's structure.

Please note that it's possible for `mgr` and `sub` to be the same object, but beware of the possible infinite recursive behaviour in this case when creating children nodes (depending on the actual implementation of the GdaTreeManager).

`manager` : | a GdaTreeManager object
`sub` : | a GdaTreeManager object to add

Since 4.2

### gda_tree_manager_get_managers ()

    const GSList *      gda_tree_manager_get_managers       (GdaTreeManager *manager);

Get the list of sub managers which have already been added using `gda_tree_manager_add_manager()`

`manager` : | a GdaTreeManager object
Returns : | a list of GdaTreeMenager which should not be modified. [transfer none][element-type Gda.TreeManager]

Since 4.2

### gda_tree_manager_add_new_node_attribute ()

    void                gda_tree_manager_add_new_node_attribute
                                                            (GdaTreeManager *manager,
                                                             const gchar *attribute,
                                                             const GValue *value);

Requests that for any new node managed (eg. created) by `manager`, a new attribute will be set. This allows one to customize the attributes of new nodes created by an existing GdaTreeManager.

As a side effect, if `value` is `NULL`, then the corresponding attribute, if it was set, is unset.

`manager` : | a GdaTreeManager
`attribute` : | an attribute name
`value` : | the attribute's value, or `NULL`. [allow-none]

Since 4.2

### GdaTreeManagerNodeFunc ()

    GdaTreeNode *       (*GdaTreeManagerNodeFunc)           (GdaTreeManager *manager,
                                                             GdaTreeNode *parent,
                                                             const gchar *name);

### gda_tree_manager_set_node_create_func ()

    void                gda_tree_manager_set_node_create_func
                                                            (GdaTreeManager *manager,
                                                             GdaTreeManagerNodeFunc func);

Sets the function to be called when a new node is being created by `manager`. If `func` is `NULL` then each created node will be a GdaTreeNode object.

Specifying a custom GdaTreeManagerNodeFunc function for example allows one to use specialized sub-classed GdaTreeNode objects.

`manager` : | a GdaTreeManager tree manager object
`func` : | a GdaTreeManagerNodeFunc function pointer, or `NULL`. [allow-none][scope call]

Since 4.2

### gda_tree_manager_get_node_create_func ()

    GdaTreeManagerNodeFunc gda_tree_manager_get_node_create_func
                                                            (GdaTreeManager *manager);

Get the function used by `manager` when creating new GdaTreeNode nodes

`manager` : | a GdaTreeManager tree manager object
Returns : | the GdaTreeManagerNodeFunc function, or `NULL` if the default function is used

Since 4.2

### gda_tree_manager_create_node ()

    GdaTreeNode *       gda_tree_manager_create_node        (GdaTreeManager *manager,
                                                             GdaTreeNode *parent,
                                                             const gchar *name);

Requests that `manager` creates a new GdaTreeNode. The new node is not in any way linked to `manager` yet, consider this method as a GdaTreeNode factory.

This method is usually used when implementing a GdaTreeManagerNodesFunc function (to create nodes), or when subclassing the GdaTreeManager.

`manager` : | a GdaTreeManager
`parent` : | the parent the new node may have, or `NULL`. [allow-none]
`name` : | name given to the new node, or `NULL`. [allow-none]
Returns : | a new GdaTreeNode. [transfer full]

Since 4.2

## Property Details

### The `"func"` property

      "func"                     gpointer              : Read / Write / Construct

This property specifies the function which needs to be called when the list of GdaTreeNode nodes managed has to be updated

### The `"recursive"` property

      "recursive"                gboolean              : Read / Write / Construct

This property specifies if, when initially creating nodes or updating the list of nodes, the tree manager shoud also request that each node it has created or updated also initially create or update their children.

This property can typically set to FALSE if the process of creating children nodes is lenghty and needs to be postponed while an event occurs.

Default value: TRUE