Fixed bug: wxPropertyGridInterface::SetPropertyReadOnly() with wxPG_DONT_RECURSE...

[wxWidgets.git] / interface / wx / treectrl.h

diff --git a/interface/wx/treectrl.h b/interface/wx/treectrl.h
index 372576d50835ba4b6d5f9e63f43897ac0a0332ba..dff4440b32e1ed7c48ede901dca46e7a0153a9d7 100644 (file)
--- a/interface/wx/treectrl.h
+++ b/interface/wx/treectrl.h
@@ -60,11 +60,15 @@
         for a particular toolkit.
     @endStyleTable
 
         for a particular toolkit.
     @endStyleTable
 

-    @beginEventTable{wxTreeEvent}
+    @beginEventEmissionTable{wxTreeEvent}

     @event{EVT_TREE_BEGIN_DRAG(id, func)}
           Begin dragging with the left mouse button.
     @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.
     @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)}
     @event{EVT_TREE_END_DRAG(id, func)}
           End dragging with the left or right mouse button.
     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}


@@ -78,7 +82,8 @@
     @event{EVT_TREE_SET_INFO(id, func)}
           Information is being supplied.
     @event{EVT_TREE_ITEM_ACTIVATED(id, func)}
     @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.
+          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)}
     @event{EVT_TREE_ITEM_COLLAPSED(id, func)}
           The item has been collapsed.
     @event{EVT_TREE_ITEM_COLLAPSING(id, func)}


@@ -98,9 +103,11 @@
     @event{EVT_TREE_KEY_DOWN(id, func)}
           A key has been pressed.
     @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)}
     @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.
+          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)}
     @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.
+          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
     @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)}
           The state image has been clicked. Windows only.
     @endEventTable


@@ -121,10 +128,10 @@
 
     @library{wxcore}
     @category{ctrl}
 
     @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
 {
 */
 class wxTreeCtrl : public wxControl
 {


@@ -143,9 +150,10 @@ public:
             Window identifier. The value @c wxID_ANY indicates a default value.
         @param pos
             Window position.
             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
         @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
         @param style
             Window style. See wxTreeCtrl.
         @param validator


@@ -155,12 +163,12 @@ public:
 
         @see Create(), wxValidator
     */
 
         @see Create(), wxValidator
     */

-    wxTreeCtrl(wxWindow* parent, wxWindowID id,
+    wxTreeCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,

                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,

-               long style = wxTR_HAS_BUTTONS,
+               long style = wxTR_DEFAULT_STYLE,

                const wxValidator& validator = wxDefaultValidator,
                const wxValidator& validator = wxDefaultValidator,

-               const wxString& name = "treeCtrl");
+               const wxString& name = wxTreeCtrlNameStr);

 
 
     /**
 
 
     /**


@@ -253,18 +261,18 @@ public:
     virtual 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,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,

-                long style = wxTR_HAS_BUTTONS,
+                long style = wxTR_DEFAULT_STYLE,

                 const wxValidator& validator = wxDefaultValidator,
                 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.
         generated.
 
         This function may cause a subsequent call to GetNextChild() to fail.


@@ -273,7 +281,7 @@ public:
 
     /**
         Deletes all items in the control. Note that this may not generate
 
     /**
         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.
     */
     virtual void DeleteAllItems();
         normally such event is generated for each removed item.
     */
     virtual void DeleteAllItems();


@@ -289,16 +297,17 @@ public:
 
     /**
         Starts editing the label of the given @a item. This function generates a
 
     /**
         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
         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
     */
         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
 
     /**
         Ends label editing. If @a cancelEdit is @true, the edit will be


@@ -309,7 +318,7 @@ public:
 
         @see EditLabel()
     */
 
         @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.
 
     /**
         Scrolls and/or expands items to ensure that the given item is visible.


@@ -350,8 +359,8 @@ public:
         None.
         @endWxPythonOnly
     */
         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
 
     /**
         Returns the buttons image list (from which application-defined button


@@ -366,8 +375,8 @@ public:
         returns the total number of descendants, otherwise only one level of
         children is counted.
     */
         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.
 
     /**
         Returns the number of items in the control.


@@ -401,8 +410,8 @@ public:
 
         @see GetNextChild(), GetNextSibling()
     */
 
         @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.
 
     /**
         Returns the first visible item.


@@ -417,7 +426,7 @@ public:
     /**
         Returns the current tree control indentation.
     */
     /**
         Returns the current tree control indentation.
     */

-    int GetIndent() const;
+    virtual unsigned int GetIndent() const;

 
     /**
         Returns the background colour of the item.
 
     /**
         Returns the background colour of the item.


@@ -454,21 +463,14 @@ public:
         - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image
             (which is shown when an expanded item is currently selected).
     */
         - ::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.
     */
     virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const;
 
 
     /**
         Returns the item's parent.
     */
     virtual 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;
-

     /**
         Gets the specified item state.
     */
     /**
         Gets the specified item state.
     */


@@ -509,8 +511,8 @@ public:
 
         @see GetFirstChild()
     */
 
         @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()
 
     /**
         Returns the next sibling of the specified item; call GetPrevSibling()


@@ -580,7 +582,7 @@ public:
         Python list of @ref wxTreeItemId "wxTreeItemId"s.
         @endWxPythonOnly
     */
         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
 
     /**
         Returns the state image list (from which application-defined state


@@ -598,13 +600,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_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
         - @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.
 
         - @c wxTREE_HITTEST_TOLEFT: To the right of the client area.
         - @c wxTREE_HITTEST_TORIGHT: To the left of the client area.
 


@@ -699,8 +699,8 @@ public:
 
         @see SortChildren()
     */
 
         @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.
 
     /**
         Appends an item as the first child of @a parent, return a new item id.


@@ -756,13 +756,13 @@ public:
     /**
         Sets the indentation for the tree control.
     */
     /**
         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.
     */
 
     /**
         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
 
     /**
         Makes item appear in bold font if @a bold parameter is @true or resets


@@ -775,6 +775,11 @@ public:
     /**
         Sets the item client data.
 
     /**
         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.
         @beginWxPythonOnly
         - @b SetPyData( @a item, @c obj): Associate the given Python Object with
             the wxTreeItemData for the given item Id.


@@ -790,8 +795,8 @@ public:
         (as opposed to a DnD operation within the tree control, which already
         is implemented internally).
     */
         (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
 
     /**
         Sets the item's font. All items in the tree should have the same height


@@ -808,22 +813,15 @@ public:
         but instead adding them only when needed, thus minimizing memory
         usage and loading time.
     */
         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.
     */
 
     /**
         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:
 
     /**
         Sets the specified item state. The value of @a state may be:


@@ -842,8 +840,8 @@ public:
     /**
         Sets the colour of the item's 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
 
     /**
         If @true is passed, specifies that the control will use a quick


@@ -923,9 +921,15 @@ public:
 
     @beginEventTable{wxTreeEvent}
     @event{EVT_TREE_BEGIN_DRAG(id, func)}
 
     @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)}
     @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)}
     @event{EVT_TREE_END_DRAG(id, func)}
         End dragging with the left or right mouse button.
     @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)}


@@ -980,7 +984,8 @@ public:
     /**
         Constructor, used by wxWidgets itself only.
     */
     /**
         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).
 
     /**
         Returns the item (valid for all events).


@@ -994,18 +999,18 @@ public:
     int GetKeyCode() const;
 
     /**
     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.
     */
 
     /**
         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;
 
     */
     wxTreeItemId GetOldItem() const;
 


@@ -1021,12 +1026,12 @@ public:
 
     /**
         Returns @true if the label edit was cancelled. This should be called
 
     /**
         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;
 
     /**
     */
     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);
         events). Windows only.
     */
     void SetToolTip(const wxString& tooltip);