Modeling Rules
Prev Chapter 1. Graph Basics Next

Modeling Rules

Rule objects are the preferred way of defining the capabilities and interactive behavior of VisualGraph elements. A Rule can, for example, be used to impose a limit on the number of incoming connections to a certain type of VisualNode or even specify that certain visual edges are not detachable. These customizations provide the flexibility that is required to use the GraphAPI in a broad variety of applications.

Every Rule has a name that is unique in a RuleRegistry instance. Once retrieved, the Rule name is then assigned to the elements of a VisualGraph object, whereby a global rule, the so-called GraphRule, is assigned to the top-level VisualGraphView object itself. Each visual object subsequently references the name of the rule it is associated with and automatically checks the rule for compliance prior to executing most of its runtime operations.

GraphObjectRule

Interface GraphObjectRule specifies the common attributes for the rules defined in interfaces NodeRule and EdgeRule, which are associated with objects of classes VisualNode and VisualEdge respectively.

The attributes supported by the GraphObjectRule are listed below. You can find detailed information about each attribute afterwards.

  • Selectable

  • Movable

  • Resizable

  • Deletable

  • Copyable

  • Cutable

The selectable attribute specifies if the VisualGraphObject can be selected. It is associated with the selectable attribute of the BaseComposite assigned to the VisualGraphObject. Currently these two flags are only synchronized in one direction. If the selectable state is changed in the GraphObjectRule and the rule is applied again to the VisualGraphObject, the selectable state of the BaseComposite is changed accordingly. A change to the selectable state of the BaseComposite, however, is NOT reflected in the GraphObjectRule. This attribute specifies not only the selectable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the selectable attribute are listed below:

  • void setSelectable(boolean)

    Sets the selectable flag for this rule.

  • boolean isSelectable()

    Returns the selectable flag for this rule.

The deletable attribute specifies if the VisualGraphObject can be deleted. It specifies not only the deletable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the deletable attribute are listed below:

  • void setDeletable(boolean)

    Sets the deletable flag for this rule.

  • boolean isDeletable()

    Returns the deletable flag for this rule.

The movable attribute specifies if the VisualGraphObject can be moved. It is associated with the movable attribute of the BaseComposite assigned to the VisualGraphObject. Currently these two flags are only synchronized in one direction. If the movable state is changed in the GraphObjectRule and the rule is applied again to the VisualGraphObject, the movable state of the BaseComposite is changed accordingly. A change to the movable state of the BaseComposite, however, is NOT reflected in the GraphObjectRule. This attribute specifies not only the movable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the movable attribute are listed below:

  • void setMovable(boolean)

    Sets the movable flag for this rule.

  • boolean isMovable()

    Returns the movable flag for this rule.

The resizable attribute specifies if the VisualGraphObject can be resized. It is associated with the resizable attribute of the Composite assigned to the VisualNode and is associated to the manipulable attribute of the CompositeLine assigned to a VisualEdge. The association of two different flags has historical reasons. Currently, these flags are only synchronized in one direction. If the resizable state is changed in the GraphObjectRule and the rule is applied again to the VisualNode or the VisualEdge, the resizable state of the Composite or the manipulable state CompositeLine is changed accordingly. A change to the resizable state of the Composite or the manipulable state of the CompositeLine, however, is NOT reflected in the GraphObjectRule. This attribute specifies not only the resizable state or the manipulable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the resizable attribute are listed below:

  • void setResizable(boolean)

    Sets the resizable flag for this rule.

  • boolean isResizable()

    Returns the resizable flag for this rule.

The copyable attribute specifies if the VisualGraphObject can either be copied to the clipboard or copied through a copy-on-move operation. It specifies not only the copyable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the copyable attribute are listed below:

  • void setCopyable(boolean)

    Sets the copyable flag for this rule.

  • boolean isCopyable()

    Returns the copyable flag for this rule.

The cutable attribute specifies if the VisualGraphObject can be cut to the clipboard. It depends on the state of the copyable attribute. A copyable state of false prohibits to cut a VisualGraphObject to the clipboard. This attribute specifies not only the cutable state of the VisualGraphObject for user interaction but also for API calls. The methods provided by the GraphObjectRule to support the cutable attribute are listed below:

  • void setCutable(boolean)

    Sets the cutable flag for this rule.

  • boolean isCutable()

    Returns the cutable flag for this rule.

NodeRule

Class NodeRule implements the rule template for VisualNode objects. Such a rule contains a set of properties whose combined values, including those defined in GraphObjectRule, define the runtime behavior of those nodes which are associated with the rule.

The attributes supported by the NodeRule are listed below. You can find detailed information about each attribute afterwards.

  • IndegreeMinimum

  • IndegreeMaximum

  • OutdegreeMinimum

  • OutdegreeMaximum

  • InstanceMinimum

  • InstanceMaximum

  • DrawPorts

  • DetachOnMove

  • Cascade1To1NodeDelete

  • CascadeDeleteEdges

  • ProhibitEdgeSplit

  • DisallowedEdgeSplitNodes

  • AcceptLooseNodesIfSubgraph

  • LegalSubgraphs

  • NodeOverlayEdgeCreation

  • NodeOverlayIndicationHandler

  • NodeDropHandler

  • SubgraphRemoveHandler

  • NodeMovedInSubgraphHandler

The minimum-indegree attribute specifies the minimum number of incoming VisualEdges. For the indegree those VisualEdges are counted that are connected with their target end to a VisualPort of a VisualNode. The value for attribute is restricted to be an integer >= 0. This attribute is used with user interaction only. The methods provided by the NodeRule to support the indegree-minimum attribute are listed below:

  • int getIndegreeMinimum()

    Returns the indegreeMinimum value for this rule instance.

  • void setIndegreeMinimum(int)

    Sets the indegreeMinimum value for this rule instance.

The maximum-indegree attribute specifies the upper bound for the number of incoming VisualEdges. This means that the maximum number of incoming VisualEdges is calculated by the upper bound minus 1. For the indegree those VisualEdges are counted that are connected with their target end to a VisualPort of a VisualNode. The value for attribute is restricted to be an integer >= 0 whereas a value of zero is considered as unlimited. This attribute is used with user interaction only. The methods provided by the NodeRule to support the indegree-maximum attribute are listed below:

  • int getIndegreeMaximum()

    Returns the indegreeMaximum value for this rule instance.

  • void setIndegreeMaximum(int)

    Sets the indegreeMeximum value for this rule instance.

The minimum-outdegree attribute specifies the minimum number of outgoing VisualEdges. For the outdegree those VisualEdges are counted that are connected with their source end to a VisualPort of a VisualNode. The value for attribute is restricted to be an integer >= 0. This attribute is used with user interaction only. The methods provided by the NodeRule to support the outdegree-minimum attribute are listed below:

  • int getOutdegreeMinimum()

    Returns the outdegreeMinimum value for this rule instance.

  • void setOutdegreeMinimum(int)

    Sets the outdegreeMinimum value for this rule instance.

The maximum-outdegree attribute specifies the upper bound for the number of outgoing VisualEdges. This means that the maximum number of outgoing VisualEdges is calculated by the upper bound minus 1. the maximum number of outgoing VisualEdges. For the outdegree those VisualEdges are counted that are connected with their source end to a VisualPort of a VisualNode. The value for attribute is restricted to be an integer >= 0 whereas a value of zero is considered as unlimited. This attribute is used with user interaction only. The methods provided by the NodeRule to support the outdegree-maximum attribute are listed below:

  • int getOutdegreeMaximum()

    Returns the outdegreeMaximum value for this rule instance.

  • void setOutdegreeMaximum(int)

    Sets the outdegreeMaximum value for this rule instance.

The instance-minimum attribute specifies the minimum number of instances for VisualNodes of a certain type. VisualNodes with the same rule are considered to be of the same type. The value for attribute is restricted to be an integer >= 0. This attribute is used with user interaction only. The methods provided by the NodeRule to support the instance-minimum attribute are listed below:

  • int getInstanceMinimum()

    Returns the instanceMinimum value for this rule instance.

  • void setInstanceMinimum(int)

    Sets the instanceMinimum value for this rule instance.

The instance-maximum attribute specifies the upper bound for the number of of instances of VisualNodes of a certain type. This means that the maximum number of such VisualNodes is calculated by the upper bound minus 1. VisualNodes with the same rule are considered to be of the same type. The value for attribute is restricted to be an integer >= 0 whereas a value of zero is considered as unlimited. This attribute is not only used with user interaction but also with API calls. The methods provided by the NodeRule to support the instance-maximum attribute are listed below:

  • int getInstanceMaximum()

    Returns the instanceMaximum value for this rule instance.

  • void setInstanceMaximum(int)

    Sets the instanceMaximum value for this rule instance.

The draw-ports attribute specifies whether the VisualPorts of the VisualNode, it is assigned to, are highlighted when a VisualEdge is moved with the mouse. This attribute is used with user interaction only. The methods provided by the NodeRule to support the draw-ports attribute are listed below:

  • void setDrawPorts(boolean)

    Sets the draw-ports flag for this rule.

  • boolean isDrawPorts()

    Returns the draw-ports flag for this rule.

The detach-on-move attribute specifies whether to detach all adjacent VisualEdges from the VisualNode when the location of the VisualNode changes. This attribute is not only used with user interaction but also for API calls. The methods provided by the NodeRule to support the detach-on-move attribute are listed below:

  • void setDetachOnMove(boolean)

    Sets the detach-on-move flag for this rule.

  • boolean isDetachOnMove()

    Returns the detach-on-move flag for this rule.

The cascade-11node-delete attribute specifies whether to take the inbound VisualEdge and the outbound VisualEdge and replace them with a connected replacement VisualEdge that is connected to the same endpoints. This setting can only be applied to so-called 1-1-Nodes. 1-1-Nodes are VisualNodes with an indegree of exactly one and an outdegree of exactly one. This attribute is not only used with user interaction but also for API calls. The methods provided by the NodeRule to support the cascade-1To1-node-delete attribute are listed below:

  • void setCascade11NodeDelete(boolean)

    Sets the cascade 1-1-node deletion flag for this rule.

  • boolean isCascade11NodeDelete()

    Returns the cascade 1-1-node deletion flag for this rule.

The cascade-delete-edges attribute specifies whether to delete all adjacent VisualEdges when the VisualNode, they are connected to, is removed from a VisualGraph. This attribute is not only used with user interaction but also for API calls. The methods provided by the NodeRule to support the cascade-delete-edges attribute are listed below:

  • void setCascadeDeleteEdges(boolean)

    Sets the cascade edge deletion flag for this rule.

  • boolean isCascadeDeleteEdges()

    Returns the cascade edges deletion flag for this rule.

The prohibit-edge-split attribute specifies whether edge-split operations are prohibited. Notice:For further information about edge-split operations please see the documentation of EdgeRule This attribute is used with user interaction only. The methods provided by the NodeRule to support the prohibit-edge-split attribute are listed below:

  • void setEdgeSplitProhibited(boolean)

    Sets the edge-split-prohibited flag for this rule.

  • boolean isEdgeSplitProhibited()

    Returns the edge-split-prohibited flag for this rule.

The disallowed-edge-split-nodes attribute specifies a list of VisualNodes that are not allowed to split a VisualEdge. The VisualNodes are specified by means of a comma-separated list of rule-names that are assigned to the VisualNode. This attribute is cared only when the VisualNode, it is assigned to, is an instance of a VisualSubgraph. This attribute is used with user interaction only. The methods provided by the NodeRule to support the disallowed-edge-split-nodes attribute are listed below:

  • String getDisallowEdgeSplitRule()

    Gets the rule names that identifies which nodes to skip for edge-split operations.

  • void setDisallowEdgeSplitRule(String)

    Gets the rule names that identifies which nodes to skip for edge split operations.

  • Set getDisallowedEdgeSplitNodes()

    Returns the names of the disallowed edge-split nodes as a Set or null if there are no disallowed edge-split nodes registered which means that all nodes are allowed to split edges.

  • void setDisallowedEdgeSplitNodes(Set)

    Sets the disallowed edge-split node rule names (as Strings) for this rule. The given Set can be null which means that all nodes are allowed to split edges.

  • String getDisallowedEdgeSplitNodesAsString()

    Returns the disallowed edge-split nodes list concatenated into a single string where tokens are delimited by a comma. The order of the output is undefined and up to the library. Invokers of this method should not rely on any order of the node rule names.

  • boolean isDisallowedToSplitEdges(String)

    Returns a flag that indicates whether the node rule name given by noderule is allowed to split an edge or not. When the given node rule name is null the node is considered to be allowed to split edges. Otherwise the given node rule name has not to be contained in the disallowed edge-split nodes list to be allowed to split edges.

The accept-loose-nodes-if-subgraph attribute specifies whether the VisualNode, this rule is assigned to, accepts loose VisualNodes inside of it. Loose VisualNodes are those with an indegree and an outdegree of zero. In the case that a VisualNode is added and it is a loose one but crosses a VisualEdge with enabled edge-insert-mode, the VisualNode is not considered as a loose VisualNode This attribute is cared only when the VisualNode, it is assigned to, is an instance of a VisualSubgraph. This attribute is not only used with user interaction but also for API calls. The methods provided by the NodeRule to support the accept-loose-nodes-if-subgraph attribute are listed below:

  • void setAcceptLooseNodesIfSubgraph(boolean)

    Sets the accept-loose-nodes-if-subgraph flag for this rule.

  • boolean isAcceptLooseNodesIfSubgraph()

    Returns the accept-loose-nodes-if-subgraph flag for this rule.

The legal-subgraphs attribute specifies a list of VisualSubgraphs that may contain this type of VisualNode. The VisualSubgraphs are specified by means of a coma-separated list of rule names that are assigned to the VisualSubgraphs. This attribute is used with user interaction only. The methods provided by the NodeRule to support the legal-subgraphs attribute are listed below:

  • void setLegalSubgraphs(Set)

    Sets the is-legal-subgraph rule names (as Strings) for this rule. The given Set can be null which means that all subgraphs are legal.

  • String getLegalSubgraphsAsString()

    Returns the is-legal-subgraph list concatenated into a single string where tokens are delimited by a comma. The order of the output is undefined and up to the library. Invokers of this method should not rely on any order of the subgraph rule names.

  • Set getLegalSubgraps()

    Returns the names of the legal-subgraphs as a Set or null if there are no legal-subgraphs registered which means that all subgraphs are legal.

  • boolean isLegalSubgraph(String)

    Returns the is-legal-subgraph flag for this rule. If no legal subgraphs (either by specifying null or an empty list) is specified then all subgraphs are considered legal.

The node-overlay-edge-creation attribute specifies whether to automatically create a VisualEdge if a VisualNode is positioned over another VisualNode. This means exactly when the union of the bounding boxes of the two VisualNodes is not empty. The following String values are supported:

ValueDescription
none When the attributes value is set to none node-overlay-edge-creation is disabled.
forward When the attributes value is set to forward a VisualEdge is created from the underlying VisualNode to the above VisualNode.
backward When the attributes value is set to backward a VisualEdge is created from the above VisualNode to the underlying VisualNode.

If a VisualEdge with the desired orientation already exists between the two VisualNodes another VisualEdge will not be created. This attribute is used with user interaction only. The methods provided by the NodeRule to support the overlay-edge-creation attribute are listed below:

  • String getOverlayEdgeCreation()

    Gets the setting for automatic edge-creation on node overlay.

  • void setOverlayEdgeCreation(String)

    Sets the setting for automatic edge-creation on node overlay.

The node-overlay-indication-handler attribute specifies the name of the VisualNodeOverlayIndicationHandler to invoke when another node is dragged and obscuring (overlaying) the VisualNode that this rule is assigned to. Normally the VisualNodeOverlayIndicationHandler is used with the overlay-edge-creation in order to display a different overlay-edge-creation-highlight than the GraphAPI provides by default. It is NOT allowed to perform any operation on a VisualGraph when the VisualNodeOverlayIndicationHandler gets called by the GraphAPI. For further information about visualnode-overlayindication-handlers please see the documentation of VisualNodeOverlayIndicationHandler This attribute is only used with user interaction. The methods provided by the NodeRule to support the overlay-handler-name attribute are listed below:

  • String getVisualNodeOverlayIndicationHandlerName()

    Gets the name that identifies the VisualNodeOverlayIndicationHandler for this rule.

  • void setVisualNodeOverlayIndicationHandlerName(String)

    Sets the name that identifies the VisualNodeOverlayIndicationHandler for this rule. If the name does not refer an already registered handler, then it is nevertheless stored inside the rule in case the matching handler is registered at a later point in time.

The node-drop-handler attribute specifies the name of the VisualNodeDropHandler instance to invoke when a VisualNode is dropped on/added to the VisualNode this rule is assigned to. This attribute is cared only when the VisualNode, it is assigned to, is an instance of a VisualSubgraph. This attribute is used with user interaction only. For further information about node-drop-handlers please see the documentation of VisualNodeDropHandler The methods provided by the NodeRule to support the drop-handler-name attribute are listed below:

  • String getDropHandlerName()

    Gets the name that identifies the VisualNodeDropHandler for this rule.

  • void setDropHandlerName(String)

    Sets the name that identifies the VisualNodeDropHandler for this rule. In case the name refers to a non registered VisualNodeDropHandler the call has no effect until at a later point in time a matching handler is registered at an active instance of VisualNodeDropHandlerRegistry.

The subgraph-remove-handler attribute specifies the name of the VisualSubgraphRemoveHandler instance to invoke when a VisualNode is removed from the VisualNode this rule is assigned to. This attribute is cared only when the VisualNode, it is assigned to, is an instance of a VisualSubgraph. This attribute is used with user interaction only. For further information about remove-handlers please see the documentation of VisualSubgraphRemoveHandler The methods provided by the NodeRule to support the remove-handler-name attribute are listed below:

  • String getSubgraphRemoveHandlerName()

    Gets the name that identifies the VisualSubgraphRemoveHandler for this rule.

  • void setSubgraphRemoveHandlerName(String)

    Sets the name that identifies the VisualSubgraphRemoveHandler for this rule. If the name does not refer an already registered handler, then it is nevertheless stored inside the rule in case the matching handler is registered at a later point in time.

The node-moved-in-subgraph-handler attribute specifies the name of the VisualNodeMovedInSubgraphHander instance to invoke when a VisualNode is moved within the VisualNode this rule is assigned to. This attribute is cared only when the VisualNode, it is assigned to, is an instance of a VisualSubgraph. This attribute is used with user interaction only. For further information about visualnode-movedinsubgraph-handlers please see the documentation of VisualNodeMovedInSubgraphHandler The methods provided by the NodeRule to support the node-moved-in-subgraph-handler attribute are listed below:

  • String getNodeMovedInSubgraphHandlerName()

    Gets the name that identifies the VisualNodeMovedInSubgraphHandler for this rule.

  • void setNodeMovedInSubgraphHandlerName(String)

    Sets the name that identifies the VisualNodeMovedInSubgraphHandler for this rule. If the name does not refer an already registered handler, then it is nevertheless stored inside the rule in case the matching handler is registered at a later point in time.

EdgeRule

Class EdgeRule implements the rule template for VisualEdge objects. Such a rule contains a set of attributes whose combined values, including those defined in GraphObjectRule, define the runtime behavior of those visual edges which are associated with the rule.

The attributes supported by the EdgeRule are listed below. You can find detailed information about each attribute afterwards.

  • DetachableSource

  • DetachableTarget

  • EdgeInsertMode

  • SnapToPortDistance

The detachable-source attribute specifies whether the source end of a VisualEdge can be detached. It specifies the detachable source state of the VisualEdge for user interaction only. The methods provided by the EdgeRule to support the detachable-source attribute are listed below:

  • void setDetachableSource(boolean)

    Sets the detachableSource flag for this rule.

  • boolean isDetachableSource()

    Returns the detachableSource flag for this rule.

The detachable-target attribute specifies whether the target end of a VisualEdge can be detached. It specifies the detachable target state of the VisualEdge for user interaction only. The methods provided by the EdgeRule to support the detachable-target attribute are listed below:

  • void setDetachableTarget(boolean)

    Sets the detachableTarget flag for this rule.

  • boolean isDetachableTarget()

    Returns the detachableTarget flag for this rule.

The edge-insert-mode attribute refers to the edge-split operation. The following String values are supported:

ValueDescription
edge insert disabled The edge-split operation is disabled when the attributes value is set to edge insert disabled.
edge insert exact position When the attributes value is set to edge insert exact position the VisualNode dropped onto the VisualEdge splits the VisualEdge exactly the position where it has been dropped.
edge insert automatic center When the attributes value is set to edge insert automatic center the VisualNode dropped onto the VisualEdge splits the VisualEdge at its center position.

This attribute is used only with user interaction. The methods provided by the EdgeRule to support the edge-insert-mode attribute are listed below:

  • int getEdgeInsertMode()

    Returns the edge insert mode for this edge rule.

  • void setEdgeInsertMode(int)

    Sets the edge insert mode for this edge rule.

The snap-to-port-distance attribute specifies the distance which is used to let the source end or the target end of a VisualEdge automatically snap to a VisualPort when either the source end, the target end or the whole VisualEdge is moved around. A value less than zero it is automatically converted to zero. This attribute is used only with user interaction. The methods provided by the EdgeRule to support the edge-insert-mode attribute are listed below:

  • int getSnapToPortDistance()

    Returns the snap to port distance for this edge rule.

  • void setSnapToPortDistance(int)

    Sets the snap to port distance for this edge rule. If the argument is less than zero it is automatically set to zero silently.

Graph Rule

Class GraphRule implements the rule template for VisualGraph objects. Such a rule contains a set of attributes whose combined values define the runtime behavior of those VisualGraphs which are associated with the rule.

The attributes supported by the GraphRule are listed below. You can find detailed information about each attribute afterwards.

  • AutoSpaceMode

  • AcceptLooseObjects

  • EdgeSplitTolerance

  • EdgeInsertSinglePosition

  • NodeDropHandler

The autospace-mode attribute specifies whether or how to displace VisualNodes when they are added to a VisualGraph so that overlap is avoided. The following constants are supported:

ValueDescription
AUTOSPACEMODE_NONE The autospace-mode is disabled.
AUTOSPACEMODE_HORIZONTAL The VisualNodes are displaced to the left or to the right in order to avoid overlapping.
AUTOSPACEMODE_VERTICAL The VisualNodes are displaced to the top or to the bottom in order to avoid overlapping.

This attribute is used with user interaction only.

  • int getAutoSpaceMode()

    Gets the autospace mode for this GraphRule.

  • void setAutoSpaceMode(int)

    Sets the autospace mode for this GraphRule.

The accept-loose-objects attribute refers to VisualNodes as objects and it specifies whether the VisualGraph, this rule is assigned to, accepts loose VisualNode objects inside of it. Loose VisualNode objects are those with an indegree and an outdegree of zero. In the case that a VisualNode is added and it is a loose one but crosses a VisualEdge with enabled edge-insert-mode, the VisualNode is not considered as a loose VisualNode. This attribute is not only used with user interaction but also for API calls.

  • void setAcceptLooseObjects(boolean)

    Sets the accept-loose-objects flag for this GraphRule.

  • boolean isAcceptLooseObjects()

    Returns the accept-loose-objects flag for this GraphRule.

The edge-split-tolerance attribute specifies the maximum distance of a VisualNode to a VisualEdge to let the VisualNode split the VisualEdge. This attribute is used with user interaction only.

  • int getEdgeSplitTolerance()

    Returns the current tolerance for edge-splitting.

  • void setEdgeSplitTolerance(int)

    Sets the tolerance for edge-splitting.

The edge-insert-single-position attribute specifies whether a multi selection of VisualNodes split a VisualEdge at a certain position (e.g. the mouse cursor position) or of they split those VisualEdges they might geometrically overlay.

  • void setEdgeInsertSinglePosition(boolean)

    Sets the edge single position flag for this GraphRule.

  • boolean isEdgeInsertSinglePosition()

    Returns the edge single position flag for this GraphRule.

The node-drop-handler attribute specifies the name of the VisualNodeDropHandler instance to invoke when a VisualNode is dropped on/added to the VisualGraph this rule is assigned to. This attribute is used with user interaction only. For further information about node-drop-handlers please see the documentation of VisualNodeDropHandler

  • String getDropHandlerName()

    Returns the name that identifies the VisualNodeDropHandler for this GraphRule.

  • void setDropHandlerName(String)

    Sets the name that identifies the VisualNodeDropHandler for this GraphRule.

Rule Registry

Class RuleRegistry is primarily responsible for managing Rule instances. Rule registration and client lookup are also supported as well as the ability to define so-called default rules for visual objects (instances of classes VisualNode and VisualEdge).

Additionally, a RuleRegistry allows client code to register a RuleFeedback instance which gets notified whenever a Rule is triggered.

In order to manage Rule instances, a RuleRegistry behaves like a hash-map. When inserting Rule instances into the RuleRegistry, the name of the Rule is used as the key value. A Rule registered in this way can be later accessed using this name. One can iterate over the key (the rule names) of the registered Rule instances as well as over the registered Rule objects themselves. It is even possible to remove registered Rule instances either by name or by providing a reference to the Rule. Finally, it is possible to ask a RuleRegistry if a certain Rule instance has been registered with it. The container methods a RuleRegistry provides are given below:

  • boolean contains(Rule)

    Checks whether a rule is already registered in the rule registry.

  • boolean contains(String)

    Checks whether a rule is already registered in the rule registry.

  • Rule get(String)

    Looks up a rule in the map and returns it, null if none is found with the given name.

  • Iterator iterator()

    Returns an iterator for all registered rules.

  • Iterator keysIterator()

    Returns an iterator for all registered rule names.

  • Rule put(Rule)

    Registers a new rule in the registry with its name..

  • Rule remove(Rule)

    Removes a rule from the RuleRegistry.

  • Rule remove(String)

    Removes a rule by name from the RuleRegistry.

A GraphRule is treated in a special way. The RuleRegistry supports registration of one GraphRule instance only. In the context of the GraphAPI, this single GraphRule object is used globally for each instance of a VisualGraph. The GraphRule is defined through the normal put operation. Whenever an instance of a GraphRule is registered with a RuleRegistry, it is taken as the new global graph-rule. The methods the RuleRegistry provides in order to support the graph-rule are given below:

  • GraphRule getGraphRule()

    Returns the current GraphRule of this RuleRegistry. The returned value may be null.

The RuleRegistry supports the definition of a default EdgeRule for VisualEdges and a default NodeRule for VisualNodes. In the context of the GraphAPI these default rules are used to assign a rule to any VisualGraphObject that is added to a VisualGraph that hasnt assigned one. The methods the RuleRegistry provides in order to support the default rules are given below:

  • String getDefaultEdgeRule()

    Returns the name of the default EdgeRule or null if it is not set.

  • void setDefaultEdgeRule(String)

    Sets the name of the default EdgeRule. The given name must not be null and an EdgeRule with the given name must be registered at the RuleRegistry.

  • String getDefaultNodeRule()

    Returns the name of the default NodeRule or null if it is not set.

  • void setDefaultNodeRule(String)

    Sets the name of the default NodeRule. The given name must not be null and a NodeRule with the given name must be registered at the RuleRegistry.

As mentioned beforehand the RuleRegistry allows to register an instance of a RuleFeedback in order to get notifications whenever a rule check has passed or was rejected. The methods provided by the RuleRegistry in order to support it are listed below:

  • RuleFeedback getRuleFeedback()

    Returns the RuleFeedback callback interface from this RuleRegistry.

  • void setRuleFeedback(RuleFeedback)

    Sets the RuleFeedback callback interface for this RuleRegistry.

Relations and General Use

The last sections introduced the different rule objects independently. Now it is time to put them together and talk about the relationships among the attributes of certain rule objects. In doing so, this section provides some basic use cases and should inspire a sense of how the rules can be used to define the behavior of a modeled graph.

When modeling a graph, it soon becomes clear that there are certain tasks which you will perform again and again. For example, consider the simple operation of connecting two nodes. First the nodes are placed side by side. Then an edge is inserted into the graph. The source end of the edge is connected to one of the nodes and then the target end is connected to the other node. As you can see, performing such tasks repeatedly increases the time needed to model a graph and therefore decreases efficiency. Moreover, this kind of repetition can wear down the typical user.

The modeling capabilities of the GraphAPI encapsulate these operations and give them a speaking name. Hence it becomes possible to easily enable and disable them in a certain application.

Some of these capabilities are accessible through a single attribute in a certain rule object while others combine more than one attribute from multiple rule objects. The next sections show you how.

Automatic Port Snapping

Automatic-Port-Snapping means that either the source end, the target end or both ends automatically snap to a certain VisualPort of a VisualNode. This frees the user from the concentration required to find ports and hit them precisely with the mouse cursor. The sensitive area around a VisualPort, to which the end of a VisualEdge snaps, can be chosen freely. Obviously, these sensitive areas have to be defined such that they do not overlap.

Automatic-Port-Snapping is carried out when interaction stops and the user has moved the source end, the target end or a complete VisualEdge. A VisualEdge has to be selected.

The Automatic-Port-Snapping is controlled by the 'snap-to-port-distance' attribute of a EdgeRule. In order to disable the automatic-port-snapping feature, the value of this attribute is set to zero. A value greater than zero enables it and defines the sensitive area simultaneously.

The sensitive area is defined as a rectangle whose side lengths are double the value set for the 'snap-to-port-distance' attribute. The center of the rectangle is the location of the VisualPort.

Note

Under normal conditions, Automatic-Port-Snapping is assisted by port highlighting. Doing so indicates to the user where a VisualNode provides a VisualPort.

Port highlighting is configured through the InteractionSettings class that can be accessed from the VisualGraphView

Overlay Edge Creation

The overlay-edge-creation operation combines the steps of inserting a new VisualEdge, connect the source end of the inserted VisualEdge to one VisualNode and then connect the target end of the inserted VisualEdge to another VisualNode.

Overlay-edge-creation is controlled by the 'node-overlay-edge-creation' attribute of the NodeRule. This attribute supports three settings which disables the operation, forces to create a new VisualEdge from the underlying VisualNode to the above or vice versa.

It is carried out when a user interaction stops he has moved one VisualNode over another VisualNode and 'node-overlay-edge-creation' is activated for the above VisualNode. When the user releases the mouse button the two VisualNodes are connected automatically by a new VisualEdge. The newly created VisualEdge is configured with the default VisualEdge geometry and the default VisualEdge style. These two attributes can be set at the VisualGraphView.

The detection if two VisualNodes do overlay each other is done by the bounding boxes of these nodes. More exactly one could say that the union of the bounding boxes of the VisualNodes must not be emty.

While the user interaction is taking place and a VisualNode is dragged over another and 'node-overlay-edge-creation' is activated a highlight is displayed so that the user gets a feeback about what happens when he droppes the VisualNode at that location.

Note

The displayed highlight can be configured in two different ways.

One way is to make use of the InteractionHighlightConfiguration. It is accessible through the VisualGraphView. With the InteractionHighlightConfiguration you are able to specify a Composite that is displayed instead of the one defined in the GraphAPI by default. This Composite is automatically positioned by the GraphAPI.

The other way is to implement a VisualNodeOverlayIndicationHandler, register it at the VisualNodeOverlayIndicationHandlerRegistry of a VisualGraphView and set the value of the 'node-overlay-indication-handler' attribute to the name of the registered VisualNodeOverlayIndicationHandler. Doing so the VisualNodeOverlayIndicationHandler is called by the GraphAPI whenever a 'node-overlay-edge-creation' has to be indicated or has to be performed. The VisualNodeOverlayIndicationHandler has to return a collection of Composites which are displayed instead of the default or self configured one provided by the InteractionHighlightConfiguration. Using the VisualNodeOverlayIndicationHandler offers much more flexibility for indicating a overlay-edge-creation.

Surely both the default or self configured indicator of the InteractionHighlightConfiguration and a VisualNodeOverlayIndicationHandler can be used in combination.

Edge Split

Edge Cascade

Cascade Delete Edges

Detach On Move

© 2004, 2005 Tensegrity Software GmbH

Prev Up Next
GraphObject IDs Home | ToC Modelling Handlers