The BaseComposite interface is an aggregated interface that combines multiple roles and responsibilities. Apart from those roles which are inherited, this interface defines new methods that deal with the containment, management and drawing of Primitive objects to a Device.

It is very unlikely that you will create your own class that implements this abstract interface. More likely, you will use classes that already implement derived interfaces, such as Composite and CompositeLine, two concrete specifications that define the behavioral contracts for rectangular and line-based composites respectively.

This interface exists because client code does not always have to differentiate between rectangular and line composites, two types which exhibit deviant runtime behaviors.

Figure 2.3. Class Diagram BaseComposite

A far more comfortable way to add multiple Primitive objects to this container is by using an instance of interface GeometryDescriptor. These named objects are instantiated from an XML file and can be more easily defined and assembled. Moreover, a runtime object of this type provides the configuration data for several Primitive objects anyways. So instead of writing Java code to create the Primitive objects, you can define them as a GeometryDescriptor written in an XML file, load them at system startup and apply them by calling method applyGeometry(GeometryDescriptor)

Similarly, the appearance of a BaseComposite can be set by applying a StyleDescriptor. This object specifies how a Geometry is represented on the screen in terms of line styles, area fill and more. You can invoke the following method multiple times: applyStyle(StyleDescriptor)

A BaseComposite must be representable on the screen. Therefore, it uses a Renderer and a Device object to do so, as you can see in the following draw methods:

A BaseComposite is able to manage an InfoValue object. This value object can be used in many different ways. Therefore, the following constants are defined within the BaseComposite interface:

The Composite interface supplements the BaseComposite behavior by managing its own CoordinateSystem. In doing so, the coordinates of the contained Primitive objects remain independent of any other CoordinateSystem used in a view, such as that of a parent container or the top-level CompositeView.

Moreover, a Composite object has a location and a size within its managed CoordinateSystem and is set by a BoundingBox. This box defines the top-left corner and size of all inlying Primitive objects managed by the Composite container.

Taken together, the CoordinateSystem and BoundingBox of a Composite uniquely determine the transformation that is used when drawing the contained Primitive objects.

The CompositeLine interface is used whenever a line is drawn or two composites are connected with a link. This connecting edge is made up of a CompositeLine - a Composite that holds a line and behaves differently than normal composites.

The CompositeLine interface supplements the BaseComposite behavior by managing a set of Coordinate objects that are used by a parent CoordinateSystem.

Figure 2.4. Class Diagram CompositeLine

To modify the coordinates of a CompositeLine, please use the following methods:

This interface represents the top-level BaseCompositeContainer in a tree of like-kind containers. Clients will reference this interface type explicitly because it declares methods needed at the very top of the hierarchy. Moreover, a CompositeView merges several basic interfaces and offers special support for handling objects of type BaseComposite. This interface is a mighty specification: the classes which implement it are basically responsible for performing all drawing, event-handling, selection and notification tasks necessary for a top-level view container.

Figure 2.5. Class Diagram CompositeView

It should come as no surprise, then, that this interface is merged into the interface specification for VisualGraphView. This allows clients to speak to a top-level VisualGraph as if it were a CompositeView by nature.

A CompositeView will draw the following objects in the order specified:

A CompositeView supports user interaction by extending the InteractionProvider interface. In order to plug additional interaction behavior into an instance, you must register a CompositeInteractionHandler that is invoked by the CompositeView whenever some form of user interaction takes place. The table below gives information about how method calls are delegated.

For more information, please refer to the JavaDoc of interface CompositeInteractionHandler.

Because it is possible that the view area of CompositeView is much larger than the drawing area, scrollbars are usually needed to make the entire view area visible to the user. Since scrollbars cannot be attached to a CompositeView, the relevant scroll information can nevertheless be provided to an object that requires it. These are the methods to call:

Additionally, this interface specifies that Primitive objects can be used to draw a title and other background graphics, objects which should not respond to mouse events. In other words, these primitives should only be used for the views static adornment. The methods to manage these Primitive objects are:

Two methods deal with the layered positioning of contained BaseComposite instances:

A CompositeView has both a CoordinateSystem and its own BoundingBox which allows it to scale and position all child composites contained below it. The relevant methods are:

In addition to its own CoordinateSystem, a CompositeView uses a second instance, which it calls the "reference coordinate system." This CoordinateSystem is used to define how much of the view area should be visible within the viewport of the CompositeView. The following method is used to retrieve this CoordinateSystem.

A CompositeView also supports different modes which can be externally configured.

These modes can be manipulated using the following methods:

As a container of BaseComposite objects, a CompositeView will mediate all occurring events propagated by objects of type Composite, CompositeLine, CompositeGroup and, of course, its own type (CompositeView).

To be informed about these events, one must add an EventMediatorListener or a VetoableEventMediatorListener to a CompositeView instance.

The following interfaces can provide you with more information about the event mediator mechanism: EventMediator, EventMediatorListener, VetoableEventMediator, VetoableEventMediatorListener.

The relevant event mediation methods are:

Events are delivered in the following order:

A CompositeView object fires events for every conceivable change that can happen to it. In order to be notified about the occurrence of these events, an object which implements the CompositeViewListener interface must be registered with an instance of this class.

Some of the events fired by a CompositeView may be vetoed, which means that the processing of an event can be stopped. To veto an event, one must register a VetoableCompositeViewListener with an instance of this class.

The event-throwing mechanism of a CompositeView can be turned on and off. By invoking the enableEvents method and supplying the specific event mask, you can control which events are thrown. A call to disableEvents, on the other hand, suitably turns off the specified events marked by the event mask parameter.

By default all events are turned on. To determine which events are enabled or disabled, you can invoke the areEventsEnabled method. The event masks are defined by an enumeration in this interface or in an interface that extends this one. Event mask names always start with the EVENT_MASK prefix. The methods a CompositeView exposes to support the event mechanism are:

An example arrangement

Composite objects hold their own CoordinateSystem, which is nested within the CoordinateSystem of a parent CompositeGroup or CompositeView. The BoundingBox of a Composite, moreover, defines its size and location and should be specified using the CoordinateSystem of its parent view.

Imagine a scenario with the following components:

• A view with an x-axis going from 0 to 7000 and a y-axis of the same length.

• Composite one:

  • CoordinateSystem: x-Axis from 0 to 2000, y-Axis from 0 to 2000

  • BoundingBox: left-top: (1000, 1000), right-bottom: (2000, 4000)

• Composite two:

  • CoordinateSystem: x-Axis from 0 to 2000, y-Axis from 0 to 2000

  • BoundingBox: left-top: (5000, 5000), right-bottom: (6500, 6500)

A visualization of this arrangement looks as follows:

Figure 2.6. An arrangement of Composites in a Composite View

Note

Note the CoordinateSystem of the second Composite. Although it has the same maximum values as the first, the Composite does not have the same size in the view because its size is determined by its BoundingBox. The layout of Primitive objects in a Composite, however, is done by using the CoordinateSystem of a Composite.

Now let us see how to create a Composite programmatically. First of all, we need to create a CompositeView:

// Get a CompositeFactory instance
CompositeFactory factory= CompositeFactory.newInstance();
//  Create a view with the given CoordinateSystem Composite
CompositeView compositeView= factory.newCompositeView();

As you can see, we have chosen to use MutableScale and MutableCoordinateSystem objects so that we can change the minimum and maximum values later.

Now lets create a new Composite. In the following examples we will create two of them:

CoordinateSystem coordSystem1= 
    new MutableCoordinateSystem(
        new DefaultMutableScaleLinear(0, 2000),
        new DefaultMutableScaleLinear(0, 2000));
Composite composite1= factory.newComposite(coordSystem1);
composite1.setBoundingBox(1000, 4000, 1000, 3500);

The creation of the second Composite is equivalent:

CoordinateSystem coordSystem2= 
    new MutableCoordinateSystem(
        new DefaultMutableScaleLinear(0, 2000),
        new DefaultMutableScaleLinear(0, 2000));
Composite composite2= factory.newComposite(coordSystem2);
composite2.setBoundingBox(5000, 6500, 5000, 6500);

Now we can add the two newly-created Composite instances to the view by simply calling its addComposite method:

compositeView.addComposite(composite1);
compositeView.addComposite(composite2);

Although the above code is not ready for use, it should give you a basic understanding how to deal with the CoordinateSystem and BoundingBox of a Composite. This example^[4] is provided to get you used to the basic concepts of the CompositeAPI. We will have a look at some real world examples in later sections.