Given an LqrCarver object, it is possible to attach an arbitrary number of extra carvers to it: these will passively undergo the same carving process as the root carver. In order for this to be possible, the carvers must be all of the same size.

The function to use is simply:

This attaches aux to carver.

It is not necessary that the parent LqrCarver is activated. In fact, a carver can be attached to a carver which is itself attached to another one.

Needless to say, no resizing operation should be done directly on an LqrCarver once it has been attached to another LqrCarver, and neither should the cancel method be invoked directly on them.

Attached carvers can be read-out in the same way as their parents. There are however also methods to span all them, in a way very similar to that in which internally dumped LqrVMap's are accessed, but LqrVMapList objects are substitued in this case by LqrCarverList objects.

First, the starting point of the list has to be retreived through:

Then, one can iterate through the attached carvers by using these two functions:

Here is a sample code usage:

LqrCarver *aux;
LqrCarverList *list;

list = lqr_carver_list_start (carver);
while (list) {
    aux = lqr_carver_list_current (list);
    /* ... do something on aux ... */
    list = lqr_carver_list_next (list);
}
                        

The carvers will always be accessed in the order in which they were attached.

Alternatively, one can apply a function to all the elements of the list (and recursively to all the elements of their attached lists, if there are any), through this function:

To use this second method, you'll need to define a function first, as in the following sample code:

LqrRetVal my_func (LqrCarver *aux, LqrDataTok data)
{
    /* ... do something on aux ... */
    return LQR_OK;
}

LqrCarverList *list;
LqrDataTok data_tok;

list = lqr_carver_list_start (carver);
data_tok->data = NULL;
lqr_carver_list_foreach_recursive (list, my_func, data_tok);
                        

The data to be passed on to the LqrCarverFunc is of type LqrDataTok. This is defined as a union, with the following fields:

In the above example, no data is actually passed on to the function.