The basis of the VkGraph class is the SgGraph widget, which manages and displays the graph. This section provides an overview of the SgGraph widget. For in-depth information on interacting with the graph widget, consult the SgGraph(3x) reference page.

A primary responsibility of the SgGraph widget is to clearly and systematically lay out the nodes. The graph layout algorithm is a simple and efficient tree layout algorithm designed to handle forests of nodes. It lays out nodes as a multi-rooted tree.

By default, the graph widget created by the VkGraph class operates in a read-only mode in which the graph widget is used primarily as a layout manager for arranging the node widgets. By modifying certain SgGraph resources, you can also interactively edit the displayed graph, creating and moving arcs and nodes. However, to support most of the functionality of the edit mode, you must provide callback functions and other information to the graph widget so that you can interpret the edit operations and use them in your program.

Refer to the SgGraph(3x) reference page for details on the resources and callbacks used for edit mode. Also refer to the example in /usr/share/src/ViewKit/ComponentDemos/graph.

The process of building and displaying a graph using the VkGraph component consists of the following steps:

Example 12-1 illustrates this process by showing the code used to create the graph shown in Figure 12-2.

#include <Vk/VkApp.h>
#include <Vk/VkWindow.h>
#include <Vk/VkNode.h>
#include <Vk/VkGraph.h>
#include <Vk/VkMenu.h>
class GraphWindow: public VkWindow {
 
  public:
    GraphWindow( const char *);
    ~GraphWindow();
    virtual const char* className();
  protected:
    VkGraph *graph;
    VkNode *p_node, *c1_node, *c2_node, *gc1_node, *gc2_node;
 
  private:
    static void quitCallback (Widget, XtPointer, XtPointer);
    static VkMenuDesc appMenuPane[];
};
 
 
VkMenuDesc GraphWindow::appMenuPane[] = {
  { ACTION,   "Quit",      &GraphWindow::quitCallback },
  { END }
};
 
GraphWindow::GraphWindow(const char *name) : VkWindow( name )
{
    // Create nodes
 
    p_node   = new VkNode("parentNode", "Parent");
    c1_node  = new VkNode("childNode1", "Child 1");
    c2_node  = new VkNode("childNode2", "Child 2");
    gc1_node = new VkNode("grandChildNode1", "Grandchild 1");
    gc2_node = new VkNode("grandChildNode2", "Grandchild 2");
    
    // Create graph
 
    graph   = new VkGraph( "graph", mainWindowWidget() );
 
    // Add nodes to graph
 
    graph->add(p_node, c1_node);     // p_node is parent to c1_node
    graph->add(p_node, c2_node);     // p_node is parent to c2_node
    graph->add(c1_node, gc1_node);   // c1_node is parent to gc1_node
    graph->add(c1_node, gc2_node);   // c1_node is parent to gc2_node
    graph->displayAll();             // Display all nodes in graph
    graph->doLayout();               // Layout the graph
    
    addView(graph);                  // Set graph to be window's view
    addMenuPane("Application", appMenuPane);         // Create menu bar
}
GraphWindow::~GraphWindow()
{
    delete graph;
    delete p_node;
    delete c1_node;
    delete c2_node;
    delete gc1_node;
    delete gc2_node;
}
 
const char* GraphWindow::className()
{
    return "GraphWindow";
}
 
void GraphWindow::quitCallback ( Widget, XtPointer, XtPointer )
{
    theApplication->quitYourself();
}
 
void main(int argc, char **argv)
{
  VkApp       *myApp    = new VkApp("GraphViewer", &argc, argv);
  GraphWindow *graphWin = new GraphWindow("GraphViewer");
 
  graphWin->show();
  myApp->run();
}

This example creates a VkWindow subclass to contain the graph. The graph itself is created in the GraphWindow constructor:

In addition to displaying a graph, VkGraph automatically provides controls for interactively manipulating the graph. One set of controls is contained in the control panel, shown in Figure 12-3, which appears along the bottom of the graph.

Figure 12-3. Graph Command Panel

The control panel contains buttons and a menu that allow the user to interactively control various characteristics of the graph's display. Using the control panel, the user can

Additionally, VkGraph automatically creates popup menus that contain commands that allow the user to hide and display nodes in the graph.

Zooming

VkGraph provides eight preset zoom settings that allow the user to shrink or enlarge the size of the graph. The user can directly set the zoom value using the Zoom menu shown in Figure 12-4.

Figure 12-4. Interactively Changing the Graph Zoom Value

Clicking the Zoom Out button (the down-arrow button immediately to the right of the Zoom menu) changes the zoom setting to the next lower value, and clicking the Zoom In button (the up-arrow button to the right of the Zoom Out button) changes the zoom setting to the next higher value.

Edit Mode Operations

There are additional operations that a user can perform if you set the graph to edit mode, as described in “Graph Widget”. By default, the graph widget created by the VkGraph class operates in read-only mode. You can set the graph widget to edit mode in a VkGraph subclass.

---

Note: To support much of the functionality of the edit mode, you must provide callback functions and other information to the graph widget so that you can interpret the edit operations and use them in your program. Refer to the SgGraph(3x) reference page for details on the resources and callbacks used for edit mode.

---

You must select one or more nodes before you can perform an operation on it. You can select nodes only if the graph is in edit mode. By default, the graph is created in display-only mode.

To perform most operations in edit mode, the user must first select one or more nodes. The user can select a single node by clicking it with the left mouse button. The graph highlights the selected node. The user can select additional nodes by holding down the Control key and clicking additional nodes with the left mouse button. The user can also select multiple nodes with a bounding box by moving the pointer to a spot on the graph where there is no node or arc, then holding down the left mouse button and dragging out a bounding box. When the button is released, all nodes fully enclosed by the box are selected. (Partially enclosed nodes aren't selected.)

The user can deselect nodes by clicking the left mouse button on a blank section of the graph.

The user can move a node by clicking that node with the middle mouse button and then dragging the node anywhere in the graph window. The user can move several nodes at once by first selecting the nodes and then clicking any one of the nodes with the middle mouse button and dragging the nodes to their new position.

The popup Selected Nodes menu allows the user to perform an operation on all selected nodes. To open the Selected Nodes menu, the user moves the pointer to any blank area of the graph, and then presses the right mouse button. The menu has three commands:

“Hide Selected Nodes”		Hides all selected nodes and their connecting arcs.
“Collapse Selected Nodes”		Hides all descendent nodes and connecting arcs of the selected nodes.
“Expand Selected Nodes”		Displays the immediate children of all the selected nodes.

This section describes the basic functionality provided by the VkNode class. Most VkNode functions other than the constructor are for use by VkGraph; however, you might occasionally find some of the utility and access functions useful.

Node Constructor and Destructor

The VkNode constructor has two forms:

VkNode(const char *name, const char *label = NULL) VkNode(const char *name, VkNode *parent, const char *label = NULL)

name is the node's component name. You should provide unique names for all nodes. label is the label that the node displays when visible in a graph. If you do not provide a label, the node uses the component name as the label. You can optionally provide a pointer to an existing node, which the constructor uses as a parent node for the new node.

As an example, the following line of code creates the node state19 with the internal name “state19” and the label “Indiana”:

VkNode state19 = new VkNode("state19", "Indiana");

The following line of code creates a new node, city41, as a child of state19. The name of the new node is “city41” and the label is “Terre Haute”:

VkNode city41 = new VkNode("city41", state19, "Terre Haute");

---

Note: The VkNode constructor merely initializes internal variables; it does not create any widgets. The VkGraph object of which a VkNode object is a member can create and destroy node widgets as needed. The VkGraph object calls a protected member function, VkNode::build(), whenever it needs to create a node's widget. “Creating Node Subclasses” discusses build() in more detail.

---

The VkNode destructor destroys the node's widget if it exists and deallocates all other internal storage.

void sortChildren()

static void setSortFunction(VkNodeSortFunction func)

typedef int (*VkNodeSortFunction)(VkNode *, VkNode *)

static int sortNodesByLabel(VkNode *one, VkNode *two)
{
    int value = strcmp(one->label(), two->label());
    return value;
}     

char *name() const

virtual char *label()

int nParents() const
int nChildren() const

VkNode *parent(int index) const
VkNode *child(int index) const

VkNode *findParent(char *name)
VkNode *findChild(char *name)

You can create subclasses of VkNode to extend its features in a variety of ways to maintain additional data or to change the way the node displays itself in a graph. Some possibilities include the following:

You have a great deal of flexibility in deciding how to extend the VkNode class. The important restriction that you must keep in mind is that the VkGraph object of which a VkNode object is a member can create and destroy node widgets as needed. Therefore, in your subclass function definitions you cannot assume that your node's widget exists.

The VkGraph object calls a protected member function, VkNode::build(), whenever it needs to create a node's widget. If you want to use the additional features of the default SgIconGadget widget or if you want to use a different widget in you subclass, you must override build():

virtual void build(Widget parent)

If you simply want to use the additional features of the default SgIconGadget widget, you can call VkNode::build() from within your subclass's build() function to create the SgIconGadget widget and set the widget's label. Then, you can perform any additional operations you want. (Consult the SgIconGadget(3x) reference page for more information on using this widget.) For example:

void MyNode::build(Widget parent)
{
    VkNode::build(parent);
    // Additional setup...
}

If you want to use your own widget or widget hierarchy, create the widget(s) using parent as the parent widget, and assign the widget or root of a widget hierarchy to the _baseWidget data member. After creating the _baseWidget, call installDestroyHandler(), as described in “Handling Component Widget Destruction”.

From within a VkNode subclass you can also access the _label data member:

char *_label

_label contains the node's label string as set by the VkNode constructor.

The VkGraph constructor is simple with few arguments. You must provide a name and the parent widget for the graph:

VkGraph(char *name, Widget parent)

The VkGraph destructor destroys the graph. It does not destroy any VkNode objects that are part of the graph.

After you create nodes, you must add them to the graph object you created. Also, if you didn't specify the parent-child relationship for the nodes when you created them, you should supply the remaining connectivity information when adding the nodes to the graph. (See “ViewKit Node Class” for information on creating nodes.)

The VkGraph::add() function adds nodes to a graph object:

virtual int add(VkNode *node)
 
virtual void add(VkNode *parent, VkNode *child,
                 char *attribute = NULL)

If you supply only one node pointer as an argument, add() simply adds the node to the graph. If you have already added the node to the graph, add() does nothing.

If you supply two node pointers as arguments, add() adds both nodes to the graph and establishes the first node as the parent of the second node. If you have already added either node to the graph, add() does not add the node again, but it does establish the parent-child relationship between the nodes.

---

Note: The second form of add() establishes the parent-child relationship between nodes even if one already exists. Thus, it is possible to have more than one connection between nodes. By default, the graph displays only a single arc between connected nodes, even if you define multiple connections between the nodes. However, as described in “Displaying Duplicate Arcs”, by clicking the graph's Multiple Arcs button the user can force the graph to display an arc for each connection you defined. To turn off the multiple-arc display, the user can click the Multiple Arcs button again.

---

When specifying a parent-child connection using add(), you can specify an attribute for that connection. An attribute is an arbitrary name that you can use to control the appearance of the arc widget that connects the two nodes. For example, assume that you add two nodes to a graph as follows:

graph->add(parent, child, "primary");
graph->add(parent, child, "secondary");

The resulting graph displays two connecting arcs between the two nodes. You can now specify X resources to control various aspects of the arc. For example:

*primary*foreground:      red
*primary*arcDirection:    bidirected
*secondary*foreground:    blue
*secondary*arcDirection:  undirected
*secondary*style:         LineOnOffDash

You can use this method to set many of the resources supported by the SgArc widget. The resources you can specify are: XmNforeground, XmNtoSide, XmNfromSide, XmNfromPosition, XmNtoPosition, XmNarcDirection, XmNfontList, XmNarcWidth, XmNstyle, and XmNdashes. See the SgArc(3x) reference page for details on these resources.

The following code fragment creates a graph, creates two nodes, establishes a parent-child relationship between the nodes, and adds the nodes to the graph:

graph   = new VkGraph("graph", parent);
p_node  = new VkNode("parentNode", "Parent");
c1_node = new VkNode("childNode1", p_node, "Child 1");
graph->add(p_node);
graph->add(c1_node);

Note that in this example, the connection between the two nodes is established when you create c1_node. Therefore, you must add the nodes to the graph using separate calls to add(). Suppose that, instead of the two separate calls, you execute this:

graph->add(p_node, c1_node);

Then you not only add the two nodes to the graph, but you establish a second connection between the nodes.

You can accomplish the same result as above by creating the nodes without providing the parent-child relationship, and then specifying the connection when you add the nodes to the graph. The following code fragment is functionally equivalent to that shown above:

graph   = new VkGraph("graph", parent);
p_node  = new VkNode("parentNode", "Parent");
c1_node = new VkNode("childNode1", "Child 1");
graph->add(p_node, c1_node);

You can remove nodes from a graph using VkGraph::remove():

virtual void remove(VkNode *node, Boolean deleteNode = FALSE)

By default, remove() removes the node from the graph but does not delete it. If you set the deleteNode argument to TRUE, remove() deletes the node when it removes it.

Once you have added all nodes to a graph and specified their connectivity, you must indicate which nodes the graph should display. VkGraph provides many functions that allow you to display or hide all of the graph, individual nodes, and portions of node subtrees.

After displaying nodes, you should call one of the graph layout member functions as described in “Laying Out the Graph”. Otherwise, the nodes might not display in desired locations.

The basic display functions are VkGraph::displayAll() and VkGraph::clearAll():

virtual void displayAll()
void clearAll()

displayAll() displays all nodes and clearAll() hides all nodes. Typically, after creating your graph, you execute displayAll() to display all of the nodes. For example:

graph->displayAll();

Sometimes you might want to display only portions of your graph. VkGraph provides functions to operate on either single nodes or subtrees of nodes.

The VkGraph::display() function displays a single node:

virtual void display(VkNode *child)
virtual VkNode *display(char *name)

You can provide display() with either a pointer to the node or the component name of the node. If you provide the node's name, this function returns a pointer to the node.

VkGraph::undisplay() hides a single node:

virtual void undisplay(VkNode *node)
virtual void hideNode(VkNode *node)

VkGraph::hideNode() is equivalent to undisplay().

VkGraph also provides a large number of functions that display or hide portions of the graph:

You can also create your own functions for determining whether or not nodes are displayed and then use the VkGraph::displayIf() function to apply those functions:

virtual void displayIf(VkGraphFilterProc)

The type definition of VkGraphFilterProc is as follows:

typedef Boolean (*VkGraphFilterProc) (VkNode );

The function you provide must be a static function that accepts a node as an arguments and returns TRUE if the node should be displayed.

---

Note: displayIf() does not hide (that is, call undisplay()) if the filter function returns FALSE for a node. Therefore, if you want to display only those nodes for which the filter function returns TRUE, you must first call clearAll().

---

For example, the following function displays only those nodes whose names begin with the string “state”:

static Boolean displayState(VkNode *node)
{
    if ( strcmp("state", node->name(), 5)
        return TRUE;
    else
        return FALSE;
}       

The final step in displaying a graph is to lay it out. Laying out the graph arranges the widgets in a logical manner and then manages the widgets.

To lay out the entire graph, call the VkGraph::doLayout() function, which applies the layout algorithm to the entire graph and then manages all widgets associated with the graph:

void doLayout()

If you modify the graph after displaying it, or if you allow the user to edit the graph interactively, the graph might become cluttered and you might want to lay out the graph again. To do so you can call doLayout() again to force the graph to reapply the layout algorithm to the graph to clean up the display. As an example, the Realign button provided on the graph command panel simply calls doLayout() whenever the user clicks the button.

If, after displaying the graph, you display any additional nodes (for example, using the VkGraph::display() function), you must force a layout of the graph to manage all the widgets you created. You can call doLayout() again to do so, but this applies the layout algorithm to the entire graph. Doing so could produce major changes in the layout of the entire graph, which could be disruptive and undesired if the user has previously moved nodes. Also, it could take considerable time if the graph is large. In this case, you can instead call the VkGraph::doSubtreeLayout() function which, given a root node, applies the layout algorithm to just a subtree of the graph:

void doSubtreeLayout(VkNode *node)

For example, the following code fragment illustrates displaying a graph, graph, and then displaying another node, newNode:

// At this point, all nodes are created, the connectivity is
// specified, and certain nodes selected to be displayed
 
// Lay out and display the graph
 
graph->doLayout();
// Mark newNode to be displayed
 
graph->display(newNode);
 
// Display newNode, re-laying out only the subtree
// under newNode
 
graph->doSubtreeLayout(newNode);

VkGraph::doSparseLayout() is a special-purpose build and layout function that displays the relationship between a node and its grandparent nodes even if the node's parents are not displayed:

void doSparseLayout()

doSparseLayout() performs a special build of the graph and whenever it finds a node with an undisplayed parent node, it checks to see whether there are any displayed grandparent nodes. If doSparseLayout() finds such grandparent nodes, it creates a dashed-line arc (instead of a solid-line arc) to connect the node and its grandparent nodes. After finishing the build process, doSparseLayout() performs a layout of the entire graph and manages all widgets associated with the graph.

So far, this chapter has discussed creating tree graphs using the VkGraph class. However, VkGraph also supports butterfly graphs, which display only a central node and its immediate parent and child nodes. The central node of a butterfly graph is called the butterfly node.

VkGraph can construct a butterfly graph from any graph specification. All you need to do is call VkGraph::displayButterfly() to specify one node as the butterfly node; VkGraph automatically determines which nodes to display:

virtual void displayButterfly(VkNode *node)
virtual VkNode *displayButterfly(char *name)

Then call VkGraph::doLayout() to lay out the graph as you normally would. For example, assuming that you have already defined a graph specification for a graph called graph, the following code fragment would instruct the graph object to display a butterfly graph centered on the node centerNode:

graph->displayButterfly( centerNode );
graph->doLayout();

After displaying a butterfly graph, you can use displayButterfly() to specify a new butterfly node and display a different butterfly graph given the same graph specification. For example, the following code fragment illustrates setting a new butterfly node, newCenter, after displaying the butterfly graph in the example above:

graph->displayButterfly( newCenter );
graph->doLayout();

After displaying a butterfly graph, you can return to displaying a normal tree graph by setting the layout style to XmGRAPH using the VkGraph::setLayoutStyle() function:

virtual void setLayoutStyle(char type)

For example, the following code fragment illustrates displaying the entire graph specified by graph after displaying the butterfly graphs above:

graph->setLayoutStyle( XmGRAPH );
graph->displayAll();
graph->doLayout();

As discussed in “Graph Overview”, by clicking the Graph Overview button in the graph command panel, a user can display an overview of all a graph's visible nodes.

You can also display the overview window programmatically using VkGraph::showOverview():

void showOverview()

Call VkGraph::hideOverview() to programmatically hide the overview window:

void hideOverview()

You can obtain a pointer to the overview window's VkWindow object using VkGraph::overviewWindow():

VkWindow *overviewWindow()

VkGraph provides the following utility functions:

VkGraph provides the following access functions for obtaining values associated with the graph:

Occasionally, after displaying one graph, you might want to display an entirely different graph. The simplest method of accomplishing this is to create another VkGraph object for the new graph.

However, creating a new graph object entails the overhead of creating many new widgets and data structures. Sometimes it is simpler, faster, and more appropriate to re-use the existing graph object. For example, consider a window in which you are displaying a graph of C++ class hierarchies associated with a program. The window might contain controls that allow the user to select other programs to examine. If the user selects a new program to examine, the most convenient thing to do would be to keep the existing graph object but “clear it” of all existing information.

The VkGraph::tearDownGraph() function provides this ability:

virtual void tearDownGraph()

It tears down the graph by destroying all arc and node widgets and deleting all VkNode objects associated with the graph. This function is equivalent to deleting all VkNode objects associated with the graph, deleting the graph object, and creating a new graph object with the same name, but entails less overhead processing than if you were to explicitly perform these actions separately.

The VkGraph class declares two ViewKit member function callbacks.

VkGraph activates the VkGraph::arcCreatedCallback whenever the graph creates a SgArc widget to connect two nodes. The arcCreatedCallback callback includes as call data the newly created SgArc widget. See the SgArc(3x) reference pages for information on the SgArc widget.

VkGraph activates the VkGraph::arcDestroyedCallback whenever the graph destroys all arc widgets as a result of a call to VkGraph::clearAll() (see “Indicating Which Nodes to Display”). VkGraph activates the arcDestroyedCallback callback once for every arc destroyed, including as call data the SgArc widget destroyed. See the SgArc(3x) reference pages for information on the SgArc widget.

VkGraph sets several X resources that specify the labels of its popup menus. You can override these values in an app-defaults file if you want to provide your own labels. The resources and their default values are as follows:

*graph*popupMenu*hideNode*labelString:               Hide Node
*graph*popupMenu*collapseSubgraph*labelString:       Collapse Subgraph
*graph*popupMenu*expandOneLevel*labelString:         Show Immediate Children
*graph*popupMenu*expandSubgraph*labelString:         Expand Subgraph
*graph*popupMenu*hideParents.labelString:            Hide Parents
*graph*popupMenu*expandParents.labelString:          Show Parents
*graph*popupMenu*selectedNodes.labelString:          Selected Nodes
*graph*popupMenu*hideSelectedNodes.labelString:      Hide
*graph*popupMenu*collapseSelectedNodes.labelString:  Collapse
*graph*popupMenu*expandSelectedNodes.labelString:    Expand

VkGraph provides much of the functionality that you should require for displaying and manipulating graphs. In most other cases, you can obtain a pointer to the SgGraph widget using the graphWidget() access function and operate directly on the widget.

However, sometimes you might want to perform additional processing when certain actions occur. In a case like this, you can create a subclass of VkGraph. VkGraph provides a number of virtual “hook” functions that you can override and implement additional functionality: