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