VkGraph(3x)
VkGraph - A component that displays directed graphs
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
NAME VkGraph - A component that displays directed graphs INHERITS FROM VkComponent : VkCallbackObject HEADER FILE #include <Vk/VkGraph.h> PUBLIC PROTOCOL SUMMARY Constructor/Destructor VkGraph(char* name, Widget parent); virtual void ~VkGraph(void); Saving graphs void saveToFile(void); Access Functions Widget twinsButton(void); Widget relayButton(void); Widget reorientButton(void); Widget workArea(void); int numNodes(void); Widget graphWidget(void); Controlling position void makeNodeVisible(VkNode* node); Destroying a graph virtual void tearDownGraph(void); Overview control void showOverview(void); void hideOverview(void); VkWindow* overviewWindow(void); Node control virtual void hideNode(VkNode *node); virtual void hideParents(VkNode *node); virtual void expandNode(VkNode *node); virtual void expandSubgraph(VkNode *node); void clearAll(void); virtual void displayAll(void); void sortAll(void); virtual void display(VkNode* child); virtual VkNode* display(char* name); virtual void hideParentsAndChildren(VkNode* node); virtual void displayParentsAndChildren(VkNode* node); virtual VkNode* displayParentsAndChildren(char* name); virtual void hideParents(VkNode* node); virtual void displayWithParents(VkNode* node); virtual VkNode* displayWithParents(char* name); virtual void displayWithAllParents(VkNode* node); virtual VkNode* displayWithAllParents(char* name); virtual void displayWithChildren(VkNode* node); virtual VkNode* displayWithChildren(char* name); virtual void displayWithAllChildren(VkNode* node); virtual VkNode* displayWithAllChildren(char* name); virtual void displayButterfly(VkNode* node); virtual void displayIf(VkGraphFilterProc filterFunction); void hideAllChildren(VkNode* node); void hideWithAllChildren(VkNode* node); Adding and removing nodes virtual void add(VkNode* parent, int parentIndex, VkNode* child, int childIndex, char* attribute); virtual int add(VkNode* node, int givenIndex); virtual void add(VkNode* parent, VkNode* child, char* attribute); virtual void remove(VkNode *node, Boolean deleteNode = FALSE); virtual void undisplay(VkNode* node); Operating on Nodes virtual void forAllNodesDo(VkGraphNodeProc filterFunction); Layout Styles virtual VkNode* displayButterfly(char* name); virtual void setLayoutStyle(char type); Finding Nodes VkNode* find(char* name); Graph Layout void doLayout(void); void doSubtreeLayout(VkNode* node); void doSparseLayout(void); PROTECTED PROTOCOL SUMMARY Not for external use These functions are not intended for external use. They are only used by the VkGraph constructor. This means that, although they are virtual functions, by virtue of historical accident, they cannot be overridden. They are listed here only to avoid confusion to those who look at the headers. virtual void arcCreatedHook(VkNode*, Widget, VkNode*); virtual void arcDestroyedHook(Widget); virtual void popupMenu(VkNode*,XEvent*); virtual void setZoomOption(int); virtual void twinsVisibleHook(Boolean); Protected Data Members VkNode** _nodeList; int _numNodes; int _maxNodes; VkNode* _butterflyNode; VkPopupMenu* _desktopMenu; VkMenuItem* _expandSelected; VkMenuItem* _collapseSelected; VkMenuItem* _hideSelected; VkPopupMenu* _popupMenu; VkMenuItem* _expand; VkMenuItem* _hide; VkMenuItem* _expandParents; VkMenuItem* _hideParents; VkMenuItem* _collapse; VkMenuItem* _bigExpand; VkNode* _selectedNode; VkMenuItem* _popupTitleObj; CLASS DESCRIPTION The VkGraph class is a component that provides a high-level interface to the XmGraph widget. Graphs are constructed by specifying parent/child parents of objects, represented by the VkNode class. The VkGraph class constructs an abstract graph from these objects and allows applications or users to specify which portions of the graph to display at any one time. In this way, the VkGraph component supports graphs that can be larger than it is practical to display at one time. All nodes displayed by a VkGraph component must belong to the VkNode class or a derived class. The VkNode class maintains information about parent/child relationships and is able to create a widget on demand to be displayed in the VkGraph component. VkGraph manages which of the available nodes have visible widgets at any given time. FUNCTION DESCRIPTIONS hideNode() virtual void hideNode(VkNode *node); Hide (remove from the visible graph) the given node. hideParents() virtual void hideParents(VkNode *node); Hide all visible parents of the given node. expandNode() virtual void expandNode(VkNode *node); Show the specified node, as well as all immediate children. expandSubgraph() virtual void expandSubgraph(VkNode *node); Show the specified node, as well as all nodes below this node in the hierarchy. hideAllChildren() void hideAllChildren(VkNode* node); Hide all nodes below this node in the hierarchy. hideWithAllChildren() void hideWithAllChildren(VkNode* node); Hide this node and also all nodes below this node in the hierarchy. VkGraph() VkGraph(char *name, Widget parent); Initialize a VkGraph object. Creates the user interface widget used by this component. ~VkGraph() virtual void ~VkGraph(void); Cleanup before destroying a VkGraph object. The destructor does not destroy any VkNode objects added to the graph. saveToFile() void saveToFile(void); Save a postscript representation of the graph to a file. The user is prompted for a filename using a file browser dialog. twinsButton() Widget twinsButton(void); This access function retrieves the button widget used to control whether sibling arcs are shown. relayButton() Widget relayButton(void); This access function retrieves the button widget used to relay the graph. reorientButton() Widget reorientButton(void); This access function retrieves the button widget used to reorient the graph. workArea() Widget workArea(void); This access function retrieves an XmForm widget that is located in the bottom left corner of the VkGraph component. Applications can use this area to add additional controls. makeNodeVisible() void makeNodeVisible(VkNode *node); Scroll the graph if necessary to ensure that the given node is in the visible portion of the screen. tearDownGraph() virtual void tearDownGraph(void); Destroys an abstract graph and resets a VkGraph object to it's initial state. All VkNode objects added to the graph are deleted and removed from the graph. showOverview() void showOverview(void); Display a second window that shows an overview of all nodes in the graph. hideOverview() void hideOverview(void); Remove the overview window from the screen. overviewWindow() VkWindow* overviewWindow(void); Return a handle on the VkWindow object that contains the overview of the graph. twinsVisibleHook() virtual void twinsVisibleHook(Boolean vis); This virtual function can be used by derived classes that wish to perform some additional operations when the graph changes its display mode from showing all arcs between nodes, to showing only a single arc for all connections, and vice-versa. setZoomOption void setZoomOption(int index); Programmatically change the scaling factor of the graph. The argument is an index of the supported scale factors, as shown on the zoom option menu. clearAll() void clearAll(); Remove all nodes from the visible graph. The abstract graph is left undisturbed. displayAll() virtual void displayAll(void); Display every node in the abstract graph. Beware of huge graphs. sortAll() void sortAll(void); Sort the nodes of the graph. See the VkNode::sortFunction member function. add() int add(VkNode *node); virtual void add( VkNode *parent, VkNode *child, char *attribute = NULL); Add a node or a pair of nodes with a parent/child relationship to the abstract graph. If a node has no relationships, it is simply entered into an internal table maintained by the graph. If two nodes are given, a parent/child relationship between the two nodes is established. A parent/child relationship may also be given an attribute, which may be an arbitrary string. This attribute can be used to control the visual appearance of the arcs that connect the two nodes. See "Setting Attributes". undisplay() virtual void undisplay(VkNode *node); Remove the given node from the visible graph. setSize() void setSize(int size); Some applications know in advance how many nodes will be placed in an abstract graph. In this case, using setSize() to specify this size in advance can save time by allowing the VkGraph object to allocate sufficient memory at one time. The graph well expand the tables if necessary. resetSize() void resetSize(int newSize); Changes the size of the internal storage for nodes in the abstract graph. Normally, this function is for internal use. display() virtual void display(VkNode *node); virtual VkNode* display(char *name); Makes a node visible. The node must have been previously added to the abstract graph. If the node is specified by name, the first occurrence of that name is displayed. hideParentsAndChildren() virtual void hideParentsAndChildren(VkNode *node); Remove all parents and children of the specified node from the visible display. displayParentsAndChildren() virtual void displayParentsAndChildren(VkNode *node); virtual VkNode* displayParentsAndChildren(char *name); Display all parents and children of the specified node. displayParentsAndChildren() hideParents() virtual void hideParents(VkNode *node); Remove the immediate parents of the specified node. displayWithParents() virtual void displayWithParents(VkNode *node); virtual VkNode* displayWithParents(char *name); Show the specified node along with its immediate parents. displayWithAllParents() virtual void displayWithAllParents(VkNode *node); virtual VkNode* displayWithAllParents(char *name); Show the specified node along with all nodes above it in the hierarchy. displayWithChildren() virtual void displayWithChildren(VkNode *node); virtual VkNode* displayWithChildren(char *name); Show the specified node along with its immediate children. displayWithAllChildren() virtual void displayWithAllChildren(VkNode *node); virtual VkNode* displayWithAllChildren(char *name); Show the specified node along with all nodes below that point in the hierarchy. displayButterfly() virtual void displayButterfly(VkNode *node); virtual VkNode* displayButterfly(char *name); Change the graph display mode to display the given node as a "butterfly", a graph that has a node in the center, immediate parents to the left, and immediate children to the right. displayIf() virtual void displayIf(VkGraphFilterProc filterFunction); Loop through all nodes in the graph displaying any node that passes through the given filter function. The form of the filter function must be: Boolean filterFunction(VkNode *node); The function should return TRUE if the node should be displayed, or FALSE if it should not be displayed. forAllNodesDo() virtual void forAllNodesDo(VkGraphNodeProc function); Perform some operation on all nodes registered with the VkGraph component. The form of the specified function must be: void function (VkNode *node); setLayoutStyle() virtual void setLayoutStyle(char type); Set the layout style of the graph. Currently the supported styles are XmGRAPH and XmBUTTERFLY. XmGRAPH is the normal, hierarchical display mode. XmBUTTERFLY displays a given node as the center of a "butterfly" graph. See the displayButterfly() member function. find() VkNode* find(char *name); Returns the first VkNode object registered with the VkGraph object that has the given name. doLayout() void doLayout(void); Force a layout of the current graph. Normally, a program adds nodes to a graph, displays a subset of these nodes, and then calls doLayout() to arrange the nodes on the screen. doSubtreeLayout() void doSubtreeLayout(VkNode *node); Invoke the graph's layout routines on a subtree starting at the specified node. No other nodes are moved or considered. numNodes() int numNodes(void); Return the number of nodes in the abstract graph. graphWidget() Widget graphWidget(void); Returns the XmGraph widget instantiated by the VkGraph component. Not all the functionality of the XmGraph widget is encapsulated in the VkGraph class, and it is sometimes useful to set various resources directly on the graph widget. USING ATTRIBUTES When specifying a parent/child connection in the VkGraph component's abstract graph, it is possible to specify an attribute for that connection. An attribute is an arbitrary name that can be used to control the appearance of the arc widget that connects the two nodes. For example, assume two nodes are added to a graph as follows: graph->add(parent, child, "primary"); graph->add(parent, child, "secondary"); The resulting graph will display two connecting arcs between the two nodes. One can now specify X resources to control various aspects of the arc. For example: *primary*foreground: red *secondary*foreground: blue *primary*arcDirection: bidirected *secondary*arcDirection: undirected Most resource supported by the Arc widget are supported through this interface. The supported resources are: foreground toSide fromSide fromPosition toPosition arcDirection fontList arcWidth style dashes See the SgArc man page for details on these resources. X RESOURCES The VkGraph component sets the following default resources to control menu labels. "*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", EXAMPLES The following code segment creates a graph that displays a simple tree of three nodes. #include <Vk/VkNode.h> #include <Vk/VkGraph.h> void buildgraph(Widget parent) { VkGraph *graph = new VkGraph("graph", parent); VkNode *node1 = new VkNode("node1"); VkNode *node2 = new VkNode("node2"); VkNode *node3 = new VkNode("node3"); VkNode *node4 = new VkNode("node4"); graph->add(node1, node2); graph->add(node1, node3); graph->add(node2, node4); graph->displayAll(); graph->doLayout(); graph->show(); } The following code segment reads data from standard input in the form: parent child parentLabel childLabel and creates a graph. Note the use of VkGraph::find() to find an existing node for a given unique name. #include <Vk/VkNode.h> #include <Vk/VkGraph.h> void buildgraph(Widget parent) { char parentName[1000]; char childName[1000]; char childLabel[1000]; char parentLabel[1000]; VkGraph *graph = new VkGraph("graph", parent); while((nitems = scanf("%s %s %s %s", parentName, childName, parentLabel, childLabel)) != EOF && nitems == 4) { VkNode *parent, *child; parent = child = NULL; if(parentName && (parent = graph->find(parentName)) == NULL) parent = new VkNode(parentName, parentLabel); if(childName && (child = graph->find(childName)) == NULL) child = new VkNode(childName, childLabel); graph->add(parent, child); } graph->displayAll(); graph->doLayout(); graph->show(); } INHERITED MEMBER FUNCTIONS Inherited from VkComponent installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), VkComponent(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback Inherited from VkCallbackObject callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() CLASSES USED BY THIS CLASS VkApp, VkMenu, VkMenuItem, VkNode, VkPopupMenu SEE ALSO VkComponent, VkApp, VkMenu, VkMenuItem, VkNode, VkPopupMenu ViewKit Programmer's Guide The X Window System, DEC Press, Bob Sheifler and Jim Gettys The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick The OSF/Motif Programmers Reference, Prentice Hall, OSF