Hierarchy events in nested managers

Programmer's documentation > Rogue Wave JViews Framework Advanced Features > Nested managers and nested graphers > Hierarchy events in nested managers

Listeners registered with addManagerTreeContentChangedListener receive events from all changes to children and their descendents in the hierarchy of nested managers.

An event is created on the manager that contains the changed object and it is propagated upwards in the hierarchy to the ancestors. Typically, the event listener is added to the root of the hierarchy.

Conversely, hierarchy events are propagated downwards in the hierarchy to the descendents. They are similar to java.awt.event.HierarchyEvent and notify the descendents about a change made to their ancestors. Typically, hierarchy event listeners are added to the leaves of the hierarchy.

Two types of hierarchy events exist:

The GraphicBagHierarchyEvent installed by addGraphicBagHierarchyListener,

The ManagerViewsChangedEvent installed by addManagerViewsHierarchyListener.

Graphic bag hierarchy events

When a submanager is added to or removed from its manager, a Graphic Bag Hierarchy event is fired. It notifies all objects contained in the submanager recursively that the root of the submanager nesting hierarchy has changed. The objects that can receive this event are IlvManager, IlvGraphicSet, IlvGraphicHandleBag and their subclasses.

In order to add a listener for Graphic Bag Hierarchy events or remove one, you can call the following methods on a submanager (or on IlvGraphicSet or IlvGraphicHandleBag ):

void addGraphicBagHierarchyListener (GraphicBagHierarchyListener

listener)

void removeGraphicBagHierarchyListener (GraphicBagHierarchyListener

listener)

The GraphicBagHierarchyEvent contains the following information:

getGraphicBag() - this is the object whose graphic bag has changed,

getOldRootBag() - this is the root graphic bag of the entire hierarchy before

the change happened,

getNewRootBag() - this is the root graphic bag of the entire hierarchy after

the change happened.

NOTE The event is fired on the manager, graphic set or graphic handle bag whose graphic bag has changed. It is propagated recursively to all children that implement the GraphicBagHierarchyEventReceiver interface. It is not propagated to children whose ancestors do not implement the GraphicBagHierarchyEventReceiver interface, because the recursive propagation of the event stops on the object that does not implement that interface. For example, if a manager contains an object of type IlvGraphicHandle, which contains an IlvGraphicSet, then the event is not received by the IlvGraphicSet because the IlvGraphicHandle does not implement the interface. However, if the manager contains an object of type IlvFullZoomingGraphic, which contains an IlvGraphicSet, then the event is received by the IlvGraphicSet because both IlvFullZoomingGraphic and IlvGraphicSet implement the interface.

Manager views changed events

ManagerViewsChangedEvent events are fired when a view is added to or removed from a manager. To install listeners for these events on a manager, use the following methods:

addManagerViewsListener

removeManagerViewsListener

For details, see Listener for the views of a manager.

Listeners installed with this API will only receive events when a view is added directly to the manager. In a nested hierarchy of managers, a submanager does not receive the event if the view is added to the root manager of the hierarchy, even though the submanager will be visible in that view.

It is possible to install listeners of the ManagerViewsChangedEvent events so that they also receive the events from the ancestor managers. Use the following API to achieve this:

addManagerViewsHierarchyListener

removeManagerViewsHierarchyListener

This API can be used on IlvManager, IlvGraphicSet, IlvGraphicHandleBag and their subclasses. If a view is added to the root manager, the event is propagated to all the contained objects that have a listener added with this API.

NOTE The event is fired by the manager where a view is added or removed. It is propagated recursively to all children that implement the ManagerViewsHierarchyEventReceiver interface. It is not propagated to children whose ancestors do not implement the ManagerViewsHierarchyEventReceiver interface, because the recursive propagation of the event stops at an object that does not implement that interface. For example, if a manager contains an object of type IlvGraphicHandle, which contains an IlvGraphicSet, then the event is not received by the IlvGraphicSet because the IlvGraphicHandle does not implement the interface. However, if the manager contains an object of type IlvFullZoomingGraphic, which contains an IlvGraphicSet, then the event is received by the IlvGraphicSet because both IlvFullZoomingGraphic and IlvGraphicSet implement the interface.