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 a pane for each node.

Accessors

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

Description

A 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 a pane 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.

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

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

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 in the directory examples/capi/graphics/ .

See also

item-pinboard-object
line-pinboard-object