A composite node using callbacks to implement its contents. During the creation,
each instance gets three callbacks that are called by the LE-area to get
information about its content. Potential children (this term is used
for represented children regardless of the state of their expansion, so the
potential children need not to be children of the LE-area in the VCL node tree
meaning) are represented by a meaningless void *
pointer. Children are expanded (when needed) to VCL nodes, which are
cached inside the LE-area. The creator is also responsible for sending
notifications (using _notification functions) about interesting
events regarding the visualised objects.
It supports the object interface, the node interface, the container interface and the composite interface.
Callbacks
All callback headers contain the data argument, which is user data
registered together with the callback.
void (* get_bbox_of_child_fn_t) (void * child_id,
struct vcl_le_area * questioner,
struct geom_rectangle *bbox, void * data)
The first callback is used by the LE-area to ask about the bbox of a child
child_id. The callee is required to fill the *bbox (in local
coordinates).
void * (* expand_child_fn_t) (void * child_id,
struct vcl_le_area * questioner, void * data)
The second callback is used by the LE-area to expand a meaningless child ID to
a VCL node. The callee is required to return a (parent-free) VCL node
representing the child_id child. The caller (LE-area) is then
responsible for destroying that node.
void (* get_children_fn_t) (struct vcl_le_area * questioner, uns backwards,
const struct geom_rectangle * bbox, void * data)
The third callback is used by the LE-area to ask about children in the
bbox. The callee is required to answer using one call
vcl_le_area_answer_child_in_bbox() per one item inside the
*bbox, the callee is allowed (but not required) to ignore items
outside *bbox. The items should be answered in the order from front to
back, unless backwards is true.
Functions
struct vcl_le_area * vcl_le_area_new (get_bbox_of_child_fn_t cb1,
void * cb1_data, expand_child_fn_t cb2,
void * cb2_data, get_children_fn_t cb3,
void * cb3_data)
Creates an LE-area with the appropriate callbacks.
vcl_le_area_flush (struct vcl_le_area * obj,
const struct geom_rectangle *new_bbox)
Flushes all cached children nodes and stored information and sets a new
internal bounding box. *new_bbox must encompass all new
potential children of the LE-area. It can be used instead of many
child disappearance and child appearance notifications after a massive
reorganisation of represented data.
void vcl_le_area_answer_child_in_bbox (struct vcl_le_area * obj,
void * child_id)
Answers the get_children callback.
void vcl_le_area_child_altered_notification (struct vcl_le_area * obj,
void * child_id, const struct geom_rectangle *where)
A notification about a bounding box preserving change in a potential child
child_id, where where is the bounding box of the changed part of
the potential child.
void vcl_le_area_child_changed_notification (struct vcl_le_area * obj,
void * child_id, const struct geom_rectangle *old_bbox,
const struct geom_rectangle *new_bbox)
A notification about a major change of a potential child, where
old_bbox is the old bounding box of the potential child and new_bbox is
the new bounding box of the potential child.
void vcl_le_area_child_transformed_notification (struct vcl_le_area * obj,
void * child_id, const struct geom_rectangle *old_bbox,
const struct geom_rectangle *new_bbox,
const struct geom_transform2 * trans)
A notification about a major change of a potential child which has the character
of an affine transformation, where old_bbox is old the bounding box of
the potential child, new_bbox is the new bounding box of the potential
child, and trans is the given transformation.
For one event, there should be only one call to one of the
vcl_le_area_child_altered_notification
vcl_le_area_child_changed_notification
vcl_le_area_child_transformed_notification
void vcl_le_area_child_appeared_notification (struct vcl_le_area * obj,
void * child_id)
A notification about a new potential child.
void vcl_le_area_child_disappeared_notification (struct vcl_le_area * obj,
void * child_id)
A notification about the vanishing of a potential child.
void * vcl_le_area_child_lookup (struct vcl_le_area * obj, void * child_id)
Does a lookup in the internal cache of children representing nodes. Returns
the appropriate node of child_id if it is in the cache, NULL
otherwise. The node is locked to prevent it from being destroyed by the LE-area. The callee is
not responsible for destroying the returned node.
void vcl_le_area_child_unlock (struct vcl_le_area * obj, void * child_id)
Unlocks a cache item locked by vcl_le_area_child_lookup().