X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..d58526d55433162cef8ad2ed7f422689862c3019:/interface/wx/treectrl.h diff --git a/interface/wx/treectrl.h b/interface/wx/treectrl.h index 89c72236db..dff4440b32 100644 --- a/interface/wx/treectrl.h +++ b/interface/wx/treectrl.h @@ -60,6 +60,59 @@ 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: @@ -75,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 { @@ -97,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 @@ -109,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. @@ -130,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 @@ -185,7 +239,7 @@ public: /** Collapses the given item. */ - void Collapse(const wxTreeItemId& item); + virtual void Collapse(const wxTreeItemId& item); /** Collapses the root item. @@ -204,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 @@ -239,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 @@ -263,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. @@ -304,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 @@ -320,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 @@ -334,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. @@ -355,13 +410,13 @@ 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 normal image list. @@ -371,12 +426,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. @@ -389,12 +444,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: @@ -408,20 +463,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. @@ -431,12 +479,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 @@ -444,7 +492,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 @@ -463,8 +511,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() @@ -474,7 +522,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 @@ -482,7 +530,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 @@ -492,7 +540,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 @@ -500,7 +548,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 @@ -513,14 +561,14 @@ 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. */ - wxTreeItemId GetSelection() const; + virtual wxTreeItemId GetSelection() const; /** Fills the array of tree items passed in with the currently selected @@ -534,7 +582,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 @@ -552,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_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. @@ -610,7 +656,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 @@ -622,22 +668,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 @@ -653,8 +699,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. @@ -673,14 +719,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 @@ -705,18 +751,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 @@ -724,18 +770,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); /** @@ -744,8 +795,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 @@ -754,7 +805,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 @@ -762,22 +813,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: @@ -791,13 +835,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 @@ -816,7 +860,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 @@ -833,12 +877,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 @@ -849,14 +893,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. @@ -877,9 +921,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)} @@ -934,7 +984,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). @@ -948,18 +999,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; @@ -975,12 +1026,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);