docs/latex/wx/treelay.tex

   1 \section{\class{wxTreeLayout}}\label{wxtreelayout}
   2
   3 wxTreeLayout provides layout of simple trees with one root node, drawn left-to-right,
   4 with user-defined spacing between nodes.
   5
   6 wxTreeLayout is an abstract class that must be subclassed. The programmer
   7 defines various member functions which will access whatever data structures
   8 are appropriate for the application, and wxTreeLayout uses these when laying
   9 out the tree.
  10
  11 Nodes are identified by long integer identifiers. The derived class
  12 communicates the actual tree structure to wxTreeLayout by defining \helpref{wxTreeLayout::GetChildren}{wxtreelayoutgetchildren}\rtfsp
  13 and \helpref{wxTreeLayout::GetNodeParent}{wxtreelayoutgetnodeparent} functions.
  14
  15 The application should call \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout} to do the tree
  16 layout. Depending on how the derived class has been defined, either
  17 \rtfsp\helpref{wxTreeLayout::Draw}{wxtreelayoutdraw} must be called (for example by the OnPaint member
  18 of a wxScrolledWindow) or the application-defined drawing code should be called
  19 as normal.
  20
  21 For example, if you have an image drawing system already defined, you
  22 may want wxTreeLayout to position existing node images in that system. So you
  23 just need a way for wxTreeLayout to set the node image positions according to
  24 the layout algorithm, and the rest will be done by your own image drawing
  25 system.
  26
  27 The algorithm is due to Gabriel Robins \cite{robins87}, a linear-time
  28 algorithm originally implemented in LISP for AI applications.
  29
  30 The original algorithm has been modified so that both X and Y planes
  31 are calculated simultaneously, increasing efficiency slightly. The basic
  32 code is only a page or so long.
  33
  34 \helponly{Below is the example tree generated by the program test.cc.
  35
  36 \begin{figure}
  37 $$\image{11cm;0cm}{treetst.ps}$$
  38 \caption{Example tree}\label{exampletree}
  39 \end{figure}
  40 }
  41
  42 \wxheading{Derived from}
  43
  44 wxObject
  45
  46 \wxheading{See also}
  47
  48 \helpref{wxTreeLayoutStored}{wxtreelayoutstored}
  49
  50 \latexignore{\rtfignore{\wxheading{Members}}}
  51
  52 \membersection{wxTreeLayout::wxTreeLayout}
  53
  54 \func{}{wxTreeLayout}{\void}
  55
  56 Constructor.
  57
  58 \membersection{wxTreeLayout::ActivateNode}\label{wxtreelayoutactivatenode}
  59
  60 \func{void}{ActivateNode}{\param{long}{ id}, \param{bool }{active}}
  61
  62 Define this so wxTreeLayout can turn nodes on and off for drawing purposes
  63 (not all nodes may be connected in the tree). See also \helpref{wxTreeLayout::NodeActive}{wxtreelayoutnodeactive}.
  64
  65 \membersection{wxTreeLayout::CalcLayout}
  66
  67 \func{void}{CalcLayout}{\param{long}{ id}, \param{int}{ level}}
  68
  69 Private function for laying out a branch.
  70
  71 \membersection{wxTreeLayout::DoLayout}\label{wxtreelayoutdolayout}
  72
  73 \func{void}{DoLayout}{\param{wxDC\&}{ dc}, \param{long}{ topNode = -1}}
  74
  75 Calculates the layout for the tree, optionally specifying the top node.
  76
  77 \membersection{wxTreeLayout::Draw}\label{wxtreelayoutdraw}
  78
  79 \func{void}{Draw}{\param{wxDC\&}{ dc}}
  80
  81 Call this to let wxTreeLayout draw the tree itself, once the layout has been
  82 calculated with \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout}.
  83
  84 \membersection{wxTreeLayout::DrawBranch}
  85
  86 \func{void}{DrawBranch}{\param{long}{ from}, \param{long}{ to}, \param{wxDC\&}{ dc}}
  87
  88 Defined by wxTreeLayout to draw an arc between two nodes.
  89
  90 \membersection{wxTreeLayout::DrawBranches}
  91
  92 \func{void}{DrawBranches}{\param{wxDC\&}{ dc}}
  93
  94 Defined by wxTreeLayout to draw the arcs between nodes.
  95
  96 \membersection{wxTreeLayout::DrawNode}
  97
  98 \func{void}{DrawNode}{\param{long}{ id}, \param{wxDC\&}{ dc}}
  99
 100 Defined by wxTreeLayout to draw a node.
 101
 102 \membersection{wxTreeLayout::DrawNodes}
 103
 104 \func{void}{DrawNodes}{\param{wxDC\&}{ dc}}
 105
 106 Defined by wxTreeLayout to draw the nodes.
 107
 108 \membersection{wxTreeLayout::GetChildren}\label{wxtreelayoutgetchildren}
 109
 110 \func{void}{GetChildren}{\param{long}{ id}, \param{wxList \&}{list}}
 111
 112 Must be defined to return the children of node {\it id} in the given list
 113 of integers.
 114
 115 \membersection{wxTreeLayout::GetNextNode}\label{wxtreelayoutgetnextnode}
 116
 117 \func{long}{GetNextNode}{\param{long}{ id}}
 118
 119 Must be defined to return the next node after {\it id}, so that wxTreeLayout can
 120 iterate through all relevant nodes. The ordering is not important.
 121 The function should return -1 if there are no more nodes.
 122
 123 \membersection{wxTreeLayout::GetNodeName}
 124
 125 \constfunc{wxString}{GetNodeName}{\param{long}{ id}}
 126
 127 May optionally be defined to get a node's name (for example if leaving
 128 the drawing to wxTreeLayout).
 129
 130 \membersection{wxTreeLayout::GetNodeSize}
 131
 132 \constfunc{void}{GetNodeSize}{\param{long}{ id}, \param{long*}{ x}, \param{long*}{ y}}
 133
 134 Can be defined to indicate a node's size, or left to wxTreeLayout to use the
 135 name as an indication of size.
 136
 137 \membersection{wxTreeLayout::GetNodeParent}\label{wxtreelayoutgetnodeparent}
 138
 139 \constfunc{long}{GetNodeParent}{\param{long}{ id}}
 140
 141 Must be defined to return the parent node of {\it id}.
 142 The function should return -1 if there is no parent.
 143
 144 \membersection{wxTreeLayout::GetNodeX}
 145
 146 \constfunc{long}{GetNodeX}{\param{long}{ id}}
 147
 148 Must be defined to return the current X position of the node. Note that
 149 coordinates are assumed to be at the top-left of the node so some conversion
 150 may be necessary for your application.
 151
 152 \membersection{wxTreeLayout::GetNodeY}
 153
 154 \constfunc{long}{GetNodeY}{\param{long}{ id}}
 155
 156 Must be defined to return the current Y position of the node. Note that
 157 coordinates are assumed to be at the top-left of the node so some conversion
 158 may be necessary for your application.
 159
 160 \membersection{wxTreeLayout::GetLeftMargin}
 161
 162 \constfunc{long}{GetLeftMargin}{\void}
 163
 164 Gets the left margin set with \helpref{wxTreeLayout::SetMargins}{wxtreelayoutsetmargins}.
 165
 166 \membersection{wxTreeLayout::GetOrientation}
 167
 168 \constfunc{bool}{GetOrientation}{\void}
 169
 170 Gets the orientation: TRUE means top-to-bottom, FALSE means left-to-right (the default).
 171
 172 \membersection{wxTreeLayout::GetTopMargin}
 173
 174 \constfunc{long}{GetTopMargin}{\void}
 175
 176 Gets the top margin set with \helpref{wxTreeLayout::SetMargins}{wxtreelayoutsetmargins}.
 177
 178 \membersection{wxTreeLayout::GetTopNode}
 179
 180 \constfunc{long}{GetTopNode}{\void}
 181
 182 wxTreeLayout calls this to get the top of the tree. Don't redefine this; call
 183 \rtfsp\helpref{wxTreeLayout::SetTopNode}{wxtreelayoutsettopnode} instead before calling \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout}.
 184
 185 \membersection{wxTreeLayout::GetXSpacing}
 186
 187 \constfunc{long}{GetXSpacing}{\void}
 188
 189 Gets the horizontal spacing between nodes.
 190
 191 \membersection{wxTreeLayout::GetYSpacing}
 192
 193 \constfunc{long}{GetYSpacing}{\void}
 194
 195 Gets the vertical spacing between nodes.
 196
 197 \membersection{wxTreeLayout::Initialize}
 198
 199 \func{void}{Initialize}{\void}
 200
 201 Initializes wxTreeLayout. Call from application or overridden {\bf Initialize}
 202 or constructor.
 203
 204 \membersection{wxTreeLayout::NodeActive}\label{wxtreelayoutnodeactive}
 205
 206 \func{bool}{NodeActive}{\param{long}{ id}}
 207
 208 Define this so wxTreeLayout can know which nodes are to be drawn (not all
 209 nodes may be connected in the tree). See also \helpref{wxTreeLayout::ActivateNode}{wxtreelayoutactivatenode}.
 210
 211 \membersection{wxTreeLayout::SetNodeName}
 212
 213 \func{void}{SetNodeName}{\param{long}{ id}, \param{const wxString\& }{ name}}
 214
 215 May optionally be defined to set a node's name.
 216
 217 \membersection{wxTreeLayout::SetNodeX}
 218
 219 \func{void}{SetNodeX}{\param{long}{ id}, \param{long}{ x}}
 220
 221 Must be defined to set the current X position of the node. Note that
 222 coordinates are assumed to be at the top-left of the node so some conversion
 223 may be necessary for your application.
 224
 225 \membersection{wxTreeLayout::SetNodeY}
 226
 227 \func{void}{SetNodeY}{\param{long}{ id}, \param{long}{ y}}
 228
 229 Must be defined to set the current Y position of the node. Note that
 230 coordinates are assumed to be at the top-left of the node so some conversion
 231 may be necessary for your application.
 232
 233 \membersection{wxTreeLayout::SetOrientation}
 234
 235 \func{void}{SetOrientation}{\param{bool}{ orientation}}
 236
 237 Sets the tree orientation: TRUE means top-to-bottom, FALSE means left-to-right (the default).
 238
 239 \membersection{wxTreeLayout::SetTopNode}\label{wxtreelayoutsettopnode}
 240
 241 \func{void}{SetTopNode}{\param{long}{ id}}
 242
 243 Call this to identify the top of the tree to wxTreeLayout.
 244
 245 \membersection{wxTreeLayout::SetSpacing}
 246
 247 \func{void}{SetSpacing}{\param{long}{ x}, \param{long}{ y}}
 248
 249 Sets the horizontal and vertical spacing between nodes in the tree.
 250
 251 \membersection{wxTreeLayout::SetMargins}\label{wxtreelayoutsetmargins}
 252
 253 \func{void}{SetMargins}{\param{long}{ x}, \param{long}{ y}}
 254
 255 Sets the left and top margins of the whole tree.
 256
 257 \section{\class{wxTreeLayoutStored}}\label{wxtreelayoutstored}
 258
 259 wxTreeLayoutStored provides storage for node labels, position and client data. It also provides hit-testing
 260 (which node a mouse event occurred on). It is usually a more convenient class to use than wxTreeLayout.
 261
 262 \wxheading{Derived from}
 263
 264 \helpref{wxTreeLayout}{wxtreelayout}\\
 265 \helpref{wxObject}{wxobject}
 266
 267 \wxheading{See also}
 268
 269 \helpref{wxTreeLayout}{wxtreelayout}
 270
 271 \latexignore{\rtfignore{\wxheading{Members}}}
 272
 273 \membersection{wxTreeLayoutStored::wxTreeLayoutStored}
 274
 275 \func{}{wxTreeLayoutStored}{\param{int }{noNodes = 200}}
 276
 277 Constructor. Specify the maximum number of nodes to be allocated.
 278
 279 \membersection{wxTreeLayoutStored::AddChild}\label{wxtreelayoutstoredaddchild}
 280
 281 \func{long}{AddChild}{\param{const wxString\&}{ name}, \param{const wxString\&}{ parent = ""}}
 282
 283 Adds a child with a given parent, returning the node id.
 284
 285 \membersection{wxTreeLayoutStored::GetClientData}\label{wxtreelayoutstoredgetclientdata}
 286
 287 \constfunc{long}{GetClientData}{\param{long}{ id}}
 288
 289 Gets the client data for the given node.
 290
 291 \membersection{wxTreeLayoutStored::GetNode}\label{wxtreelayoutstoredgetnode}
 292
 293 \constfunc{wxStoredNode*}{GetNode}{\param{long}{ id}}
 294
 295 Returns the wxStoredNode object for the given node id.
 296
 297 \membersection{wxTreeLayoutStored::GetNodeCount}\label{wxtreelayoutstoredgetnodecount}
 298
 299 \constfunc{int}{GetNodeCount}{\void}
 300
 301 Returns the current number of nodes.
 302
 303 \membersection{wxTreeLayoutStored::GetNumNodes}\label{wxtreelayoutstoredgetnumnodes}
 304
 305 \constfunc{int}{GetNumNodes}{\void}
 306
 307 Returns the maximum number of nodes.
 308
 309 \membersection{wxTreeLayoutStored::HitTest}\label{wxtreelayoutstoredhittest}
 310
 311 \func{wxString}{HitTest}{\param{wxMouseEvent\&}{ event}, \param{wxDC\& }{dc}}
 312
 313 Returns a string with the node name corresponding to the position of the mouse event, or the empty string if no node
 314 was detected.
 315
 316 \membersection{wxTreeLayoutStored::NameToId}\label{wxtreelayoutstorednametoid}
 317
 318 \func{long}{NameToId}{\param{const wxString\&}{ name}}
 319
 320 Returns the id for the given node name, or -1 if there was no such node.
 321
 322 \membersection{wxTreeLayoutStored::SetClientData}\label{wxtreelayoutstoredsetclientdata}
 323
 324 \func{void}{SetClientData}{\param{long}{ id}, \param{long}{ clientData}}
 325
 326 Sets client data for the given node.
 327