added wxFileName::MakeRelativeTo() and the tests/docs for it

[wxWidgets.git] / docs / latex / wx / treelay.tex

\section{\class{wxTreeLayout}}\label{wxtreelayout}

wxTreeLayout 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.

Nodes are identified by long integer identifiers. The derived class
communicates the actual tree structure to wxTreeLayout by defining \helpref{wxTreeLayout::GetChildren}{wxtreelayoutgetchildren}\rtfsp
and \helpref{wxTreeLayout::GetNodeParent}{wxtreelayoutgetnodeparent} functions.

The application should call \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout} to do the tree
layout. Depending on how the derived class has been defined, either
\rtfsp\helpref{wxTreeLayout::Draw}{wxtreelayoutdraw} must be called (for example by the OnPaint member
of a wxScrolledWindow) 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.

The algorithm is due to Gabriel Robins \cite{robins87}, 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.

\helponly{Below is the example tree generated by the program test.cc.

\begin{figure}
$$\image{11cm;0cm}{treetst.ps}$$
\caption{Example tree}\label{exampletree}
\end{figure}
}

\wxheading{Derived from}

wxObject

\wxheading{See also}

\helpref{wxTreeLayoutStored}{wxtreelayoutstored}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxTreeLayout::wxTreeLayout}

\func{}{wxTreeLayout}{\void}

Constructor.

\membersection{wxTreeLayout::ActivateNode}\label{wxtreelayoutactivatenode}

\func{void}{ActivateNode}{\param{long}{ id}, \param{bool }{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 \helpref{wxTreeLayout::NodeActive}{wxtreelayoutnodeactive}.

\membersection{wxTreeLayout::CalcLayout}

\func{void}{CalcLayout}{\param{long}{ id}, \param{int}{ level}}

Private function for laying out a branch.

\membersection{wxTreeLayout::DoLayout}\label{wxtreelayoutdolayout}

\func{void}{DoLayout}{\param{wxDC\&}{ dc}, \param{long}{ topNode = -1}}

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

\membersection{wxTreeLayout::Draw}\label{wxtreelayoutdraw}

\func{void}{Draw}{\param{wxDC\&}{ dc}}

Call this to let wxTreeLayout draw the tree itself, once the layout has been
calculated with \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout}.

\membersection{wxTreeLayout::DrawBranch}

\func{void}{DrawBranch}{\param{long}{ from}, \param{long}{ to}, \param{wxDC\&}{ dc}}

Defined by wxTreeLayout to draw an arc between two nodes.

\membersection{wxTreeLayout::DrawBranches}

\func{void}{DrawBranches}{\param{wxDC\&}{ dc}}

Defined by wxTreeLayout to draw the arcs between nodes.

\membersection{wxTreeLayout::DrawNode}

\func{void}{DrawNode}{\param{long}{ id}, \param{wxDC\&}{ dc}}

Defined by wxTreeLayout to draw a node.

\membersection{wxTreeLayout::DrawNodes}

\func{void}{DrawNodes}{\param{wxDC\&}{ dc}}

Defined by wxTreeLayout to draw the nodes.

\membersection{wxTreeLayout::GetChildren}\label{wxtreelayoutgetchildren}

\func{void}{GetChildren}{\param{long}{ id}, \param{wxList \&}{list}}

Must be defined to return the children of node {\it id} in the given list
of integers.

\membersection{wxTreeLayout::GetNextNode}\label{wxtreelayoutgetnextnode}

\func{long}{GetNextNode}{\param{long}{ id}}

Must be defined to return the next node after {\it 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.

\membersection{wxTreeLayout::GetNodeName}

\constfunc{wxString}{GetNodeName}{\param{long}{ id}}

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

\membersection{wxTreeLayout::GetNodeSize}

\constfunc{void}{GetNodeSize}{\param{long}{ id}, \param{long*}{ x}, \param{long*}{ y}}

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

\membersection{wxTreeLayout::GetNodeParent}\label{wxtreelayoutgetnodeparent}

\constfunc{long}{GetNodeParent}{\param{long}{ id}}

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

\membersection{wxTreeLayout::GetNodeX}

\constfunc{long}{GetNodeX}{\param{long}{ 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.

\membersection{wxTreeLayout::GetNodeY}

\constfunc{long}{GetNodeY}{\param{long}{ 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.

\membersection{wxTreeLayout::GetLeftMargin}

\constfunc{long}{GetLeftMargin}{\void}

Gets the left margin set with \helpref{wxTreeLayout::SetMargins}{wxtreelayoutsetmargins}.

\membersection{wxTreeLayout::GetOrientation}

\constfunc{bool}{GetOrientation}{\void}

Gets the orientation: TRUE means top-to-bottom, FALSE means left-to-right (the default).

\membersection{wxTreeLayout::GetTopMargin}

\constfunc{long}{GetTopMargin}{\void}

Gets the top margin set with \helpref{wxTreeLayout::SetMargins}{wxtreelayoutsetmargins}.

\membersection{wxTreeLayout::GetTopNode}

\constfunc{long}{GetTopNode}{\void}

wxTreeLayout calls this to get the top of the tree. Don't redefine this; call
\rtfsp\helpref{wxTreeLayout::SetTopNode}{wxtreelayoutsettopnode} instead before calling \helpref{wxTreeLayout::DoLayout}{wxtreelayoutdolayout}.

\membersection{wxTreeLayout::GetXSpacing}

\constfunc{long}{GetXSpacing}{\void}

Gets the horizontal spacing between nodes.

\membersection{wxTreeLayout::GetYSpacing}

\constfunc{long}{GetYSpacing}{\void}

Gets the vertical spacing between nodes.

\membersection{wxTreeLayout::Initialize}

\func{void}{Initialize}{\void}

Initializes wxTreeLayout. Call from application or overridden {\bf Initialize}
or constructor.

\membersection{wxTreeLayout::NodeActive}\label{wxtreelayoutnodeactive}

\func{bool}{NodeActive}{\param{long}{ id}}

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

\membersection{wxTreeLayout::SetNodeName}

\func{void}{SetNodeName}{\param{long}{ id}, \param{const wxString\& }{ name}}

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

\membersection{wxTreeLayout::SetNodeX}

\func{void}{SetNodeX}{\param{long}{ id}, \param{long}{ 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.

\membersection{wxTreeLayout::SetNodeY}

\func{void}{SetNodeY}{\param{long}{ id}, \param{long}{ 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.

\membersection{wxTreeLayout::SetOrientation}

\func{void}{SetOrientation}{\param{bool}{ orientation}}

Sets the tree orientation: TRUE means top-to-bottom, FALSE means left-to-right (the default).

\membersection{wxTreeLayout::SetTopNode}\label{wxtreelayoutsettopnode}

\func{void}{SetTopNode}{\param{long}{ id}}

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

\membersection{wxTreeLayout::SetSpacing}

\func{void}{SetSpacing}{\param{long}{ x}, \param{long}{ y}}

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

\membersection{wxTreeLayout::SetMargins}\label{wxtreelayoutsetmargins}

\func{void}{SetMargins}{\param{long}{ x}, \param{long}{ y}}

Sets the left and top margins of the whole tree.

\section{\class{wxTreeLayoutStored}}\label{wxtreelayoutstored}

wxTreeLayoutStored provides storage for node labels, position and client data. It also provides hit-testing
(which node a mouse event occurred on). It is usually a more convenient class to use than wxTreeLayout.

\wxheading{Derived from}

\helpref{wxTreeLayout}{wxtreelayout}\\
\helpref{wxObject}{wxobject}

\wxheading{See also}

\helpref{wxTreeLayout}{wxtreelayout}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxTreeLayoutStored::wxTreeLayoutStored}

\func{}{wxTreeLayoutStored}{\param{int }{noNodes = 200}}

Constructor. Specify the maximum number of nodes to be allocated.

\membersection{wxTreeLayoutStored::AddChild}\label{wxtreelayoutstoredaddchild}

\func{long}{AddChild}{\param{const wxString\&}{ name}, \param{const wxString\&}{ parent = ""}}

Adds a child with a given parent, returning the node id.

\membersection{wxTreeLayoutStored::GetClientData}\label{wxtreelayoutstoredgetclientdata}

\constfunc{long}{GetClientData}{\param{long}{ id}}

Gets the client data for the given node.

\membersection{wxTreeLayoutStored::GetNode}\label{wxtreelayoutstoredgetnode}

\constfunc{wxStoredNode*}{GetNode}{\param{long}{ id}}

Returns the wxStoredNode object for the given node id.

\membersection{wxTreeLayoutStored::GetNodeCount}\label{wxtreelayoutstoredgetnodecount}

\constfunc{int}{GetNodeCount}{\void}

Returns the current number of nodes.

\membersection{wxTreeLayoutStored::GetNumNodes}\label{wxtreelayoutstoredgetnumnodes}

\constfunc{int}{GetNumNodes}{\void}

Returns the maximum number of nodes.

\membersection{wxTreeLayoutStored::HitTest}\label{wxtreelayoutstoredhittest}

\func{wxString}{HitTest}{\param{wxMouseEvent\&}{ event}, \param{wxDC\& }{dc}}

Returns a string with the node name corresponding to the position of the mouse event, or the empty string if no node
was detected.

\membersection{wxTreeLayoutStored::NameToId}\label{wxtreelayoutstorednametoid}

\func{long}{NameToId}{\param{const wxString\&}{ name}}

Returns the id for the given node name, or -1 if there was no such node.

\membersection{wxTreeLayoutStored::SetClientData}\label{wxtreelayoutstoredsetclientdata}

\func{void}{SetClientData}{\param{long}{ id}, \param{long}{ clientData}}

Sets client data for the given node.