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