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