Added wxTreebook:

- added the control itself
- added protected wxBookCtrlBase::AllowNullPage() to accommodate it
- big changes to the sample to get rid of (most) ugly macros
- added XRC handler for the control
- added docs
- and wxUSE_TREEBOOK everywhere


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@35862 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -44,6 +44,7 @@ The following are a variety of classes that are derived from wxWindow.
 \twocolitem{\helpref{wxNotebook}{wxnotebook}}{Notebook class}
 \twocolitem{\helpref{wxListbook}{wxlistbook}}{Similar to notebook but using list control}
 \twocolitem{\helpref{wxChoicebook}{wxchoicebook}}{Similar to notebook but using choice control}
+\twocolitem{\helpref{wxTreebook}{wxtreebook}}{Similar to notebook but using tree control}
 \twocolitem{\helpref{wxSashWindow}{wxsashwindow}}{Window with four optional sashes that can be dragged}
 \twocolitem{\helpref{wxSashLayoutWindow}{wxsashlayoutwindow}}{Window that can be involved in an IDE-like layout arrangement}
 \twocolitem{\helpref{wxVScrolledWindow}{wxvscrolledwindow}}{As wxScrolledWindow but supports lines of variable height}
@@ -252,6 +253,7 @@ An event object contains information about a specific event. Event handlers
 \twocolitem{\helpref{wxSplitterEvent}{wxsplitterevent}}{An event from \helpref{wxSplitterWindow}{wxsplitterwindow}}
 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
 \twocolitem{\helpref{wxTimerEvent}{wxtimerevent}}{A timer expiration event}
+\twocolitem{\helpref{wxTreebookEvent}{wxtreebookevent}}{A treebook control event}
 \twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{A tree control event}
 \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
 \twocolitem{\helpref{wxWindowCreateEvent}{wxwindowcreateevent}}{A window creation event}

docs/latex/wx/classes.tex

@@ -348,6 +348,8 @@
 \input toolbar.tex
 \input tooltip.tex
 \input tlw.tex
+\input treebook.tex
+\input treebookevent.tex
 \input treectrl.tex
 \input treeevt.tex
 \input treedata.tex

docs/latex/wx/treebook.tex

@@ -0,0 +1,269 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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{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}}
+
+\func{bool}{AddSubPage}{\param{size\_t }{pagePos}, \param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}
+
+Adds a new child-page to either the last or the specified top-level.
+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::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.
+
+\wxheading{See also}
+
+\helpref{wxTreebook::GetSelection}{wxtreebookgetselection}
+

docs/latex/wx/treebookevent.tex

@@ -0,0 +1,80 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        treebookevent.tex
+%% Purpose:     wxTreebookEvent 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{wxTreebookEvent}}\label{wxtreebookevent}
+
+This class represents the events generated by a treebook control: currently,
+there are four of them. The PAGE\_CHANGING and PAGE\_CHANGED - have exactly the same
+behaviour as \helpref{wxNotebookEvent}{wxnotebookevent}.
+
+The other two NODE\_COLLAPSED and NODE\_EXPANDED are triggered when page node in the tree control
+is collapsed/expanded. The page index could be retreived by calling
+\helpref{wxTreebookEvent::GetSelection}{wxtreebookeventgetselection}.
+
+
+
+\wxheading{Derived from}
+
+wxBookCtrlBaseEvent\\
+\helpref{wxNotifyEvent}{wxnotifyevent}\\
+\helpref{wxCommandEvent}{wxcommandevent}\\
+\helpref{wxEvent}{wxevent}\\
+\helpref{wxObject}{wxobject}
+
+
+
+\wxheading{Include files}
+
+<treebook.h>
+
+
+
+\input treebookevt.inc
+
+
+
+\wxheading{See also}
+
+\helpref{wxNotebookEvent}{wxnotebookevent}, \helpref{wxTreebook}{wxtreebook}
+
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxTreebookEvent::wxTreebookEvent}\label{wxtreebookeventwxtreebookevent}
+
+\func{}{wxTreebookEvent}{\param{wxEventType }{commandType = wxEVT\_NULL}, \param{int }{id = 0}, \param{int }{nSel = wxNOT\_FOUND}, \param{int }{nOldSel = wxNOT\_FOUND}}
+
+\wxheading{See also}
+
+\helpref{wxNotebookEvent}{wxnotebookevent}
+
+
+
+\membersection{wxTreebookEvent::GetOldSelection}\label{wxtreebookeventgetoldselection}
+
+\constfunc{int}{GetOldSelection}{\void}
+
+Returns the page that was selected before the change, wxNOT\_FOUND if none was selected.
+
+
+
+\membersection{wxTreebookEvent::GetSelection}\label{wxtreebookeventgetselection}
+
+\constfunc{int}{GetSelection}{\void}
+
+Returns the currently selected page, or wxNOT\_FOUND if none was selected.
+
+\wxheading{See also}
+
+\helpref{wxNotebookEvent::GetSelection}{wxnotebookeventgetselection}
+

docs/latex/wx/treebookevt.inc

@@ -0,0 +1,12 @@
+\wxheading{Event handling}
+
+To process input from a treebook control, use the following event handler macros
+to direct input to member functions that take a \helpref{wxTreebookEvent}{wxtreebookevent} argument.
+
+\twocolwidtha{10cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf EVT\_TREEBOOK\_PAGE\_CHANGED(id, func)}}{The page selection was changed. Processes a wxEVT\_COMMAND\_TREEBOOK\_PAGE\_CHANGED event.}
+\twocolitem{{\bf EVT\_TREEBOOK\_PAGE\_CHANGING(id, func)}}{The page selection is about to be changed. Processes a wxEVT\_COMMAND\_TREEBOOK\_PAGE\_CHANGING event. This event can be \helpref{vetoed}{wxnotifyeventveto}.}
+\twocolitem{{\bf EVT\_TREEBOOK\_NODE\_COLLAPSED(id, func)}}{The page node is going to be collapsed. Processes a wxEVT\_COMMAND\_TREEBOOK\_NODE\_COLLAPSED event.}
+\twocolitem{{\bf EVT\_TREEBOOK\_NODE\_EXPANDED(id, func)}}{The page node is going to be expanded. Processes a wxEVT\_COMMAND\_TREEBOOK\_NODE\_EXPANDED event.}
+\end{twocollist}

docs/latex/wx/tsamples.tex

@@ -369,9 +369,9 @@ It replaces the old dynamic sample.
 
 This samples shows \helpref{wxBookCtrl}{wxbookctrloverview} family of controls.
 Although initially it was written to demonstrate \helpref{wxNotebook}{wxnotebook}
-only, it can now be also used to see \helpref{wxListbook}{wxlistbook} and
-\helpref{wxChoicebook}{wxchoicebook} in action. Test each of the controls, their
-orientation, images and pages using commands through menu.
+only, it can now be also used to see \helpref{wxListbook}{wxlistbook},
+\helpref{wxChoicebook}{wxchoicebook} and \helpref{wxTreebook}{wxtreebook} in action.
+Test each of the controls, their orientation, images and pages using commands through menu.