interface/treebook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treebook.h
   3 // Purpose:     interface of wxTreebookEvent
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTreebookEvent
  11     @wxheader{treebook.h}
  12
  13     This class represents the events generated by a treebook control: currently,
  14     there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and
  15     EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as
  16     wxNotebookEvent.
  17
  18     The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED()
  19     are triggered when page node in the tree control is collapsed/expanded. The
  20     page index could be retreived by calling GetSelection().
  21
  22     @beginEventTable{wxTreebookEvent}
  23     @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
  24         The page selection was changed. Processes a @c
  25         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
  26     @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
  27         The page selection is about to be changed. Processes a @c
  28         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
  29         wxNotifyEvent::Veto() "vetoed".
  30     @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
  31         The page node is going to be collapsed. Processes a @c
  32         wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
  33     @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
  34         The page node is going to be expanded. Processes a @c
  35         wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
  36     @endEventTable
  37
  38     @library{wxcore}
  39     @category{events}
  40
  41     @see wxTreebook, wxNotebookEvent
  42 */
  43 class wxTreebookEvent : public wxNotifyEvent
  44 {
  45 public:
  46     /**
  47         @see wxNotebookEvent
  48     */
  49     wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0,
  50                     int nSel = wxNOT_FOUND,
  51                     int nOldSel = wxNOT_FOUND);
  52
  53     /**
  54         Returns the page that was selected before the change, @c wxNOT_FOUND if
  55         none was selected.
  56     */
  57     int GetOldSelection() const;
  58
  59     /**
  60         Returns the currently selected page, or @c wxNOT_FOUND if none was
  61         selected.
  62
  63         @see wxNotebookEvent::GetSelection()
  64     */
  65     int GetSelection() const;
  66 };
  67
  68
  69
  70 /**
  71     @class wxTreebook
  72     @wxheader{treebook.h}
  73
  74     This class is an extension of the wxNotebook class that allows a tree
  75     structured set of pages to be shown in a control. A classic example is a
  76     netscape preferences dialog that shows a tree of preference sections on
  77     the left and select section page on the right.
  78
  79     To use the class simply create it and populate with pages using
  80     InsertPage(), InsertSubPage(), AddPage(), AddSubPage().
  81
  82     If your tree is no more than 1 level in depth then you could simply use
  83     AddPage() and AddSubPage() to sequentially populate your tree by adding at
  84     every step a page or a subpage to the end of the tree.
  85
  86     @beginEventTable{wxTreebookEvent}
  87     @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)}
  88         The page selection was changed. Processes a @c
  89         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event.
  90     @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)}
  91         The page selection is about to be changed. Processes a @c
  92         wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref
  93         wxNotifyEvent::Veto() "vetoed".
  94     @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)}
  95         The page node is going to be collapsed. Processes a @c
  96         wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event.
  97     @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)}
  98         The page node is going to be expanded. Processes a @c
  99         wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event.
 100     @endEventTable
 101
 102     @library{wxcore}
 103     @category{miscwnd}
 104
 105     @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList,
 106          @ref overview_bookctrl, @ref page_samples_notebook
 107 */
 108 class wxTreebook : public wxBookCtrlBase
 109 {
 110 public:
 111     /**
 112         Default constructor.
 113     */
 114     wxTreebook();
 115
 116     /**
 117         Creates an empty wxTreebook.
 118
 119         @param parent
 120             The parent window. Must be non-@NULL.
 121         @param id
 122             The window identifier.
 123         @param pos
 124             The window position.
 125         @param size
 126             The window size.
 127         @param style
 128             The window style. See wxNotebook.
 129         @param name
 130             The name of the control (used only under Motif).
 131     */
 132     wxTreebook(wxWindow* parent, wxWindowID id,
 133                const wxPoint& pos = wxDefaultPosition,
 134                const wxSize& size = wxDefaultSize,
 135                long style = wxBK_DEFAULT,
 136                const wxString& name = wxEmptyString);
 137
 138     /**
 139         Destroys the wxTreebook object. Also deletes all the pages owned by the
 140         control (inserted previously into it).
 141     */
 142     ~wxTreebook();
 143
 144     /**
 145         Adds a new page. The page is placed at the topmost level after all other
 146         pages. @NULL could be specified for page to create an empty page.
 147     */
 148     bool AddPage(wxWindow* page, const wxString& text,
 149                  bool bSelect = false,
 150                  int imageId = wxNOT_FOUND);
 151
 152     /**
 153         Adds a new child-page to the last top-level page. @NULL could be
 154         specified for page to create an empty page.
 155     */
 156     bool AddSubPage(wxWindow* page, const wxString& text,
 157                     bool bSelect = false,
 158                     int imageId = wxNOT_FOUND);
 159
 160     /**
 161         Sets the image list for the page control and takes ownership of the
 162         list.
 163
 164         @see wxImageList, SetImageList()
 165     */
 166     void AssignImageList(wxImageList* imageList);
 167
 168     /**
 169         Changes the selection for the given page, returning the previous
 170         selection.
 171
 172         The call to this function does not generate the page changing events.
 173         This is the only difference with SetSelection(). See
 174         @ref overview_eventhandling_prog for more info.
 175     */
 176     int ChangeSelection(size_t page);
 177
 178     /**
 179         Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId,
 180         @false ).
 181     */
 182     bool CollapseNode(size_t pageId);
 183
 184     /**
 185         Creates a treebook control. See wxTreebook::wxTreebook() for the
 186         description of the parameters.
 187     */
 188     bool Create(wxWindow* parent, wxWindowID id,
 189                 const wxPoint& pos = wxDefaultPosition,
 190                 const wxSize& size = wxDefaultSize,
 191                 long style = wxBK_DEFAULT,
 192                 const wxString& name = wxEmptyString);
 193
 194     /**
 195         Deletes all pages inserted into the treebook. No event is generated.
 196     */
 197     bool DeleteAllPages();
 198
 199     /**
 200         Deletes the page at the specified position and all its children. Could
 201         trigger page selection change in a case when selected page is removed.
 202         In that case its parent is selected (or the next page if no parent).
 203     */
 204     bool DeletePage(size_t pagePos);
 205
 206     /**
 207         Expands (collapses) the @a pageId node. Returns the previous state. May
 208         generate page changing events (if selected page is under the collapsed
 209         branch, then its parent is autoselected).
 210     */
 211     bool ExpandNode(size_t pageId, bool expand = true);
 212
 213     /**
 214         Returns the image index for the given page.
 215     */
 216     int GetPageImage(size_t n) const;
 217
 218     /**
 219         Returns the parent page of the given one or @c wxNOT_FOUND if this is a
 220         top-level page.
 221     */
 222     int GetPageParent(size_t page) const;
 223
 224     /**
 225         Returns the string for the given page.
 226     */
 227     wxString GetPageText(size_t n) const;
 228
 229     /**
 230         Returns the currently selected page, or @c wxNOT_FOUND if none was
 231         selected.
 232
 233         @note This method may return either the previously or newly selected
 234             page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler
 235             depending on the platform and so wxTreebookEvent::GetSelection()
 236             should be used instead in this case.
 237     */
 238     int GetSelection() const;
 239
 240     /**
 241         Inserts a new page just before the page indicated by @a pagePos. The new
 242         page is placed before @a pagePos page and on the same level. @NULL could
 243         be specified for page to create an empty page.
 244     */
 245     bool InsertPage(size_t pagePos, wxWindow* page,
 246                     const wxString& text,
 247                     bool bSelect = false,
 248                     int imageId = wxNOT_FOUND);
 249
 250     /**
 251         Inserts a sub page under the specified page.
 252
 253         @NULL could be specified for page to create an empty page.
 254     */
 255     bool InsertSubPage(size_t pagePos, wxWindow* page,
 256                        const wxString& text,
 257                        bool bSelect = false,
 258                        int imageId = wxNOT_FOUND);
 259
 260     /**
 261         Returns @true if the page represented by @a pageId is expanded.
 262     */
 263     bool IsNodeExpanded(size_t pageId) const;
 264
 265     /**
 266         Sets the image list for the page control. It does not take ownership of
 267         the image list, you must delete it yourself.
 268
 269         @see wxImageList, AssignImageList()
 270     */
 271     void SetImageList(wxImageList* imageList);
 272
 273     /**
 274         Sets the image index for the given @a page. @a imageId is an index into
 275         the image list which was set with SetImageList().
 276     */
 277     bool SetPageImage(size_t page, int imageId);
 278
 279     /**
 280         Sets the @a text for the given @a page.
 281     */
 282     bool SetPageText(size_t page, const wxString& text);
 283
 284     /**
 285         @deprecated Please use ChangeSelection() instead.
 286
 287         Sets the selection for the given page, returning the previous selection.
 288
 289         The call to this function generates page changing events.
 290
 291         @see GetSelection(), ChangeSelection()
 292     */
 293     int SetSelection(size_t n);
 294 };
 295