graph-pane

graph-pane Class

Summary

A graph pane is a pane that displays a hierarchy of items in a graph.

Package

capi

Superclasses

simple-pinboard-layout
choice

Subclasses

simple-network-pane

Initargs

`:roots`	The roots of the graph.
`:children-function`	Returns the children of a node.
`:layout-function`	A keyword denoting how to layout the nodes.
`:layout-x-adjust`	The adjust value for the `x` direction.
`:layout-y-adjust`	The adjust value for the `y` direction.
`:node-pinboard-class`
	The class of pane to represent nodes.
`:edge-pinboard-class`
	The class of pane to represent edges.
`:node-pane-function`
	A function to return an element for each node.
`:edge-pane-function`
	A function to return an element for each edge.

Accessors

graph-pane-layout-function
graph-pane-roots

Description

The class graph-pane is a pane that displays a hierarchy of items in a graph.

The graph-pane calculates the items of the graph by calling the children-function on each of its roots, and then calling it again on each of the children recursively until no more children are found. The children-function gets called with an item of the graph and should return a list of the children of that item.

Each item is represented by a node in the graph.

The layout-function tells the graph pane how to lay out its nodes. It can be one these values:

`:left-right`	Lay the graph out from the left to the right.
`:top-down`	Lay the graph out from the top down.
`:right-left`	Lay the graph out from the right to the left.
`:bottom-up`	Lay the graph out from the bottom up.

layout-x-adjust and layout-y-adjust act on the underlying layout to decide where to place the nodes. The values should be a keyword or a list of the form (keyword n) where n is an integer. These values of adjust are interpreted as by pane-adjusted-position. :top is the default for layout-y-adjust and :left is the default for layout-x-adjust.

When a graph pane wants to display nodes and edges, it creates instances of node-pinboard-class and edge-pinboard-class which default to item-pinboard-object and line-pinboard-object respectively. These classes must be subclasses of simple-pane or pinboard-object, and there are some examples of the use of these keywords below.

The node-pane-function is called to create an element for each node, and by default it creates an instance of node-pinboard-class. It gets passed the graph pane and the item corresponding to the node, and should return an instance of a subclass of simple-pane or pinboard-object. Note that the name of the initarg is a little misleading, as in most cases you should return a pinboard-object rather than a pane. If you use your own class which has its own geometry requirements, you should define a calculate-constraints method for it, which should use with-geometry on the object to set %min-width% and %width% to the desired width, and %height% and %min-height% to the desired height. See the example in:

(example-edit-file "capi/graphics/circled-graph-nodes")

edge-pane-function is called to create an element for an edge. The default creates an object of the class specified by edge-pinboard-class. If edge-pane-function is supplied, it must be a function that takes three arguments: the pane and the two items that are connected by the edge, and must return an element (a simple-pane or a pinboard-object).

To expand or contract a node, the user clicks on the circle next to the node. An expandable node has an unfilled circle and a collapsible node has a filled circle.

graph-pane is a subclass of choice, so for details of its selection handling, see choice.

The highlighting of the children is controlled as described for pinboard-layout, but for graph-pane the default value of highlight-style is :standard.

Notes

The output-pane initarg :drawing-mode controls quality of drawing in a graph-pane, including anti-aliasing of any text displayed on Microsoft Windows and GTK+.

Compatibility note

In LispWorks 4.3 the double click gesture on a graph-pane node always calls the action-callback, and the user gesture to expand or collapse a node is to click on the circle drawn alongside the node.

In LispWorks 4.2 and previous versions, the double click gesture was used for expansion and contraction of nodes and the action-callback was not always called.

Examples

(defun node-children (node)
  (when (< node 16)
    (list (* node 2)
          (1+ (* node 2)))))

(setq graph 
      (capi:contain
       (make-instance 'capi:graph-pane
                      :roots '(1)
                      :children-function
                      'node-children)
       :best-width 300 :best-height 400))

(capi:apply-in-pane-process 
 graph #'(setf capi:graph-pane-roots) '(2 6) graph)

(capi:contain 
 (make-instance 'capi:graph-pane
                :roots '(1)
                :children-function 
                'node-children
                :layout-function :top-down)
 :best-width 300 :best-height 400)

(capi:contain
 (make-instance 'capi:graph-pane
                :roots '(1)
                :children-function 
                'node-children
                :layout-function :top-down
                :layout-x-adjust :left)
 :best-width 300 :best-height 400)

This example demonstrates a different style of graph output with right-angle edges and parent nodes being adjusted towards the top instead of at the center.

(capi:contain 
 (make-instance
  'capi:graph-pane
  :roots '(1)
  :children-function 'node-children
  :layout-y-adjust '(:top 10)
  :edge-pinboard-class
  'capi:right-angle-line-pinboard-object)
 :best-width 300
 :best-height 400)

This example demonstrates the use of :node-pinboard-class to specify that the nodes are drawn as push buttons.

(capi:contain 
 (make-instance
  'capi:graph-pane
  :roots '(1)
  :children-function 'node-children
  :node-pinboard-class 'capi:push-button)
 :best-width 300
 :best-height 400)

There are more examples here:

(example-edit-file "capi/graphics/*graph*")