interface/treebook.h

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