use wxChar correctly in wxString docs; mark wx1 compatibility functions

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        treebook.tex
%% Purpose:     wxTreebook documentation
%% Author:      Evgeniy Tarassov
%% Modified by:
%% Created:     2005-10-04
%% RCS-ID:      $Id$
%% Copyright:   (c) 2005 Vadim Zeitlin <vadim@wxwindows.org>
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxTreebook}}\label{wxtreebook}

This class is an extension of the Notebook class that allows a tree structured
set of pages to be shown in a control.
A classic example is a netscape preferences dialog that shows a tree
of preference sections on the left and select section page on the right.

To use the class simply create it and populate with pages using
\helpref{InsertPage}{wxtreebookinsertpage},
\helpref{InsertSubPage}{wxtreebookinsertsubpage},
\helpref{AddPage}{wxtreebookaddpage},
\helpref{AddSubPage}{wxtreebookaddsubpage}.

If your tree is no more than $1$ level in depth then you could
simply use \helpref{AddPage}{wxtreebookaddpage} and 
\helpref{AddSubPage}{wxtreebookaddsubpage} to sequentially populate your tree
by adding at every step a page or a subpage to the end of the tree.


\wxheading{Derived from}

wxBookCtrlBase\\
\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}


\wxheading{Include files}

<wx/treebook.h>

\input treebookevt.inc


\wxheading{See also}

\helpref{wxNotebook}{wxnotebook}, \helpref{wxTreebookEvent}{wxtreebookevent}, \helpref{wxImageList}{wximagelist}, \helpref{notebook sample}{samplenotebook}



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


\membersection{wxTreebook::wxTreebook}\label{wxtreebookwxtreebook}

\func{}{wxTreebook}{\void}

Default constructor.


\func{}{wxTreebook}{
    \param{wxWindow* }{parent},
    \param{wxWindowID }{id},
    \param{const wxPoint\& }{pos = wxDefaultPosition},
    \param{const wxSize\& }{size = wxDefaultSize},
    \param{long }{style = wxTBK\_DEFAULT},
    \param{const wxString\& }{name = wxEmptyString}}

Creates an empty TreeBook control.

\wxheading{Parameters}

\docparam{parent}{The parent window. Must be non-NULL.}

\docparam{id}{The window identifier.}

\docparam{pos}{The window position.}

\docparam{size}{The window size.}

\docparam{style}{The window style. See \helpref{wxNotebook}{wxnotebook}.}

\docparam{name}{The name of the control (used only under Motif).}



\membersection{wxTreebook::\destruct{wxTreebook}}\label{wxtreebookdtor}

\func{}{\destruct{wxTreebook}}{\void}

Destroys the wxTreebook object.

Also deletes all the pages owned by the control (inserted previously into it).



\membersection{wxTreebook::AddPage}\label{wxtreebookaddpage}

\func{bool}{AddPage}{
    \param{wxWindow* }{page},
    \param{const wxString\& }{text},
    \param{bool }{bSelect = false},
    \param{int }{imageId = wxNOT\_FOUND}}

Adds a new page. The page is placed at the topmost level after all other pages.
\NULL could be specified for page to create an empty page.



\membersection{wxTreebook::AddSubPage}\label{wxtreebookaddsubpage}

\func{bool}{AddSubPage}{\param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}

Adds a new child-page to the last top-level page.
\NULL could be specified for page to create an empty page.



\membersection{wxTreebook::AssignImageList}\label{wxtreebookassignimagelist}

\func{void}{AssignImageList}{\param{wxImageList* }{imageList}}

Sets the image list for the page control and takes ownership of the list.

\wxheading{See also}

\helpref{wxImageList}{wximagelist}, \helpref{SetImageList}{wxtreebooksetimagelist}



\membersection{wxTreebook::CollapseNode}\label{wxtreebookcollapsenode}

\func{bool}{CollapseNode}{\param{size\_t }{pageId}}

Shortcut for \helpref{ExpandNode}{wxtreebookexpandnode}(pageId, false).



\membersection{wxTreebook::Create}\label{wxtreebookcreate}

\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxTBK\_DEFAULT}, \param{const wxString\& }{name = wxEmptyString}}

Creates a treebook control. See \helpref{wxTreebook::wxTreebook}{wxtreebookwxtreebook} for the description of the parameters.



\membersection{wxTreebook::DeleteAllPages}\label{wxtreebookdeleteallpages}

\func{bool}{DeleteAllPages}{\void}

Deletes all pages inserted into the treebook. No event is generated.



\membersection{wxTreebook::DeletePage}\label{wxtreebookdeletepage}

\func{bool}{DeletePage}{\param{size\_t }{pagePos}}

Deletes the page at the specified position and all its children. Could trigger page selection change
in a case when selected page is removed. In that case its parent is selected
(or the next page if no parent).



\membersection{wxTreebook::ExpandNode}\label{wxtreebookexpandnode}

\func{bool}{ExpandNode}{\param{size\_t }{pageId}, \param{bool }{expand = true}}

Expands (collapses) the pageId node. Returns the previous state.
May generate page changing events (if selected page
is under the collapsed branch, then its parent is autoselected).


\membersection{wxTreebook::GetPageImage}\label{wxtreebookgetpageimage}

\constfunc{int}{GetPageImage}{\param{size\_t }{n}}

Returns the image index for the given page.


\membersection{wxTreebook::GetPageParent}\label{wxtreebookgetpageparent}

\constfunc{int}{GetPageParent}{\param{size\_t }{page}}

Returns the parent page of the given one or \texttt{wxNOT\_FOUND} if this is a
top-level page.


\membersection{wxTreebook::GetPageText}\label{wxtreebookgetpagetext}

\constfunc{wxString}{GetPageText}{\param{size\_t }{n}}

Returns the string for the given page.



\membersection{wxTreebook::GetSelection}\label{wxtreebookgetselection}

\constfunc{int}{GetSelection}{\void}

Returns the currently selected page, or wxNOT\_FOUND if none was selected.

Note that this method may return either the previously or newly selected page
when called from the EVT\_TREEBOOK\_PAGE\_CHANGED handler
depending on the platform and so wxTreebookEvent::GetSelection should be used instead in this case.



\membersection{wxTreebook::InsertPage}\label{wxtreebookinsertpage}

\func{bool}{InsertPage}{\param{size\_t }{pagePos}, \param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}

Inserts a new page just before the page indicated by pagePos.
The new page is placed before pagePos page and on the same level.
\NULL could be specified for page to create an empty page.


\membersection{wxTreebook::InsertSubPage}\label{wxtreebookinsertsubpage}

\func{bool}{InsertSubPage}{\param{size\_t }{pagePos}, \param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}

Inserts a sub page under the specified page.

\NULL could be specified for page to create an empty page.


\membersection{wxTreebook::IsNodeExpanded}\label{wxtreebookisnodeexpanded}

\constfunc{bool}{IsNodeExpanded}{\param{size\_t }{pageId}}

Gets the pagePos page state -- whether it is expanded or collapsed



\membersection{wxTreebook::SetImageList}\label{wxtreebooksetimagelist}

\func{void}{SetImageList}{\param{wxImageList* }{imageList}}

Sets the image list for the page control. It does not take ownership of the image list, you must delete it yourself.

\wxheading{See also}

\helpref{wxImageList}{wximagelist}, \helpref{AssignImageList}{wxtreebookassignimagelist}



\membersection{wxTreebook::SetPageImage}\label{wxtreebooksetpageimage}

\func{bool}{SetPageImage}{\param{size\_t }{page}, \param{int }{imageId}}

Sets the image index for the given page. ImageId is an index into the image list
which was set with \helpref{SetImageList}{wxtreebooksetimagelist}.



\membersection{wxTreebook::SetPageText}\label{wxtreebooksetpagetext}

\func{bool}{SetPageText}{\param{size\_t }{page}, \param{const wxString\& }{text}}

Sets the text for the given page.



\membersection{wxTreebook::SetSelection}\label{wxtreebooksetselection}

\func{int}{SetSelection}{\param{size\_t }{n}}

Sets the selection for the given page, returning the previous selection.

The call to this function generates the page changing events.

This function is deprecated and should not be used in new code. Please use the
\helpref{ChangeSelection}{wxtreebookchangeselection} function instead.

\wxheading{See also}

\helpref{wxTreebook::GetSelection}{wxtreebookgetselection}



\membersection{wxTreebook::ChangeSelection}\label{wxtreebookchangeselection}

\func{int}{ChangeSelection}{\param{size\_t}{ page}}

Changes the selection for the given page, returning the previous selection.

The call to this function \emph{does not} generate the page changing events.
This is the only difference with \helpref{SetSelection}{wxtreebooksetselection}.
See \helpref{this topic}{progevent} for more info.