\hy-9{0}{
}



\hy-5{2}{Manual for wxTreeLayout 1.0: a tree layout library for wxWindows}

\hy-6{3}{Julian Smart
Artificial Intelligence Applications Institute

University of Edinburgh
EH1 1HN}

November 1993







\hy-5{1}{

Contents

}
\hy-6{4}{Copyright notice}

\hy-6{6}{Introduction}

\hy-6{8}{Implementation}

\hy-6{10}{wxTreeLayout Class Reference}

\hy-6{155}{References}


\hy-10{5}{Copyright notice}


Copyright (c) 1993 Artificial Intelligence Applications Institute,
The University of Edinburgh.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice, author statement and this permission notice appear in
all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR THE
UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF
DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH
THE USE OR PERFORMANCE OF THIS SOFTWARE.


\hy-10{7}{Introduction}


This manual describes a tree-drawing class library for wxWindows. It
provides layout of simple trees with one root node, drawn left-to-right,
with user-defined spacing between nodes.

wxTreeLayout is an abstract class that must be subclassed. The programmer
defines various member functions which will access whatever data structures
are appropriate for the application, and wxTreeLayout uses these when laying
out the tree.

wxStoredTree is a class derived from wxTreeLayout that may be used directly to
draw trees on a canvas. It supplies storage for the nodes, and draws
to a device context.

Below is the example tree generated by the program test.cc.


11cm;0cmtreetst.ps
Figure 1.1: Example tree




\hy-10{9}{Implementation}


The algorithm is due to Gabriel Robins [1], a linear-time
algorithm originally implemented in LISP for AI applications.

The original algorithm has been modified so that both X and Y planes
are calculated simultaneously, increasing efficiency slightly. The basic
code is only a page or so long.


\hy-10{11}{wxTreeLayout Class Reference}


The member functions are given in alphabetical order except for the
constructors and destructors which appear first.

\hy-8{12}{wxTreeLayout: wxObject}


\hy-10{156}{References}
[1] \hy-8{157}{Robins, Gabriel}. 1987 (September). \hy-7{158}{The ISI grapher: a portable tool for displaying graphs pictorially (ISI/RS-87-196). }Technical report. University of South California. 


\hy-10{13}{wxTreeLayout: wxObject}

This abstract class is used for drawing a tree. You must derive a new
class from this, and define member functions to access the data that
wxTreeLayout needs.

Nodes are identified by long integer identifiers. The derived class
communicates the actual tree structure to wxTreeLayout by defining \hy-13{14}{wxTreeLayout::GetChildren}
and \hy-13{15}{wxTreeLayout::GetNodeParent} functions.

The application should call \hy-13{16}{DoLayout} to do the tree
layout. Depending on how the derived class has been defined, either
\hy-13{17}{wxTreeLayout::Draw} must be called (for example by the OnDraw member
of a wxCanvas) or the application-defined drawing code should be called
as normal.

For example, if you have an image drawing system already defined, you
may want wxTreeLayout to position existing node images in that system. So you
just need a way for wxTreeLayout to set the node image positions according to
the layout algorithm, and the rest will be done by your own image drawing
system.

\hy-8{18}{wxTreeLayout::wxTreeLayout}

\hy-8{22}{wxTreeLayout::ActivateNode}

\hy-8{28}{wxTreeLayout::DoLayout}

\hy-8{32}{wxTreeLayout::Draw}

\hy-8{37}{wxTreeLayout::DrawBranch}

\hy-8{42}{wxTreeLayout::DrawBranches}

\hy-8{45}{wxTreeLayout::DrawNode}

\hy-8{49}{wxTreeLayout::DrawNodes}

\hy-8{52}{wxTreeLayout::GetChildren}

\hy-8{58}{wxTreeLayout::GetDC}

\hy-8{61}{wxTreeLayout::GetNextNode}

\hy-8{66}{wxTreeLayout::GetNodeName}

\hy-8{70}{wxTreeLayout::GetNodeSize}

\hy-8{76}{wxTreeLayout::GetNodeParent}

\hy-8{81}{wxTreeLayout::GetNodeX}

\hy-8{85}{wxTreeLayout::GetNodeY}

\hy-8{89}{wxTreeLayout::GetLeftMargin}

\hy-8{93}{wxTreeLayout::GetTopMargin}

\hy-8{97}{wxTreeLayout::GetTopNode}

\hy-8{102}{wxTreeLayout::GetXSpacing}

\hy-8{105}{wxTreeLayout::GetYSpacing}

\hy-8{108}{wxTreeLayout::Initialize}

\hy-8{112}{wxTreeLayout::CalcLayout}

\hy-8{117}{wxTreeLayout::NodeActive}

\hy-8{122}{wxTreeLayout::SetNodeName}

\hy-8{127}{wxTreeLayout::SetNodeX}

\hy-8{132}{wxTreeLayout::SetNodeY}

\hy-8{137}{wxTreeLayout::SetTopNode}

\hy-8{141}{wxTreeLayout::SetDC}

\hy-8{145}{wxTreeLayout::SetSpacing}

\hy-8{150}{wxTreeLayout::SetMargins}


\hy-10{19}{wxTreeLayout::wxTreeLayout}

\hy-8{20}{void wxTreeLayout(wxDC * \hy-8{21}{dc = NULL})}

Constructor.


\hy-10{23}{wxTreeLayout::ActivateNode}

\hy-8{24}{void ActivateNode(long \hy-8{25}{ id}, Bool  \hy-8{26}{active})}

Define this so wxTreeLayout can turn nodes on and off for drawing purposes
(not all nodes may be connected in the tree). See also \hy-13{27}{NodeActive}.


\hy-10{29}{wxTreeLayout::DoLayout}

\hy-8{30}{void DoLayout(long \hy-8{31}{ topNode = -1})}

Calculates the layout for the tree, optionally specifying the top node.


\hy-10{33}{wxTreeLayout::Draw}

\hy-8{34}{void Draw(void)}

Call this to let wxTreeLayout draw the tree itself, once the layout has been
calculated with \hy-13{35}{DoLayout}. The device context must
have been set in the constructor or using \hy-13{36}{SetDC}.


\hy-10{38}{wxTreeLayout::DrawBranch}

\hy-8{39}{void DrawBranch(long \hy-8{40}{ from}, long \hy-8{41}{ to})}

Defined by wxTreeLayout to draw an arc between two nodes.


\hy-10{43}{wxTreeLayout::DrawBranches}

\hy-8{44}{void DrawBranches(void)}

Defined by wxTreeLayout to draw the arcs between nodes.


\hy-10{46}{wxTreeLayout::DrawNode}

\hy-8{47}{void DrawNode(long \hy-8{48}{ id})}

Defined by wxTreeLayout to draw a node.


\hy-10{50}{wxTreeLayout::DrawNodes}

\hy-8{51}{void DrawNodes(void)}

Defined by wxTreeLayout to draw the nodes.


\hy-10{53}{wxTreeLayout::GetChildren}

\hy-8{54}{void GetChildren(long \hy-8{55}{ id}, wxList & \hy-8{56}{list})}

Must be defined to return the children of node \hy-7{57}{id} in the given list
of integers.


\hy-10{59}{wxTreeLayout::GetDC}

\hy-8{60}{long GetDC(void)}

Gets the (optional) device context associated with the tree.


\hy-10{62}{wxTreeLayout::GetNextNode}

\hy-8{63}{long GetNextNode(long \hy-8{64}{ id})}

Must be defined to return the next node after \hy-7{65}{id}, so that wxTreeLayout can
iterate through all relevant nodes. The ordering is not important.
The function should return -1 if there are no more nodes.


\hy-10{67}{wxTreeLayout::GetNodeName}

\hy-8{68}{char * GetNodeName(long \hy-8{69}{ id})}

May optionally be defined to get a node's name (for example if leaving
the drawing to wxTreeLayout).


\hy-10{71}{wxTreeLayout::GetNodeSize}

\hy-8{72}{void GetNodeSize(long \hy-8{73}{ id}, float \hy-8{74}{ *x}, float \hy-8{75}{ *y})}

Can be defined to indicate a node's size, or left to wxTreeLayout to use the
name as an indication of size.


\hy-10{77}{wxTreeLayout::GetNodeParent}

\hy-8{78}{long GetNodeParent(long \hy-8{79}{ id})}

Must be defined to return the parent node of \hy-7{80}{id}.
The function should return -1 if there is no parent.


\hy-10{82}{wxTreeLayout::GetNodeX}

\hy-8{83}{float GetNodeX(long \hy-8{84}{ id})}

Must be defined to return the current X position of the node. Note that
coordinates are assumed to be at the top-left of the node so some conversion
may be necessary for your application.


\hy-10{86}{wxTreeLayout::GetNodeY}

\hy-8{87}{float GetNodeY(long \hy-8{88}{ id})}

Must be defined to return the current Y position of the node. Note that
coordinates are assumed to be at the top-left of the node so some conversion
may be necessary for your application.


\hy-10{90}{wxTreeLayout::GetLeftMargin}

\hy-8{91}{float GetLeftMargin(void)}

Gets the left margin set with \hy-13{92}{SetMargins}.


\hy-10{94}{wxTreeLayout::GetTopMargin}

\hy-8{95}{float GetTopMargin(void)}

Gets the top margin set with \hy-13{96}{SetMargins}.


\hy-10{98}{wxTreeLayout::GetTopNode}

\hy-8{99}{long GetTopNode(void)}

wxTreeLayout calls this to get the top of the tree. Don't redefine this; call
\hy-13{100}{SetTopNode} instead before calling \hy-13{101}{DoLayout}.


\hy-10{103}{wxTreeLayout::GetXSpacing}

\hy-8{104}{float GetXSpacing(void)}

Gets the horizontal spacing between nodes.


\hy-10{106}{wxTreeLayout::GetYSpacing}

\hy-8{107}{float GetYSpacing(void)}

Gets the vertical spacing between nodes.


\hy-10{109}{wxTreeLayout::Initialize}

\hy-8{110}{void Initialize(void)}

Initializes wxTreeLayout. Call from application or overridden \hy-8{111}{Initialize}
or constructor.


\hy-10{113}{wxTreeLayout::CalcLayout}

\hy-8{114}{void CalcLayout(long \hy-8{115}{ node_id}, int \hy-8{116}{ level})}

Private function for laying out a branch.


\hy-10{118}{wxTreeLayout::NodeActive}

\hy-8{119}{Bool NodeActive(long \hy-8{120}{ id})}

Define this so wxTreeLayout can know which nodes are to be drawn (not all
nodes may be connected in the tree). See also \hy-13{121}{ActivateNode}.


\hy-10{123}{wxTreeLayout::SetNodeName}

\hy-8{124}{void SetNodeName(long \hy-8{125}{ id}, char * \hy-8{126}{ name})}

May optionally be defined to set a node's name.


\hy-10{128}{wxTreeLayout::SetNodeX}

\hy-8{129}{void SetNodeX(long \hy-8{130}{ id}, float \hy-8{131}{ x})}

Must be defined to set the current X position of the node. Note that
coordinates are assumed to be at the top-left of the node so some conversion
may be necessary for your application.


\hy-10{133}{wxTreeLayout::SetNodeY}

\hy-8{134}{void SetNodeY(long \hy-8{135}{ id}, float \hy-8{136}{ y})}

Must be defined to set the current Y position of the node. Note that
coordinates are assumed to be at the top-left of the node so some conversion
may be necessary for your application.


\hy-10{138}{wxTreeLayout::SetTopNode}

\hy-8{139}{void SetTopNode(long \hy-8{140}{ id})}

Call this to identify the top of the tree to wxTreeLayout.


\hy-10{142}{wxTreeLayout::SetDC}

\hy-8{143}{void SetDC(wxDC * \hy-8{144}{dc})}

Use this to set the tree's device context, if leaving the drawing up
to wxTreeLayout.


\hy-10{146}{wxTreeLayout::SetSpacing}

\hy-8{147}{void SetSpacing(float \hy-8{148}{ x}, float \hy-8{149}{ y})}

Sets the horizontal and vertical spacing between nodes in the tree.


\hy-10{151}{wxTreeLayout::SetMargins}

\hy-8{152}{void SetMargins(float \hy-8{153}{ x}, float \hy-8{154}{ y})}

Sets the left and top margins of the whole tree.






\hyindex{
"wxTree Manual"
4 5
6 7
8 9
10 11
12 13
18 19
22 23
28 29
32 33
37 38
42 43
45 46
49 50
52 53
58 59
61 62
66 67
70 71
76 77
81 82
85 86
89 90
93 94
97 98
102 103
105 106
108 109
112 113
117 118
122 123
127 128
132 133
137 138
141 142
145 146
150 151
155 156
14 53
14 53
15 77
15 77
16 29
16 29
17 33
17 33
27 118
27 118
35 29
35 29
36 142
36 142
92 151
92 151
96 151
96 151
100 138
100 138
101 29
101 29
121 23
121 23
14 53
14 53
15 77
15 77
16 29
16 29
17 33
17 33
27 118
27 118
35 29
35 29
36 142
36 142
92 151
92 151
96 151
96 151
100 138
100 138
101 29
101 29
121 23
121 23
}
