X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..cb755cb737c22705c58e3dba8b990c4d3eefd741:/interface/wx/treectrl.h diff --git a/interface/wx/treectrl.h b/interface/wx/treectrl.h index 372576d508..6897303738 100644 --- a/interface/wx/treectrl.h +++ b/interface/wx/treectrl.h @@ -60,11 +60,15 @@ for a particular toolkit. @endStyleTable - @beginEventTable{wxTreeEvent} + @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)} @@ -78,7 +82,8 @@ @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)} @@ -98,9 +103,11 @@ @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)} - 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 @@ -121,10 +128,10 @@ @library{wxcore} @category{ctrl} - + @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 { @@ -143,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 @@ -155,12 +163,12 @@ 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); /** @@ -253,18 +261,18 @@ public: 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. @@ -273,7 +281,7 @@ public: /** 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(); @@ -289,16 +297,17 @@ public: /** 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 @@ -309,7 +318,7 @@ 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. @@ -350,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 @@ -366,8 +375,8 @@ 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. @@ -401,14 +410,23 @@ 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. */ 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. */ @@ -417,7 +435,7 @@ public: /** Returns the current tree control indentation. */ - int GetIndent() const; + virtual unsigned int GetIndent() const; /** Returns the background colour of the item. @@ -454,21 +472,14 @@ 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. */ 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. */ @@ -509,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() @@ -564,7 +575,8 @@ public: /** 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(). */ virtual wxTreeItemId GetSelection() const; @@ -580,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 @@ -598,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. @@ -699,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. @@ -756,13 +766,13 @@ public: /** 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 @@ -775,6 +785,11 @@ public: /** 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. @@ -790,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 @@ -808,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: @@ -842,8 +850,8 @@ public: /** 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 @@ -923,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)} @@ -980,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). @@ -994,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; @@ -1021,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);