]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/treectrl.h
Only show the default close button in wxInfoBar if there are no others.
[wxWidgets.git] / interface / wx / treectrl.h
index 782a36837e9e9f71804e13f252d79ed58bc6ce65..6897303738d1e5fb885438b07174e3818cdef957 100644 (file)
@@ -9,7 +9,6 @@
 
 /**
     @class wxTreeCtrl
-    @wxheader{treectrl.h}
 
     A tree control presents information as a hierarchy, with items that may be
     expanded to show further items. Items in a tree control are referenced by
         for a particular toolkit.
     @endStyleTable
 
+    @beginEventEmissionTable{wxTreeEvent}
+    @event{EVT_TREE_BEGIN_DRAG(id, func)}
+          Begin dragging with the left mouse button.
+          If you want to enable left-dragging you need to intercept this event
+          and explicitely call wxTreeEvent::Allow(), as it's vetoed by default.
+    @event{EVT_TREE_BEGIN_RDRAG(id, func)}
+          Begin dragging with the right mouse button.
+          If you want to enable right-dragging you need to intercept this event
+          and explicitely call wxTreeEvent::Allow(), as it's vetoed by default.
+    @event{EVT_TREE_END_DRAG(id, func)}
+          End dragging with the left or right mouse button.
+    @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
+          Begin editing a label. This can be prevented by calling Veto().
+    @event{EVT_TREE_END_LABEL_EDIT(id, func)}
+          Finish editing a label. This can be prevented by calling Veto().
+    @event{EVT_TREE_DELETE_ITEM(id, func)}
+          An item was deleted.
+    @event{EVT_TREE_GET_INFO(id, func)}
+          Request information from the application.
+    @event{EVT_TREE_SET_INFO(id, func)}
+          Information is being supplied.
+    @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
+          The item has been activated, i.e. chosen by double clicking it with
+          mouse or from keyboard.
+    @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
+          The item has been collapsed.
+    @event{EVT_TREE_ITEM_COLLAPSING(id, func)}
+          The item is being collapsed. This can be prevented by calling Veto().
+    @event{EVT_TREE_ITEM_EXPANDED(id, func)}
+          The item has been expanded.
+    @event{EVT_TREE_ITEM_EXPANDING(id, func)}
+          The item is being expanded. This can be prevented by calling Veto().
+    @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)}
+          The user has clicked the item with the right mouse button.
+    @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)}
+          The user has clicked the item with the middle mouse button.
+    @event{EVT_TREE_SEL_CHANGED(id, func)}
+          Selection has changed.
+    @event{EVT_TREE_SEL_CHANGING(id, func)}
+          Selection is changing. This can be prevented by calling Veto().
+    @event{EVT_TREE_KEY_DOWN(id, func)}
+          A key has been pressed.
+    @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
+          The opportunity to set the item tooltip is being given to the application
+          (call wxTreeEvent::SetToolTip). Windows only.
+    @event{EVT_TREE_ITEM_MENU(id, func)}
+          The context menu for the selected item has been requested, either by a
+          right click or by using the menu key.
+    @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
+          The state image has been clicked. Windows only.
+    @endEventTable
+
+
     See also @ref overview_windowstyles.
 
     @b Win32 @b notes:
 
     @library{wxcore}
     @category{ctrl}
-    <!-- @appearance{treectrl.png} -->
+    @appearance{treectrl.png}
 
-    @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox,
-         wxListCtrl, wxImageList
+    @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl,
+         wxListBox, wxListCtrl, wxImageList
 */
 class wxTreeCtrl : public wxControl
 {
@@ -98,9 +150,10 @@ public:
             Window identifier. The value @c wxID_ANY indicates a default value.
         @param pos
             Window position.
+            If ::wxDefaultPosition is specified then a default position is chosen.
         @param size
-            Window size. If wxDefaultSize is specified then the window is sized
-            appropriately.
+            Window size. 
+            If ::wxDefaultSize is specified then the window is sized appropriately.
         @param style
             Window style. See wxTreeCtrl.
         @param validator
@@ -110,18 +163,18 @@ public:
 
         @see Create(), wxValidator
     */
-    wxTreeCtrl(wxWindow* parent, wxWindowID id,
+    wxTreeCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
-               long style = wxTR_HAS_BUTTONS,
+               long style = wxTR_DEFAULT_STYLE,
                const wxValidator& validator = wxDefaultValidator,
-               const wxString& name = "treeCtrl");
+               const wxString& name = wxTreeCtrlNameStr);
 
 
     /**
         Destructor, destroying the tree control.
     */
-    ~wxTreeCtrl();
+    virtual ~wxTreeCtrl();
 
     /**
         Adds the root node to the tree, returning the new item.
@@ -131,9 +184,9 @@ public:
         items, respectively. If @a image -1 and @a selImage is -1, the same
         image is used for both selected and unselected items.
     */
-    wxTreeItemId AddRoot(const wxString& text, int image = -1,
-                         int selImage = -1,
-                         wxTreeItemData* data = NULL);
+    virtual wxTreeItemId AddRoot(const wxString& text, int image = -1,
+                                 int selImage = -1,
+                                 wxTreeItemData* data = NULL);
 
     /**
         Appends an item to the end of the branch identified by @a parent, return
@@ -186,7 +239,7 @@ public:
     /**
         Collapses the given item.
     */
-    void Collapse(const wxTreeItemId& item);
+    virtual void Collapse(const wxTreeItemId& item);
 
     /**
         Collapses the root item.
@@ -205,33 +258,33 @@ public:
     /**
         Collapses the given item and removes all children.
     */
-    void CollapseAndReset(const wxTreeItemId& item);
+    virtual void CollapseAndReset(const wxTreeItemId& item);
 
     /**
-        Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further
-        details.
+        Creates the tree control.
+        See wxTreeCtrl::wxTreeCtrl() for further details.
     */
-    bool Create(wxWindow* parent, wxWindowID id,
+    bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
-                long style = wxTR_HAS_BUTTONS,
+                long style = wxTR_DEFAULT_STYLE,
                 const wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "treeCtrl");
+                const wxString& name = wxTreeCtrlNameStr);
 
     /**
-        Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be
+        Deletes the specified item. A @c EVT_TREE_DELETE_ITEM event will be
         generated.
 
         This function may cause a subsequent call to GetNextChild() to fail.
     */
-    void Delete(const wxTreeItemId& item);
+    virtual void Delete(const wxTreeItemId& item);
 
     /**
         Deletes all items in the control. Note that this may not generate
-        EVT_TREE_DELETE_ITEM() events under some Windows versions although
+        @c EVT_TREE_DELETE_ITEM events under some Windows versions although
         normally such event is generated for each removed item.
     */
-    void DeleteAllItems();
+    virtual void DeleteAllItems();
 
     /**
         Deletes all children of the given item (but not the item itself). Note
@@ -240,20 +293,21 @@ public:
         If you have called SetItemHasChildren(), you may need to call it again
         since DeleteChildren() does not automatically clear the setting.
     */
-    void DeleteChildren(const wxTreeItemId& item);
+    virtual void DeleteChildren(const wxTreeItemId& item);
 
     /**
         Starts editing the label of the given @a item. This function generates a
-        EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text
+        @c EVT_TREE_BEGIN_LABEL_EDIT event which can be vetoed so that no text
         control will appear for in-place editing.
 
         If the user changed the label (i.e. s/he does not press ESC or leave the
-        text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be
+        text control without changes, a @c EVT_TREE_END_LABEL_EDIT event will be
         sent which can be vetoed as well.
 
         @see EndEditLabel(), wxTreeEvent
     */
-    void EditLabel(const wxTreeItemId& item);
+    virtual wxTextCtrl *EditLabel(const wxTreeItemId& item,
+                                  wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl));
 
     /**
         Ends label editing. If @a cancelEdit is @true, the edit will be
@@ -264,17 +318,17 @@ public:
 
         @see EditLabel()
     */
-    void EndEditLabel(bool cancelEdit);
+    virtual void EndEditLabel(const wxTreeItemId& item, bool discardChanges = false);
 
     /**
         Scrolls and/or expands items to ensure that the given item is visible.
     */
-    void EnsureVisible(const wxTreeItemId& item);
+    virtual void EnsureVisible(const wxTreeItemId& item);
 
     /**
         Expands the given item.
     */
-    void Expand(const wxTreeItemId& item);
+    virtual void Expand(const wxTreeItemId& item);
 
     /**
         Expands all items in the tree.
@@ -305,8 +359,8 @@ public:
         None.
         @endWxPythonOnly
     */
-    bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect,
-                         bool textOnly = false) const;
+    virtual bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect,
+                                 bool textOnly = false) const;
 
     /**
         Returns the buttons image list (from which application-defined button
@@ -321,13 +375,13 @@ public:
         returns the total number of descendants, otherwise only one level of
         children is counted.
     */
-    unsigned int GetChildrenCount(const wxTreeItemId& item,
-                                  bool recursively = true) const;
+    virtual size_t GetChildrenCount(const wxTreeItemId& item,
+                                    bool recursively = true) const;
 
     /**
         Returns the number of items in the control.
     */
-    unsigned int GetCount() const;
+    virtual unsigned int GetCount() const;
 
     /**
         Returns the edit control being currently used to edit a label. Returns
@@ -335,7 +389,7 @@ public:
 
         @note This is currently only implemented for wxMSW.
     */
-    wxTextCtrl* GetEditControl() const;
+    virtual wxTextCtrl* GetEditControl() const;
 
     /**
         Returns the first child; call GetNextChild() for the next child.
@@ -356,13 +410,22 @@ public:
 
         @see GetNextChild(), GetNextSibling()
     */
-    wxTreeItemId GetFirstChild(const wxTreeItemId& item,
-                               wxTreeItemIdValue& cookie) const;
+    virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item,
+                                       wxTreeItemIdValue& cookie) const;
 
     /**
         Returns the first visible item.
     */
-    wxTreeItemId GetFirstVisibleItem() const;
+    virtual wxTreeItemId GetFirstVisibleItem() const;
+
+    /**
+        Returns the item last clicked or otherwise selected.
+        Unlike GetSelection(), it can be used whether or not
+        the control has the @c wxTR_MULTIPLE style.
+        
+        @since 2.9.1
+    */
+    virtual wxTreeItemId GetFocusedItem() const;
 
     /**
         Returns the normal image list.
@@ -372,12 +435,12 @@ public:
     /**
         Returns the current tree control indentation.
     */
-    int GetIndent() const;
+    virtual unsigned int GetIndent() const;
 
     /**
         Returns the background colour of the item.
     */
-    wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
+    virtual wxColour GetItemBackgroundColour(const wxTreeItemId& item) const;
 
     /**
         Returns the tree item data associated with the item.
@@ -390,12 +453,12 @@ public:
             wxTreeItemData for the given item Id.
         @endWxPythonOnly
     */
-    wxTreeItemData* GetItemData(const wxTreeItemId& item) const;
+    virtual wxTreeItemData* GetItemData(const wxTreeItemId& item) const;
 
     /**
         Returns the font of the item label.
     */
-    wxFont GetItemFont(const wxTreeItemId& item) const;
+    virtual wxFont GetItemFont(const wxTreeItemId& item) const;
 
     /**
         Gets the specified item image. The value of @a which may be:
@@ -409,20 +472,13 @@ public:
         - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
             (which is shown when an expanded item is currently selected).
     */
-    int GetItemImage(const wxTreeItemId& item,
-                     wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
+    virtual int GetItemImage(const wxTreeItemId& item,
+                             wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 
     /**
         Returns the item's parent.
     */
-    wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
-
-    /**
-        Gets the selected item image (this function is obsolete, use @ref
-        GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected)
-        instead).
-    */
-    int GetItemSelectedImage(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
 
     /**
         Gets the specified item state.
@@ -432,12 +488,12 @@ public:
     /**
         Returns the item label.
     */
-    wxString GetItemText(const wxTreeItemId& item) const;
+    virtual wxString GetItemText(const wxTreeItemId& item) const;
 
     /**
         Returns the colour of the item label.
     */
-    wxColour GetItemTextColour(const wxTreeItemId& item) const;
+    virtual wxColour GetItemTextColour(const wxTreeItemId& item) const;
 
     /**
         Returns the last child of the item (or an invalid tree item if this item
@@ -445,7 +501,7 @@ public:
 
         @see GetFirstChild(), GetNextSibling(), GetLastChild()
     */
-    wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 
     /**
         Returns the next child; call GetFirstChild() for the first child. For
@@ -464,8 +520,8 @@ public:
 
         @see GetFirstChild()
     */
-    wxTreeItemId GetNextChild(const wxTreeItemId& item,
-                              wxTreeItemIdValue& cookie) const;
+    virtual wxTreeItemId GetNextChild(const wxTreeItemId& item,
+                                      wxTreeItemIdValue& cookie) const;
 
     /**
         Returns the next sibling of the specified item; call GetPrevSibling()
@@ -475,7 +531,7 @@ public:
 
         @see GetPrevSibling()
     */
-    wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 
     /**
         Returns the next visible item or an invalid item if this item is the
@@ -483,7 +539,7 @@ public:
 
         @note The @a item itself must be visible.
     */
-    wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 
     /**
         Returns the previous sibling of the specified item; call
@@ -493,7 +549,7 @@ public:
 
         @see GetNextSibling()
     */
-    wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 
     /**
         Returns the previous visible item or an invalid item if this item is the
@@ -501,7 +557,7 @@ public:
 
         @note The @a item itself must be visible.
     */
-    wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
+    virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 
     /**
         Returns @true if the control will use a quick calculation for the best
@@ -514,14 +570,15 @@ public:
     /**
         Returns the root item for the tree control.
     */
-    wxTreeItemId GetRootItem() const;
+    virtual wxTreeItemId GetRootItem() const;
 
     /**
         Returns the selection, or an invalid item if there is no selection. This
         function only works with the controls without @c wxTR_MULTIPLE style,
-        use GetSelections() for the controls which do have this style.
+        use GetSelections() for the controls which do have this style 
+        or, if a single item is wanted, use GetFocusedItem().
     */
-    wxTreeItemId GetSelection() const;
+    virtual wxTreeItemId GetSelection() const;
 
     /**
         Fills the array of tree items passed in with the currently selected
@@ -535,7 +592,7 @@ public:
         Python list of @ref wxTreeItemId "wxTreeItemId"s.
         @endWxPythonOnly
     */
-    unsigned int GetSelections(wxArrayTreeItemIds& selection) const;
+    virtual size_t GetSelections(wxArrayTreeItemIds& selection) const;
 
     /**
         Returns the state image list (from which application-defined state
@@ -553,13 +610,11 @@ public:
         - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item.
         - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item.
         - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item.
-        - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an
-            item.
-        - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with
-            an item.
+        - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an item.
+        - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
         - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item.
         - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view
-            item that is in a user-defined state.
+          item that is in a user-defined state.
         - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
         - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
 
@@ -611,7 +666,7 @@ public:
 
         @see SetItemBold()
     */
-    bool IsBold(const wxTreeItemId& item) const;
+    virtual bool IsBold(const wxTreeItemId& item) const;
 
     /**
         Returns @true if the control is empty (i.e. has no items, even no root
@@ -623,22 +678,22 @@ public:
         Returns @true if the item is expanded (only makes sense if it has
         children).
     */
-    bool IsExpanded(const wxTreeItemId& item) const;
+    virtual bool IsExpanded(const wxTreeItemId& item) const;
 
     /**
         Returns @true if the item is selected.
     */
-    bool IsSelected(const wxTreeItemId& item) const;
+    virtual bool IsSelected(const wxTreeItemId& item) const;
 
     /**
         Returns @true if the item is visible on the screen.
     */
-    bool IsVisible(const wxTreeItemId& item) const;
+    virtual bool IsVisible(const wxTreeItemId& item) const;
 
     /**
         Returns @true if the item has children.
     */
-    bool ItemHasChildren(const wxTreeItemId& item) const;
+    virtual bool ItemHasChildren(const wxTreeItemId& item) const;
 
     /**
         Override this function in the derived class to change the sort order of
@@ -654,8 +709,8 @@ public:
 
         @see SortChildren()
     */
-    int OnCompareItems(const wxTreeItemId& item1,
-                       const wxTreeItemId& item2);
+    virtual int OnCompareItems(const wxTreeItemId& item1,
+                               const wxTreeItemId& item2);
 
     /**
         Appends an item as the first child of @a parent, return a new item id.
@@ -674,14 +729,14 @@ public:
     /**
         Scrolls the specified item into view.
     */
-    void ScrollTo(const wxTreeItemId& item);
+    virtual void ScrollTo(const wxTreeItemId& item);
 
     /**
         Selects the given item. In multiple selection controls, can be also used
         to deselect a currently selected item if the value of @a select is
         @false.
     */
-    void SelectItem(const wxTreeItemId& item, bool select = true);
+    virtual void SelectItem(const wxTreeItemId& item, bool select = true);
 
     /**
         Sets the buttons image list (from which application-defined button
@@ -706,18 +761,18 @@ public:
 
         @see AssignImageList().
     */
-    void SetImageList(wxImageList* imageList);
+    virtual void SetImageList(wxImageList* imageList);
 
     /**
         Sets the indentation for the tree control.
     */
-    void SetIndent(int indent);
+    virtual void SetIndent(unsigned int indent);
 
     /**
         Sets the colour of the item's background.
     */
-    void SetItemBackgroundColour(const wxTreeItemId& item,
-                                 const wxColour& col);
+    virtual void SetItemBackgroundColour(const wxTreeItemId& item,
+                                         const wxColour& col);
 
     /**
         Makes item appear in bold font if @a bold parameter is @true or resets
@@ -725,18 +780,23 @@ public:
 
         @see IsBold()
     */
-    void SetItemBold(const wxTreeItemId& item, bool bold = true);
+    virtual void SetItemBold(const wxTreeItemId& item, bool bold = true);
 
     /**
         Sets the item client data.
 
+        Notice that the client data previously associated with the @a item (if
+        any) is @em not freed by this function and so calling this function
+        multiple times for the same item will result in memory leaks unless you
+        delete the old item data pointer yourself.
+
         @beginWxPythonOnly
         - @b SetPyData( @a item, @c obj): Associate the given Python Object with
             the wxTreeItemData for the given item Id.
         @endWxPythonOnly
 
     */
-    void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
+    virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData* data);
 
 
     /**
@@ -745,8 +805,8 @@ public:
         (as opposed to a DnD operation within the tree control, which already
         is implemented internally).
     */
-    void SetItemDropHighlight(const wxTreeItemId& item,
-                              bool highlight = true);
+    virtual void SetItemDropHighlight(const wxTreeItemId& item,
+                                      bool highlight = true);
 
     /**
         Sets the item's font. All items in the tree should have the same height
@@ -755,7 +815,7 @@ public:
 
         @see SetItemBold()
     */
-    void SetItemFont(const wxTreeItemId& item, const wxFont& font);
+    virtual void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 
     /**
         Force appearance of the button next to the item. This is useful to
@@ -763,22 +823,15 @@ public:
         but instead adding them only when needed, thus minimizing memory
         usage and loading time.
     */
-    void SetItemHasChildren(const wxTreeItemId& item,
-                            bool hasChildren = true);
+    virtual void SetItemHasChildren(const wxTreeItemId& item,
+                                    bool hasChildren = true);
 
     /**
         Sets the specified item's image. See GetItemImage() for the description
         of the @a which parameter.
     */
-    void SetItemImage(const wxTreeItemId& item, int image,
-                      wxTreeItemIcon which = wxTreeItemIcon_Normal);
-
-    /**
-        Sets the selected item image (this function is obsolete, use @ref
-        SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected )
-        instead).
-    */
-    void SetItemSelectedImage(const wxTreeItemId& item, int selImage);
+    virtual void SetItemImage(const wxTreeItemId& item, int image,
+                              wxTreeItemIcon which = wxTreeItemIcon_Normal);
 
     /**
         Sets the specified item state. The value of @a state may be:
@@ -792,13 +845,13 @@ public:
     /**
         Sets the item label.
     */
-    void SetItemText(const wxTreeItemId& item, const wxString& text);
+    virtual void SetItemText(const wxTreeItemId& item, const wxString& text);
 
     /**
         Sets the colour of the item's text.
     */
-    void SetItemTextColour(const wxTreeItemId& item,
-                           const wxColour& col);
+    virtual void SetItemTextColour(const wxTreeItemId& item,
+                                   const wxColour& col);
 
     /**
         If @true is passed, specifies that the control will use a quick
@@ -817,7 +870,7 @@ public:
 
         @see AssignStateImageList().
     */
-    void SetStateImageList(wxImageList* imageList);
+    virtual void SetStateImageList(wxImageList* imageList);
 
     /**
         Sets the mode flags associated with the display of the tree control. The
@@ -834,12 +887,12 @@ public:
 
         @see wxTreeItemData, OnCompareItems()
     */
-    void SortChildren(const wxTreeItemId& item);
+    virtual void SortChildren(const wxTreeItemId& item);
 
     /**
         Toggles the given item between collapsed and expanded states.
     */
-    void Toggle(const wxTreeItemId& item);
+    virtual void Toggle(const wxTreeItemId& item);
 
     /**
         Toggles the given item between selected and unselected states. For
@@ -850,14 +903,14 @@ public:
     /**
         Removes the selection from the currently selected item (if any).
     */
-    void Unselect();
+    virtual void Unselect();
 
     /**
         This function either behaves the same as Unselect() if the control
         doesn't have @c wxTR_MULTIPLE style, or removes the selection from all
         items if it does have this style.
     */
-    void UnselectAll();
+    virtual void UnselectAll();
 
     /**
         Unselects the given item. This works in multiselection controls only.
@@ -869,7 +922,6 @@ public:
 
 /**
     @class wxTreeEvent
-    @wxheader{treectrl.h}
 
     A tree event holds information about events associated with wxTreeCtrl
     objects.
@@ -879,9 +931,15 @@ public:
 
     @beginEventTable{wxTreeEvent}
     @event{EVT_TREE_BEGIN_DRAG(id, func)}
-        Begin dragging with the left mouse button.
+        Begin dragging with the left mouse button. If you want to enable
+        left-dragging you need to intercept this event and explicitely call
+        wxTreeEvent::Allow(), as it's vetoed by default. Also notice that the
+        control must have an associated image list (see SetImageList()) to
+        drag its items under MSW.
     @event{EVT_TREE_BEGIN_RDRAG(id, func)}
-        Begin dragging with the right mouse button.
+        Begin dragging with the right mouse button. If you want to enable
+        right-dragging you need to intercept this event and explicitely call
+        wxTreeEvent::Allow(), as it's vetoed by default.
     @event{EVT_TREE_END_DRAG(id, func)}
         End dragging with the left or right mouse button.
     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}
@@ -936,7 +994,8 @@ public:
     /**
         Constructor, used by wxWidgets itself only.
     */
-    wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree);
+    wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree,
+                const wxTreeItemId& item = wxTreeItemId());
 
     /**
         Returns the item (valid for all events).
@@ -950,18 +1009,18 @@ public:
     int GetKeyCode() const;
 
     /**
-        Returns the key event for EVT_TREE_KEY_DOWN() events.
+        Returns the key event for @c EVT_TREE_KEY_DOWN events.
     */
-    const wxKeyEvent GetKeyEvent() const;
+    const wxKeyEvent& GetKeyEvent() const;
 
     /**
         Returns the label if the event is a begin or end edit label event.
     */
-    const wxString GetLabel() const;
+    const wxString& GetLabel() const;
 
     /**
-        Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and
-        EVT_TREE_ITEM_CHANGED() events).
+        Returns the old item index (valid for @c EVT_TREE_ITEM_CHANGING and
+        @c EVT_TREE_ITEM_CHANGED events).
     */
     wxTreeItemId GetOldItem() const;
 
@@ -977,12 +1036,12 @@ public:
 
     /**
         Returns @true if the label edit was cancelled. This should be called
-        from within an EVT_TREE_END_LABEL_EDIT() handler.
+        from within an @c EVT_TREE_END_LABEL_EDIT handler.
     */
     bool IsEditCancelled() const;
 
     /**
-        Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP()
+        Set the tooltip for the item (valid for @c EVT_TREE_ITEM_GETTOOLTIP
         events). Windows only.
     */
     void SetToolTip(const wxString& tooltip);