The Graph Widget is an alternative to Forms
for creating and populating instances of classes in Protégé. It is also particularly useful for visualizing
networks of instances and relationships between instances. This tutorial assumes a basic working knowledge of
Protégé. For more information about how to use Protégé, see our
Getting Started with Protege
Known Feature Requests
Step 1: Download GraphWidgetExample project
For those of you who are familiar with Protégé, you'll recognize this project as a slightly modified version of the
Newspaper example. We'll step through the creation of an organization chart for a group of Newspaper employees.
Step 2: Configure Organization class
- Open Protégé and load the GraphWidgetExample project from step 1.
- Choose the
Organization class in the Class Hierarchy pane on the Classes tab.
- Create a new slot called
organization_chart and attach it to the
Organization class. The slot
should be of type Instance, cardinality multiple, and have the
Employee class as the allowed class type. We
Employee as the allowed class type because an organization chart typically displays relationships between
employees working within an organization.
Screenshot of Protégé after completion of step 2:
Step 3: Configure
organization_chart slot to use Graph Widget
- Navigate to the Forms tab and choose
Organization from the Forms list.
- Select the
organization_chart slot and choose GraphWidget from the Selected Widget Type
Screenshot of Protégé after completion of step 3:
Step 4: Configure node appearance
Nodes are the objects that appear in the palette on the left-hand side of the Graph Widget. Each node represents a concrete allowed class
slot (or whatever slot is configured to use the Graph Widget). By default, the Graph Widget
assigns all nodes the same shape and color. To change the node shape and color or the text properties of the node's labels:
- Double-click on the
organization_chart slot to bring up the Graph Widget configuration dialog.
- Select the Nodes tab.
Screenshot of the Graph Widget configuration dialog:
The table in the top portion of the Nodes tab contains a list of all the concrete allowed classes for the
Note that the
class does not appear here because it's an abstract class. Rather, all the the concrete subclasses
are displayed. Try selecting various nodes from the table and changing their shape and color using the Shape
and Shape Color combo boxes. You can also change the text properties of the node's labels using the Text Color combo box and the Bold
and Italic check boxes.
You can ignore the Optional Connector Slot area as we will deal with this in a later step. To follow is a example of what the configuration
dialog might look like after configuring node appearance:
Click OK to save your changes. (Note that it is not a necessary step in this tutorial to select the same shapes and colors displayed in
the screenshot above)
Step 5: Configure a simple connector
There are two types of connectors in the Graph Widget. First we will look at the simple connector type, which is a connector
between two nodes that doesn't have an underlying instance. The allowed class type for the
assume that we are interested in focusing on the
and seeing a graphical representation of the relationship between
editors and other employees in the newspaper organization. There are two steps to complete for configuring a simple connector:
Step 6: Populate an instance of the Graph Widget using nodes and simple connectors
- Choose the
Editor class in the Class Heirarchy pane on the Classes tab and create and attach a slot called
responsible_for. The slot should be of type Instance, cardinality multiple, and have the
class as the allowed class type.
Screenshot of Protégé after completion of step 5a:
- On the Forms tab, bring up the widget configuration dialog again and select the
Editor class on the Nodes
responsible_for from the Connector Slot combo box. By making this selection, we are indicating to
the Graph Widget that we want to be able to draw connectors between
Editor nodes and other nodes of type
In other words, for each allowed class displayed in the table on the upper portion of the Nodes tab, the Connector Slot combo box
will display a list of type Instance, cardinality multiple slots for that class. You can choose one of these slots from the combo box to
indicate what other class types you can draw connectors to. Click OK to save your changes.
Screenshot of widget configuration dialog after completion of step 5b:
In this step, we'll look at an instance of the
class and learn how to populate the Graph Widget with nodes and
Navigate to the Instances tab and choose the
class in the Class Hierarchy pane.
Select San Jose Mercury News in the Instance Browser. To create an instance of the
class, select the
node in the palette and drag and drop it onto
the view. Repeat this step again so that you have two nodes in the Graph Widget view. To draw a simple connector between the two
mouse over one of the nodes in an area other than the node label. When the cursor changes from an arrow to a hand, single-click and drag your mouse over to the other node.
When you release your mouse over the other node, a connector appears between the two nodes, showing the
- Click on a node label and drag to reposition nodes in the view.
- When a node is selected, grab any of the eight resize handles to resize the node.
- Since the Editor class has a browser key (the
name slot), you can double-click on the node labels and use in-place
text editing to change the node's text.
- Double-click on nodes (anywhere except the node label) to bring up Instance Forms.
- Use the ´C´ button on the Graph Widget toolbar to create nodes in the view as an alternative to dragging and dropping
from the palette.
- Select multiple nodes and click the ´V´ button to bring up multiple Instance Forms.
- Right click on connectors to insert extra points via the Insert Point right-mouse menu item.
- Right click on connectors to remove segments via the Remove Segment right-mouse menu item.
Screenshot of San Jose Mercury News Instance Form after completion of step 6:
Continue adding nodes of various types to the Graph Widget. Notice also that the widget will only allow you to draw valid simple connectors
between nodes. Since we only specified one connector slot for the
class, we can only draw simple connectors from
other nodes, but not the other way around. For example, try drawing a simple connector from a
node to another node. The Graph Widget won't allow such a connection.
Additional screenshot of SJ Mercury News Instance Form after adding more nodes and connectors:
Step 7: Configure a reified relation
- Use the "Perform Automatic Layout" buttons to automatically layout nodes and connectors in the
- Use the "Save Graph as Image" button to save the contents of the Graph Widget to an image file.
In this step we will work with the other connector type provided by the Graph Widget called a reified relation. A reified relation is a connector
between nodes that has an underlying instance. You use this type of connector when you need to store additional information about the relationship
between two nodes. There are three steps to configure a reified relation:
Step 8: Populate an instance of the Graph Widget using nodes and reified relations
- Subclass the :DIRECTED-BINARY-RELATION system class.
- Choose the :DIRECTED-BINARY-RELATION system class in the Class Hierarchy pane on the Classes tab.
- Create a subclass called
Manager Supervision Relation.
- Change the allowed class type of the :FROM slot to
- Change the allowed class type of the :TO slot to
What we have just defined is a class that represents a reified relation between
Employee nodes. Note that you can add additional slots to this class to keep track of other
information about the relationship. The screenshot below has examples of what sort of "other information"
you might want to add. Note that it's not a necessary step in this tutorial to add additonal
slots to the
Manager Supervision Relation class.
Screenshot of Protégé after completion of step 7a:
- Create a slot to hold reified relations.
If you want to use reified relations for a particular class, you need to add a slot to the class that designates
what the valid relations are for that class. For our example, add a slot to the
Organization class called
employee_relationships. The slot should be of type Instance, cardinality multiple, and have the
Manager Supervision Relation class as the allowed class type.
Screenshot of Protégé after completion of step 7b:
- Tell the Graph Widget which of the slots attached to your class holds reified relations.
We need to tell the Graph Widget which slot attached to the
Organization class has been created to
hold reified relations. This is done in the widget configuration dialog:
- Return to the Forms tab and bring up the widget configuration dialog.
- Click on the Reified Relations tab.
employee_relationships from the Relation Slots combo box.
Screenshot of widget configuration dialog after completion of step 7c:
- Use the Line Color, Line Type, and Arrowhead Type combo boxes to change the appearance of the
reified relation connectors.
- Uncheck the Show Browser Text check box if you don't want your reified relation connectors to have
labels on them.
- Click OK to save your changes.
In this step, we'll look at a new instance of the
class and learn how to populate the Graph Widget with nodes
and reified relations.
class in the Class Hierarchy pane on the Instances tab. Create a new instance of the
San Francisco Examiner
. Using the Graph Widget, create two instances
class by dragging and dropping the
node from the palette onto the view. To draw
a reified relation between the two nodes, mouse over one of the nodes in an area other than the node label. When the cursor changes from an arrow to a hand,
single-click and drag your mouse over to the other node. When you release your mouse, a reified relation appears between the two nodes, showing a managerial
Screenshot of Protégé after completion of step 8:
- Double click on the reified relation connector to bring up the Instance Form for the
Manager Supervision Relation class.
- Designate a display slot for the
Manager Supervision Relation class to enable in-place editing of the
reified relation connector's label. (One possibility would be to attach the
- On the Forms tab, set the Selected Widget Type for the
employee_relationships slot to <none> to expand
the amount of display for the Graph Widget.
Continue adding nodes and experimenting with reified relations. To follow is a screenshot of the San Francisco Examiner Instance Form
after adding more nodes, reified relations, a simple connector, and completing the tips specified above:
Congratulations! You have now completed the Graph Widget tutorial. If you have further questions, please post them
to the protege-discussion
Converting from the Diagram Widget to the Graph Widget
The Graph Widget is the new and improved version of the Diagram Widget. The Diagram Widget existed in earlier versions of
Protégé (versions 1.7 and earlier). If you have an old Protégé project with diagram instances, you may want to
read the following notes (courtesy of Samson Tu
) on how to convert existing instances
of the Diagram Widget to the Graph Widget.
- You've installed Protégé version 1.8, build 1032 or later.
- You're interested in saving existing diagrams.
- You're using a file system back-end.
You have a project that includes the diagram ontology, that has a number of diagram instances, and you do not need to use the
existing location information of nodes and connectors.
- Make the
:DIRECTED-BINARY-RELATION class the parent class of your classes that inherit from the diagram
Connector class. Your existing subclasses of the
Connector class will then inherit
:TO slots from the
- In your existing subclasses of the Network class, add a multi-valued slot (you can choose your own name), whose allowed
classes include the allowed classes of the existing
connectors slot. This slot will be used to hold arc
information in the new Graph Widget.
- Save the project.
- Open the pins file in a text editor.
- Globally replace
:TO (assuming that you are not using the
second_object slots for
- Rename the slot
connectors in your instances that hold the diagram to the new slot you've defined in
- Save the pins file.
- Reload the project.
- Change the metaclasses of your old
Network classes to
(or any metaclass your want).
Network classes as parents of your classes.
- Delete instances of
- In the Forms tab, configure appropriate classes and slots in your project (that used to be shown as diagrams) to use the
new Graph Widget.
Do not "uninclude" the diagram project from your own project until you have converted all projects that include
the project where you specify the classes that make use of the diagram ontology.
You have a project (Project A) that includes another project (Project B) where diagrams are configured and you do not need to use
the existing location information of nodes and connectors.
- Convert Project B where you specify the classes that make use of the diagram ontology (see 1st scenario above).
- In a text editor, open the pins file for Project A. Globally replace
:TO (assuming that you are not using the
second_object slots for anything else).
- Rename the slot
connectors in your instances that hold the diagram to the new slot name you've defined.
- Save the pins file.
- You may have to reconfigure the classes of Project A in the Forms tab so that the Graph Widget gets used appropriately.
Alternatively, you can "import" the pont and pins files to rebuild the pprj file. When a new pprj file is built,
Protégé will copy the widget configuration information from included projects.
Known Feature Requests
- Graph Widget & the Mac: The Graph Widget only works on Mac OS X Panther v10.3 with an upgraded JDK (to version 1.4.2).
- There are some cases where the positioning information is lost for nodes and connectors the first time you click away from
a new instance of the graph widget. The workaround for this bug is to click away from new instances of the graph widget and come
back to them before beginning to populate them with new nodes and connectors.
Troubleshooting new nodes
- The ability to specify icons instead of shapes to represent nodes.
- An additional arrowhead type of circle
- The ability to designate arrowhead type for source arrowhead (can only specify destination arrowhead now)
- The ability to control the color of nodes based on the value of a specified slot
- Copy and paste for nodes within an instance of the graph widget
- Copy and paste for nodes between different instances of the graph widget
Information about the graphics library used by the Graph Widget
- If your node has an empty text label, there will still be a spot in the center of the node that you can mouse over where
the cursor will change from a hand to an arrow so you can single click on the node to select it. This is also the spot that
you single-click on and drag if you want to move the node around the view.
- If your node has an empty text label and you want to add some text back in, mouse-over the center of the node until the
cursor changes from a hand to an arrow. Double-click on this spot to initiate in-place text editing. You can also still
add text back in using the node's instance form. See above for instructions on launching instance forms.
- If the node's text label is so large that it obscures the node's shape, this can affect the ability to draw connectors
between nodes. The reason for this is that you must mouse over the node in an area other than the text label in order for
the cursor to change from an arrow to a hand (the signal that you can single-click and drag to start drawing a connector).
The workaround for this is to click on the node label to select the node, grab any of the resize handles and resize the node
until the node's bounding rectangle is large enough to accomodate the label and allow extra space for the node's shape. You
can either leave the node larger or after you are done drawing all connectors that initiate from the node, you can resize it
down to it's orginal size.
Rather than reinvent the wheel (write our own graphics library), we used a third party graphics library
from Northwoods Software. JGo has no runtime
fees but if you'd like to extend the GraphWidget and you need access to the JGo library, contact them to purchase a license.