Each model object can be referenced by multiple view objects which implement the functionality that allows them to be visualized. This implicates that view objects have coordinates and regions associated with them. Additionally, they have a notion of being selectable and resizable, actions that are typically found in visual editing. Finally, certain view classes, such as VisualNode and VisualEdge, extend interfaces which allow them to be automatically positioned by the layout engine. We will discuss these interfaces in more detail later.

The visualization of a view object is done with the help of a so-called Composite, a compound graphical object built upon Primitive parts. As you might have already guessed, these objects are defined by the two Java® interfaces Composite and Primitive. A graphical style, such as a stroke, fill pattern or font, can be assigned to each graphical Primitive where appropriate. These objects can then be grouped inside any Composite parent container. In this way, primitives can be used to compose complex graphical shapes.

In order to build even more complex visual shapes, ones that represent entire visual subgraphs, we provide a specialized, derived interface named CompositeGroup. Instances of this type are also Composite objects capable of nesting other Composite objects as well, providing you with the ability to nest arbitrarily complex levels of primitives.

There is a close dependency between the visually-scoped objects from the Graph library and the Composite library. For example, objects of type VisualNode use Composite instances for their rendering. The Tensegrity Graph Framework requires that each VisualNode instance be associated 1:1 with a Composite instance. Of course, this instance may be any subtype implementation as well. In addition, instances of type VisualSubgraph have a 1:1 association with an an instance of type CompositeGroup.

Figure 1.2. Classdiagram Graph View - Composite Associations

The association between a Composite and a view object is permanent. This means that once a view object has been created, its reference to the associated Composite can no longer be changed.

This interface represents the aspects common to all visual graph elements, including a VisualNode, VisualEdge and VisualSubgraph. The first of these aspects includes the identifiable nature of these elements. Every VisualGraphObject has both an identifier unique to its context as well as a global identifier that is unique within a hierarchy of VisualGraph objects. Methods to access both of these identifiers are available.

Each VisualGraphObject implementation is constructed with an initial identifier of -1. When a VisualGraphObject is added to a GraphObjectContainer, the identifier is changed internally by the container to a value that becomes unique within that container context. The container may nest other containers recursively, which might have the same identifier assigned to one of their managed objects. Identifiers, therefore, are unique within the scope of a single GraphObjectContainer only.

When a VisualGraphObject is removed from a GraphObjectContainer, the identifier is reset to -1.

Each VisualGraphObject can only be stored in one dedicated VisualGraphObjectContainer at a time.

The identifiers that are internally assigned to a VisualGraphObject corresponds with the identifier of the associated model object. In this way, a mapping from model to view objects is possible. You can create multiple VisualGraphObject instances that all reference the same model object.

Moreover, objects of this type are represented by a Composite, reference a Graph model and possess behavior specified by custom Rule objects. ^[2].

The following a list of the important methods offered by this interface:

VisualGraphObject instances are visual representations of GraphObject instances. Moreover, these visual types extend interface Layoutable so that they may be automatically positioned by a LayoutController.

This interface represents the functionality of any potential Node representation. By incorporating the functionality of a Composite object, it becomes possible to assign complex shapes and styles to an instance of this class.

The associated model Node can be obtained by invoking the getNode() method.

Here are important methods defined in the interface:

This interface represents the functionality of any potential Edge representation. By incorporating the functionality of a Composite object, it becomes possible to assign complex shapes and styles to an instance of this class.

Here are the most important methods defined in the interface:

This interface represents the visualization of a model Port that is contained and managed by a VisualNode.

This interface defines the characteristics of a single visual connection point to a VisualNode from which a VisualEdge instance is attached. In other words, an VisualEdge connects to a VisualNode via one of the many VisualPort instances owned and managed by a VisualNode, and not to the VisualNode directly.

A VisualPort uses a so-called VisualPortDenotation, which defines the angular interval where incoming and outgoing edges are allowed to connect to the associated VisualPort.

Visual ports have identifiers which can be returned to clients who request them.

The identifiers of a VisualPort and its associated model object always correspond and are unique within a single Graph, VisualGraph, Subgraph and VisualSubgraph. These identifiers are set to -1 when no longer contained by a parent component.

Each active VisualPort managed by a single VisualNode instance can be retrieved by invoking the method getVisualNode().

The number of VisualEdge objects that are currently connected to a VisualPort can be retrieved by invoking the method getRegisteredVisualEdgeCount(). The actual VisualEdge objects that are connected can be retrieved by invoking getRegisteredVisualEdges().

A VisualPort can have a number of different drawing states which are defined by the constants prefixed with DRAWINGSTATE_ and which can be set by invoking the method setDrawingState(int). This method is invoked internally by the library and usually there should not be any to need to invoke this method manually.

A VisualPort can either be direct (a so-called leaf-port) or indirect (a so-called wrapped-port). From the perspective of a library user, the difference is not significant. Wrapped-ports can themselves be wrapped up recursively. The method getDepth() can be used to find out the depth of nesting. The VisualNode that holds the leaf-port (the port that doesnt wrap-up other ports) can be queried by invoking the method getWrappedVisualNode().

The methods getCoordinate() and getBoundingBoxCoordinate() are used to find out the geometric position of a VisualPort. The later method returns the position in the CoordinateSystem of the enclosing VisualNode and thus is the one that is likely to be used in most cases.

This interface holds the methods that define the container role for classes that manage VisualGraphObject instances. This is the parent interface of both the VisualGraph and VisualSubgraph interfaces.

A VisualGraphObjectContainter will manage VisualNode and VisualEdge instances by providing implementations to add and remove objects of these types.

This interface defines a view of a Graph model as well but adds additional functional specifications. Implementations of class VisualGraphView represent the top-level containers within a hierarchy of nested VisualGraphObjectContainer instances and are responsible for the undo, redo, cut, copy and paste functionalities within a graph document.

VisualGraphView derives from and thus aggregates many interfaces, including VisualGraph, CompositeView and the VisualGraphObjectContainer interfaces, allowing clients to treat a VisualGraphView as one of many specific roles.

Also, it is important to note that a new VisualGraphView instance requires a reference to a GraphController, which must be advised to manage the newly created view after instantiation.

When new visual edges are introduced via edge-splitting, either manually or by user interaction, these new edges will be assigned a default style. This style can be configured for the entire view hierarchy by invoking the setDefaultEdgeStyle(String) method.

The paste orientation specifies how pasting preserves the relative order of connected VisualNode objects. See method setPasteOrientation(int).

VisualEdge update modes determine how connected VisualEdge objects should behave when the position of a VisualNode changes. Update modes can be set with method setVisualEdgeUpdateMode(int).

A VisualGraphView supports user interaction with the mouse. To do so it provides the methods listed below:

Other important methods defined in this interface are:

This abstract class defines the methods to create instances of all graph view objects.

By calling the static method newInstance(), you can obtain an instance that is assignable to this class.

A concrete implementation of this abstract class is GraphViewFactoryImpl. The following list contains a subset of the methods in this class.

Beside method newInstance the following static methods are provided to ease the VisualNode creation process.

Each and every view object must be associated with a corresponding model object. As a consequence, the creation of a view object cannot take place before the creation of its referenced model object. Along similar lines, no view objects may be added to a VisualGraph whose model objects do not belong to same Graph referenced by the VisualGraph

This system of adding model and view objects and later removing them follows the LIFO (Last in, First out) system. Before you can remove a model object from a Graph, you must first remove all view objects that reference it from their parent view containers.

If you are not creating objects of type Subgraph and VisualSubgraph, you will also not be using interface type VisualGraph directly. Instead, the interface type VisualGraphView is used whenever an actual visualization (including painting) is required. The following code snippet illustrates just how to create an empty VisualGraphView with a typical configuration.

VisualGraphView createVisualGraphView()
{
    // set up references to the factories
    GraphModelFactory modelfactory= 
        GraphModelFactory.newInstance();
    GraphViewFactory viewfactory= 
        GraphViewFactory.newInstance();
    GraphControllerFactory controllerfactory= 
        GraphControllerFactory.newInstance();

    // create a model-scope Graph
    Graph graph= modelfactory.newGraph();

    // create a default controller
    GraphController clientServerController= 
        controllerfactory.newClientServerGraphController(graph);
    
    VisualGraphView visualgraphview= 
        viewfactory.newVisualGraphView(clientServerController);
    
    // configure the visualgraphview in a typical way
    visualgraphview.setBoundingBox(0, 0, 0, 0);
    visualgraphview.enableClipping(true);
    visualgraphview.setSelectPastedElements(true);

    InteractionSettings settings= 
        visualgraphview.getInteractionSettings();
    settings.setPortsEnabled(true);
    settings.setAllowLoops(true);
    visualgraphview.setDefaultEdgeStyle("TenseLine");
    
    return visualgraphview;
}

This code not only creates a VisualGraphView instance but also the underlying model container of type Graph. The resulting structure is capable of representing model-scoped Node and Edge objects as part of the view representation.

As mentioned before, any view object can only be added if its associated model object has already been added to its corresponding model Graph. Suppose, for example, that we have an instance of type VisualGraphView that was created with the code provided in the previous example and stored in a local variable called visualgraphview. Adding two nodes and connecting them with an edge, in both the model and the view, would require the following code:

void addObjects(VisualGraphView visualgraphview) throws StaticException
{
    // set up factory references
    GraphModelFactory modelfactory= 
        GraphModelFactory.newInstance();
    GraphViewFactory viewfactory= 
        GraphViewFactory.newInstance();
    
    // first we create the nodes and edges
    Node node1= 
        GraphModelFactory.makeDefaultNode(modelfactory, "node1");
    Node node2= 
        GraphModelFactory.makeDefaultNode(modelfactory, "node2");

    VisualNode visualNode1= viewfactory.newVisualNode(node1,
        GeometryPool.get("Rectangle"));
    VisualNode visualNode2= viewfactory.newVisualNode(node2,
        GeometryPool.get("Rectangle"));
    Edge edge= modelfactory.newEdge(node1, node2);
    VisualEdge visualEdge= 
        viewfactory.newVisualEdge(
            edge, visualNode1, visualNode2);
    
    // add first node
    visualgraphview.getGraph().addNode(node1);
    visualgraphview.addVisualNode(visualNode2);
    
    // add second node
    visualgraphview.getGraph().addNode(node2);
    visualgraphview.addVisualNode(visualNode1);
    
    // add edge
    visualgraphview.getGraph().addEdge(edge);
    visualgraphview.addVisualEdge(visualEdge);
}

The following code illustrates how to remove the objects that were added in the previous example.

void removeObjects(VisualGraphView visualgraphview)
        throws StaticException
{
    // remove edge
    VisualEdge visualEdge= 
        (VisualEdge) visualgraphview.getVisualEdges().next();
    visualgraphview.removeVisualEdge(visualEdge);
    visualgraphview.getGraph().removeEdge(visualEdge.getEdge());
    
    // remove first node
    VisualNode tmpNode= 
        (VisualNode) visualgraphview.getVisualNodes().next();
    visualgraphview.removeVisualNode(tmpNode);
    visualgraphview.getGraph().removeNode(tmpNode.getNode());
    
    // remove another node
    tmpNode= 
        (VisualNode) visualgraphview.getVisualNodes().next();
    visualgraphview.removeVisualNode(tmpNode);
    visualgraphview.getGraph().removeNode(tmpNode.getNode());
}

Please note the order when removing objects. First a view object is removed, then the associated model object.