docs/latex/wx/treebook.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        treebook.tex
   3 %% Purpose:     wxTreebook documentation
   4 %% Author:      Evgeniy Tarassov
   5 %% Modified by:
   6 %% Created:     2005-10-04
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2005 Vadim Zeitlin <vadim@wxwindows.org>
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxTreebook}}\label{wxtreebook}
  13
  14 This class is an extension of the Notebook class that allows a tree structured
  15 set of pages to be shown in a control.
  16 A classic example is a netscape preferences dialog that shows a tree
  17 of preference sections on the left and select section page on the right.
  18
  19 To use the class simply create it and populate with pages using
  20 \helpref{InsertPage}{wxtreebookinsertpage},
  21 \helpref{InsertSubPage}{wxtreebookinsertsubpage},
  22 \helpref{AddPage}{wxtreebookaddpage},
  23 \helpref{AddSubPage}{wxtreebookaddsubpage}.
  24
  25 If your tree is no more than $1$ level in depth then you could
  26 simply use \helpref{AddPage}{wxtreebookaddpage} and
  27 \helpref{AddSubPage}{wxtreebookaddsubpage} to sequentially populate your tree
  28 by adding at every step a page or a subpage to the end of the tree.
  29
  30
  31 \wxheading{Derived from}
  32
  33 wxBookCtrlBase (see \helpref{wxBookCtrl overview}{wxbookctrloverview})\\
  34 \helpref{wxControl}{wxcontrol}\\
  35 \helpref{wxWindow}{wxwindow}\\
  36 \helpref{wxEvtHandler}{wxevthandler}\\
  37 \helpref{wxObject}{wxobject}
  38
  39
  40 \wxheading{Include files}
  41
  42 <wx/treebook.h>
  43
  44 \input treebookevt.inc
  45
  46
  47 \wxheading{See also}
  48
  49 \helpref{wxNotebook}{wxnotebook}, \helpref{wxTreebookEvent}{wxtreebookevent}, \helpref{wxImageList}{wximagelist}, \helpref{notebook sample}{samplenotebook}
  50
  51
  52
  53 \latexignore{\rtfignore{\wxheading{Members}}}
  54
  55
  56 \membersection{wxTreebook::wxTreebook}\label{wxtreebookwxtreebook}
  57
  58 \func{}{wxTreebook}{\void}
  59
  60 Default constructor.
  61
  62
  63 \func{}{wxTreebook}{
  64     \param{wxWindow* }{parent},
  65     \param{wxWindowID }{id},
  66     \param{const wxPoint\& }{pos = wxDefaultPosition},
  67     \param{const wxSize\& }{size = wxDefaultSize},
  68     \param{long }{style = wxTBK\_DEFAULT},
  69     \param{const wxString\& }{name = wxEmptyString}}
  70
  71 Creates an empty TreeBook control.
  72
  73 \wxheading{Parameters}
  74
  75 \docparam{parent}{The parent window. Must be non-NULL.}
  76
  77 \docparam{id}{The window identifier.}
  78
  79 \docparam{pos}{The window position.}
  80
  81 \docparam{size}{The window size.}
  82
  83 \docparam{style}{The window style. See \helpref{wxNotebook}{wxnotebook}.}
  84
  85 \docparam{name}{The name of the control (used only under Motif).}
  86
  87
  88
  89 \membersection{wxTreebook::\destruct{wxTreebook}}\label{wxtreebookdtor}
  90
  91 \func{}{\destruct{wxTreebook}}{\void}
  92
  93 Destroys the wxTreebook object.
  94
  95 Also deletes all the pages owned by the control (inserted previously into it).
  96
  97
  98
  99 \membersection{wxTreebook::AddPage}\label{wxtreebookaddpage}
 100
 101 \func{bool}{AddPage}{
 102     \param{wxWindow* }{page},
 103     \param{const wxString\& }{text},
 104     \param{bool }{bSelect = false},
 105     \param{int }{imageId = wxNOT\_FOUND}}
 106
 107 Adds a new page. The page is placed at the topmost level after all other pages.
 108 \NULL could be specified for page to create an empty page.
 109
 110
 111
 112 \membersection{wxTreebook::AddSubPage}\label{wxtreebookaddsubpage}
 113
 114 \func{bool}{AddSubPage}{\param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}
 115
 116 Adds a new child-page to the last top-level page.
 117 \NULL could be specified for page to create an empty page.
 118
 119
 120
 121 \membersection{wxTreebook::AssignImageList}\label{wxtreebookassignimagelist}
 122
 123 \func{void}{AssignImageList}{\param{wxImageList* }{imageList}}
 124
 125 Sets the image list for the page control and takes ownership of the list.
 126
 127 \wxheading{See also}
 128
 129 \helpref{wxImageList}{wximagelist}, \helpref{SetImageList}{wxtreebooksetimagelist}
 130
 131
 132
 133 \membersection{wxTreebook::CollapseNode}\label{wxtreebookcollapsenode}
 134
 135 \func{bool}{CollapseNode}{\param{size\_t }{pageId}}
 136
 137 Shortcut for \helpref{ExpandNode}{wxtreebookexpandnode}(pageId, false).
 138
 139
 140
 141 \membersection{wxTreebook::Create}\label{wxtreebookcreate}
 142
 143 \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}}
 144
 145 Creates a treebook control. See \helpref{wxTreebook::wxTreebook}{wxtreebookwxtreebook} for the description of the parameters.
 146
 147
 148
 149 \membersection{wxTreebook::DeleteAllPages}\label{wxtreebookdeleteallpages}
 150
 151 \func{bool}{DeleteAllPages}{\void}
 152
 153 Deletes all pages inserted into the treebook. No event is generated.
 154
 155
 156
 157 \membersection{wxTreebook::DeletePage}\label{wxtreebookdeletepage}
 158
 159 \func{bool}{DeletePage}{\param{size\_t }{pagePos}}
 160
 161 Deletes the page at the specified position and all its children. Could trigger page selection change
 162 in a case when selected page is removed. In that case its parent is selected
 163 (or the next page if no parent).
 164
 165
 166
 167 \membersection{wxTreebook::ExpandNode}\label{wxtreebookexpandnode}
 168
 169 \func{bool}{ExpandNode}{\param{size\_t }{pageId}, \param{bool }{expand = true}}
 170
 171 Expands (collapses) the pageId node. Returns the previous state.
 172 May generate page changing events (if selected page
 173 is under the collapsed branch, then its parent is autoselected).
 174
 175
 176 \membersection{wxTreebook::GetPageImage}\label{wxtreebookgetpageimage}
 177
 178 \constfunc{int}{GetPageImage}{\param{size\_t }{n}}
 179
 180 Returns the image index for the given page.
 181
 182
 183 \membersection{wxTreebook::GetPageParent}\label{wxtreebookgetpageparent}
 184
 185 \constfunc{int}{GetPageParent}{\param{size\_t }{page}}
 186
 187 Returns the parent page of the given one or \texttt{wxNOT\_FOUND} if this is a
 188 top-level page.
 189
 190
 191 \membersection{wxTreebook::GetPageText}\label{wxtreebookgetpagetext}
 192
 193 \constfunc{wxString}{GetPageText}{\param{size\_t }{n}}
 194
 195 Returns the string for the given page.
 196
 197
 198
 199 \membersection{wxTreebook::GetSelection}\label{wxtreebookgetselection}
 200
 201 \constfunc{int}{GetSelection}{\void}
 202
 203 Returns the currently selected page, or wxNOT\_FOUND if none was selected.
 204
 205 Note that this method may return either the previously or newly selected page
 206 when called from the EVT\_TREEBOOK\_PAGE\_CHANGED handler
 207 depending on the platform and so wxTreebookEvent::GetSelection should be used instead in this case.
 208
 209
 210
 211 \membersection{wxTreebook::InsertPage}\label{wxtreebookinsertpage}
 212
 213 \func{bool}{InsertPage}{\param{size\_t }{pagePos}, \param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}
 214
 215 Inserts a new page just before the page indicated by pagePos.
 216 The new page is placed before pagePos page and on the same level.
 217 \NULL could be specified for page to create an empty page.
 218
 219
 220 \membersection{wxTreebook::InsertSubPage}\label{wxtreebookinsertsubpage}
 221
 222 \func{bool}{InsertSubPage}{\param{size\_t }{pagePos}, \param{wxWindow* }{page}, \param{const wxString\& }{text}, \param{bool }{bSelect = false}, \param{int }{imageId = wxNOT\_FOUND}}
 223
 224 Inserts a sub page under the specified page.
 225
 226 \NULL could be specified for page to create an empty page.
 227
 228
 229 \membersection{wxTreebook::IsNodeExpanded}\label{wxtreebookisnodeexpanded}
 230
 231 \constfunc{bool}{IsNodeExpanded}{\param{size\_t }{pageId}}
 232
 233 Gets the pagePos page state -- whether it is expanded or collapsed
 234
 235
 236
 237 \membersection{wxTreebook::SetImageList}\label{wxtreebooksetimagelist}
 238
 239 \func{void}{SetImageList}{\param{wxImageList* }{imageList}}
 240
 241 Sets the image list for the page control. It does not take ownership of the image list, you must delete it yourself.
 242
 243 \wxheading{See also}
 244
 245 \helpref{wxImageList}{wximagelist}, \helpref{AssignImageList}{wxtreebookassignimagelist}
 246
 247
 248
 249 \membersection{wxTreebook::SetPageImage}\label{wxtreebooksetpageimage}
 250
 251 \func{bool}{SetPageImage}{\param{size\_t }{page}, \param{int }{imageId}}
 252
 253 Sets the image index for the given page. ImageId is an index into the image list
 254 which was set with \helpref{SetImageList}{wxtreebooksetimagelist}.
 255
 256
 257
 258 \membersection{wxTreebook::SetPageText}\label{wxtreebooksetpagetext}
 259
 260 \func{bool}{SetPageText}{\param{size\_t }{page}, \param{const wxString\& }{text}}
 261
 262 Sets the text for the given page.
 263
 264
 265
 266 \membersection{wxTreebook::SetSelection}\label{wxtreebooksetselection}
 267
 268 \func{int}{SetSelection}{\param{size\_t }{n}}
 269
 270 Sets the selection for the given page, returning the previous selection.
 271
 272 The call to this function generates the page changing events.
 273
 274 This function is deprecated and should not be used in new code. Please use the
 275 \helpref{ChangeSelection}{wxtreebookchangeselection} function instead.
 276
 277 \wxheading{See also}
 278
 279 \helpref{wxTreebook::GetSelection}{wxtreebookgetselection}
 280
 281
 282
 283 \membersection{wxTreebook::ChangeSelection}\label{wxtreebookchangeselection}
 284
 285 \func{int}{ChangeSelection}{\param{size\_t}{ page}}
 286
 287 Changes the selection for the given page, returning the previous selection.
 288
 289 The call to this function \emph{does not} generate the page changing events.
 290 This is the only difference with \helpref{SetSelection}{wxtreebooksetselection}.
 291 See \helpref{this topic}{progevent} for more info.
 292