NOTE: The latest (not fully-tested) jKSImapper source code can be downloaded here. Last updated sometime in 1999.

Table of Contents

What is a Concept Map?
Concept maps are specialized kind of diagrams composed of nodes and arcs. An example of a concept map is shown on Figure 1 below. This figure shows a simple but expressive graph consisting of two nodes and one arc, where the node labeled as "Earth" has a link directed toward the node labeled "Planet". This diagram expresses the notion that "Earth is a Planet". The directed arc in this graph is known as an "IS A" arc due to the relationship represented between the concepts "Earth" and "Planet".

 

Figure 1. Diagram expressing the notion "Earth is a Planet".

What is jKSImapper?
jKSImapper is a computer program that supports the drawing of concept maps by allowing the manipulation of node and arc objects. Figure 2 shows an instance of a jKSImapper program containing a concept map constructed after Sowa's linguistic formalism called Conceptual Graphs. This figure shows rectangular shaped nodes (such as the ones labeled as "TEACHER:x", "WRITE" and "BOOK"),  ellipse shaped nodes ("AGNT" and "OBJ"), several directed and one non-directed arc, and a special kind of "hollow" node to encompass other nodes and arcs. This special type of node is called Context box (which is labeled "NOT" in this example).

Figure 2. jKSImapper with a formal diagram expressing the sentence "No student reads the book written by the teacher".

Figure 3. jKSImapper core architecture .

• Drawable (Interface): Defines methods to paint a graph.
• Selectable (Interface):  Defines methods to select a graph.
• Shadowable (Interface): Defines methods to manipulate the shadowing of a graph.
• Positionable (Interface): Defines methods to modify the (x,y) position  of a graph.
• Resizable (Interface): Defines methods to modify the dimensions (i.e., width and height) of a graph.
• Containable (Interface): Defines methods to query if a graph contains a point or if it is fully contained by an area.
• Attachable (Interface): Defines methods to get a graph's anchor point based on an oncoming position from where the graph is to be anchored by an arc.
• MouseHitable (Interface): Defines methods to query information from a graph based on the position of the mouse pointer.
• Parseable (Interface): Defines methods to read/write a graph's data in linear form to a stream.

Figure 4. jKSImapper's Graphs class hierarchy.

• BehaviouralObservable (Abstract Class): Allows a behavioural graph to be "observed" by other graphs. This is usually the case of nodes, which can have arcs attached to them. In such cases, nodes (i.e., observables) notify arcs (i.e., observers) of any changes on the node that may affect them (e.g., arcs attached to a node adjust their rendering to a new position when the node notifies them after a size or location change).
• MouseEventHandler (Interface): Defines methods to handle mouse events such as movement, dragging, and clicking, among others.
• PopupProvider (Interface): Defines methods for providing a default popup menu, if one is not externally provided.
• IDHolder (Interface): Defines methods for graphs with an ID. Graphs featuring an ID are eligible to receive commands that execute an action.
• TargetQuerable (Interface): Defines methods to query a graph for its ID.

• Node (Class): This class defines the behaviour of a node. Node objects support visual instances from sub-classes of the abstract class VisualShape.
• ContextBox (Class): This class defines the behaviour of context boxes. Since context boxes display similar responses as nodes, they are implemented as a node specialization.
• Link (Class): This class defines the behaviour of arcs, which are composed of handles (or "elbows"). Although the Link class  is defined as a VisualParent descendant it does not own (at least not directly) any displayable element. Instead, its visual representation depends on a Handle Composite structure it references (Note: Handles and Links are covered in detail under the "Understanding Links and Handles" section below). Besides from the behaviour it inherits from BehaviouralGraph, Link also implements methods defined in the HandleInterface interface, which specifies methods common to Handle and Link classes.

• Visitable (Interface): Defines methods to allow Visitor objects to traverse a tree structure of Handle objects.
• BehaviouralObserver (Interface): Defines methods to add and remove a dependency with a BehaviouralObservable object.
• HandleInterface (Interface): Defines methods common to the Link and Handle classes.
• IntermediateHandle (Interface): Define methods to manipulate a line that is "bent" to create a new "elbow" (i.e., handle).
• BranchHandle (Interface): Define methods to manipulate a new line branching from a handle.

• VisualHandle (Class): This class implements the mechanisms required to display a link handle and its corresponding line. This class implements the IntermediateHandle and BranchHandle interface, which support the creation of a new handle and a new line, respectively. Instances of this class have objects of type Handle as their parents.
• VisualShape (Abstract class): This abstract class implements methods common to visual shape elements. This class have four descendant classes: VisualRectangle, VisualRoundedRectangle, VisualEllipse and VisualContextBox. From these classes, the first three are visual elements for Node objects and the latter is the visual element for ContextBox instances.

Figure 5. Example of a hierarchy of Handles based on their graphical rendering.

Figure 6. Creating a Link object on jKSImapper.

• Adding a non-terminal handle: Addition of non-terminal handles can be done by direct manipulation (i.e., by clicking and dragging a point from a line segment) or by using a popup menu option. With the latter option, a new handle is added to a line without breaking it. These actions are exemplified in Figure 7 below. This figure also shows the resulting handle hierarchy as it is modified to accommodate the new handle.

 

Figure 7. Example of the creation of a non-terminal handle using direct manipulation (top) and a popup menu option (bottom).

 
• Adding a terminal handle: Addition of terminal handles (i.e., branching lines)  is done using a popup menu option, as illustrated in Figure 8. This figure also shows the resulting handle hierarchy as it adapts to accommodate the new handle.



Figure 8. Example of the creation of a terminal handle.

 
• Deleting: Handle deletion is performed using a popup menu selection invoked over the handle to delete, as shown in Figure 9. This figure also shows the hierarchy for the exemplified link before and after the deletion occurs. The following conditions have to be fulfilled to allow the deletion of a handle: a) the handle must have 2 siblings at the most (i.e., a parent and one children), and b) the link to which the targeted handle belongs to must have 3 or more handles in total before deletion (since a link cannot be made of a single handle).



Figure 9. Example of a handle deletion using a popup menu..

 
• Moving: Changes on handle location are achieved by direct manipulation. This action is done by mouse clicking and dragging a handle to a new location. This action is shown in Figure 10.



Figure 10. Example of moving a handle to a new location using direct manipulation.

 

jKSImapper provides 2 algorithms to automatically and correctly arrange a link's handles: one algorithm arranges handles to a "balanced visual state" when shadowing, and a second one balances handles after an action is executed. The need for maintaining a link "balanced" is not obvious from the examples presented up to now, therefore Figure 11 shows an example of the dynamics of "balancing" a link. This figure features four different snap-shots of the shadowing mechanism when a handle is moved. This handle has as its only sibling a handle attached to a node. As it can be noticed, the shadow of the "anchored" handle (the one attached to the node) changes its location to a different point on the perimeter of the node according to whether that point is the closest point to the external handle been moved.

Figure 11. Example of the dynamics of shadowing when moving a handle whose sibling handle is attached to a node.

Figure 12. Example of the dynamics of shadowing when moving a handle part of a link containing a free handle (center handle).

The fundamentals of these algorithms are based on the Visitor design pattern (Gamma et. al, 1994), on which an object is allowed to traverse the hierarchy of handles to obtain information about them. The gathered information is organized as a repository of Cell objects, each storing a dynamic reference and other information related to a handle. Cell's sub-classes LocationCell and ShadowLocationCell are used by the ResetHandlesLocationVisitor and ResetHandlesShadowLocationVisitor classes, respectively. The former class balances a link after it has been modified, while the latter balances a link when shadowing is requested.

The Cell class
Figure 13 lists the Cell abstract class, which is sub-classed by the LocationCell and ShadowLocationCell classes. Instances of this class are initialized by receiving a Handle object from where a reference to it and its sibling handles is obtained. This class declares two abstract methods: locationHasChanged (to learn if the original position of a handle has been modified) and updateLocation (which copies the location stored in this class to the handle referenced).

This class implements four private methods, which are described below.

The private method setAttachedLocation obtains a new attachment point for an attached handle based on an external reference point. This point is calculated using the calculateReference method. This method receives a handle reference and calculates a central point based on all fixed points surrounding the targeted handle. These fixed points are obtained by invoking the getAllStablePoints method. This method traverses all the handle's siblings until all branches return fixed points of reference. This same process (invoking the calculateReference and getAllStablePoints methods) is used by the setFreeLocation method to calculate the location of  a free handle.
 

This class also implements the same four private methods (setAttachedLocation, setFreeLocation, calculateReference and getAllStablePoints) as the ResetHandlesLocationVisitor class did, but they are applied to shadowing instead of current locations. From these methods, getAllStablePoints is the one that differs the most between these two classes regarding the mechanisms of implementation, since in this class this method checks for a branching new line (existing if a new terminal handle is been created) and for an intermediate handle (if a new non-terminal handle is been created).