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