X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b6812a6f19ff9cbabfb7408017984a5c237d58ce..b02dd12239c8a59b9a545d9fcb04974f8ad02c6b:/interface/wx/listctrl.h?ds=sidebyside diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h index 9a6ddd739b..6a7a539801 100644 --- a/interface/wx/listctrl.h +++ b/interface/wx/listctrl.h @@ -3,7 +3,7 @@ // Purpose: interface of wxListCtrl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -86,44 +86,65 @@ @beginEventEmissionTable{wxListEvent} @event{EVT_LIST_BEGIN_DRAG(id, func)} Begin dragging with the left mouse button. + Processes a @c wxEVT_COMMAND_LIST_BEGIN_DRAG event type. @event{EVT_LIST_BEGIN_RDRAG(id, func)} - Begin dragging with the right mouse button.. + Begin dragging with the right mouse button. + Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type. @event{EVT_BEGIN_LABEL_EDIT(id, func)} Begin editing a label. This can be prevented by calling Veto(). + Processes a @c wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT event type. @event{EVT_LIST_END_LABEL_EDIT(id, func)} Finish editing a label. This can be prevented by calling Veto(). + Processes a @c wxEVT_COMMAND_LIST_END_LABEL_EDIT event type. @event{EVT_LIST_DELETE_ITEM(id, func)} An item was deleted. + Processes a @c wxEVT_COMMAND_LIST_DELETE_ITEM event type. @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)} All items were deleted. + Processes a @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event type. @event{EVT_LIST_ITEM_SELECTED(id, func)} The item has been selected. + Processes a @c wxEVT_COMMAND_LIST_ITEM_SELECTED event type. @event{EVT_LIST_ITEM_DESELECTED(id, func)} The item has been deselected. + Processes a @c wxEVT_COMMAND_LIST_ITEM_DESELECTED event type. @event{EVT_LIST_ITEM_ACTIVATED(id, func)} The item has been activated (ENTER or double click). + Processes a @c wxEVT_COMMAND_LIST_ITEM_ACTIVATED event type. @event{EVT_LIST_ITEM_FOCUSED(id, func)} The currently focused item has changed. + Processes a @c wxEVT_COMMAND_LIST_ITEM_FOCUSED event type. @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)} - The middle mouse button has been clicked on an item. + The middle mouse button has been clicked on an item. This is + only supported by the generic control. + Processes a @c wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK event type. @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)} The right mouse button has been clicked on an item. + Processes a @c wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK event type. @event{EVT_LIST_KEY_DOWN(id, func)} A key has been pressed. + Processes a @c wxEVT_COMMAND_LIST_KEY_DOWN event type. @event{EVT_LIST_INSERT_ITEM(id, func)} An item has been inserted. + Processes a @c wxEVT_COMMAND_LIST_INSERT_ITEM event type. @event{EVT_LIST_COL_CLICK(id, func)} A column (m_col) has been left-clicked. + Processes a @c wxEVT_COMMAND_LIST_COL_CLICK event type. @event{EVT_LIST_COL_RIGHT_CLICK(id, func)} A column (m_col) has been right-clicked. + Processes a @c wxEVT_COMMAND_LIST_COL_RIGHT_CLICK event type. @event{EVT_LIST_COL_BEGIN_DRAG(id, func)} The user started resizing a column - can be vetoed. + Processes a @c wxEVT_COMMAND_LIST_COL_BEGIN_DRAG event type. @event{EVT_LIST_COL_DRAGGING(id, func)} The divider between columns is being dragged. + Processes a @c wxEVT_COMMAND_LIST_COL_DRAGGING event type. @event{EVT_LIST_COL_END_DRAG(id, func)} A column has been resized by the user. + Processes a @c wxEVT_COMMAND_LIST_COL_END_DRAG event type. @event{EVT_LIST_CACHE_HINT(id, func)} Prepare cache for a virtual list control. + Processes a @c wxEVT_COMMAND_LIST_CACHE_HINT event type. @endEventTable @@ -176,6 +197,19 @@ public: */ virtual ~wxListCtrl(); + /** + Adds a new column to the list control in report view mode. + + This is just a convenient wrapper for InsertColumn() which adds the new + column after all the existing ones without having to specify its + position explicitly. + + @since 2.9.4 + */ + long AppendColumn(const wxString& heading, + int format = wxLIST_FORMAT_LEFT, + int width = -1); + /** Arranges the items in icon or small icon view. This only has effect on Win32. @a flag is one of: @@ -198,6 +232,9 @@ public: /** Deletes all items and all columns. + + @note This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS + under all platforms. */ void ClearAll(); @@ -214,9 +251,15 @@ public: /** Deletes all items in the list control. - @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM - event because deleting many items from the control would be too slow - then (unlike wxListCtrl::DeleteItem). + This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM + event because deleting many items from the control would be too slow + then (unlike wxListCtrl::DeleteItem) but it does send the special @c + wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS event if the control was not empty. + If it was already empty, nothing is done and no event is sent. + + @return @true if the items were successfully deleted or if the control + was already empty, @false if an error occurred while deleting the + items. */ bool DeleteAllItems(); @@ -245,7 +288,30 @@ public: will be sent which can be vetoed as well. */ wxTextCtrl* EditLabel(long item, - wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl)); + wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl)); + + /** + Finish editing the label. + + This method allows to programmatically end editing a list control item + in place. Usually it will only be called when editing is in progress, + i.e. if GetEditControl() returns non-NULL. In particular, do not call + it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not + yet fully created by then, just veto the event in this handler instead + to prevent the editing from even starting. + + Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT + event being generated. + + Currently only implemented in wxMSW. + + @param cancel If @true, discard the changes made by user, as if @c + Escape key was pressed. Otherwise, accept the changes as if @c + Return was pressed. + @return @true if item editing wad finished or @false if no item as + being edited. + */ + bool EndEditLabel(bool cancel); /** Ensures this item is visible. @@ -522,7 +588,7 @@ public: coordinates, of the given subitem, i.e. the part of the row @a item in the column @a subItem. - This method is only meaningfull when the wxListCtrl is in the report mode. + This method is only meaningful when the wxListCtrl is in the report mode. If @a subItem parameter is equal to the special value @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as for GetItemRect(). @@ -590,16 +656,53 @@ public: long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const; /** - For report view mode (only), inserts a column. For more details, see SetItem(). + Returns true if the control is currently using ::wxLC_REPORT style. + */ + bool InReportView() const; + + /** + For report view mode (only), inserts a column. + + For more details, see SetItem(). Also see InsertColumn(long, const + wxString&, int, int) overload for a usually more convenient + alternative to this method and the description of how the item width + is interpreted by this method. */ - long InsertColumn(long col, wxListItem& info); + long InsertColumn(long col, const wxListItem& info); /** - For report view mode (only), inserts a column. For more details, see SetItem(). + For report view mode (only), inserts a column. + + Insert a new column in the list control in report view mode at the + given position specifying its most common attributes. + + Notice that to set the image for the column you need to use + Insert(long, const wxListItem&) overload and specify ::wxLIST_MASK_IMAGE + in the item mask. + + @param col + The index where the column should be inserted. Valid indices are + from 0 up to GetColumnCount() inclusive and the latter can be used + to append the new column after the last existing one. + @param heading + The string specifying the column heading. + @param format + The flags specifying the control heading text alignment. + @param width + If positive, the width of the column in pixels. Otherwise it can be + @c wxLIST_AUTOSIZE to choose the default size for the column or @c + wxLIST_AUTOSIZE_USEHEADER to fit the column width to @a heading or + to extend to fill all the remaining space for the last column. + Notice that in case of @c wxLIST_AUTOSIZE fixed width is used as + there are no items in this column to use for determining its best + size yet. If you want to fit the column to its contents, use + SetColumnWidth() after adding the items with values in this column. + @return + The index of the inserted column or -1 if adding it failed. */ long InsertColumn(long col, const wxString& heading, int format = wxLIST_FORMAT_LEFT, - int width = -1); + int width = wxLIST_AUTOSIZE); /** Inserts an item, returning the index of the new item if successful, -1 otherwise. @@ -654,6 +757,11 @@ public: long InsertItem(long index, const wxString& label, int imageIndex); + /** + Returns true if the control is currently in virtual report view. + */ + bool IsVirtual() const; + /** Redraws the given @e item. @@ -760,7 +868,7 @@ public: @see GetColumnsOrder() */ - bool SetColumnsOrder(const wxArrayInt& orders) const; + bool SetColumnsOrder(const wxArrayInt& orders); /** Sets the image list associated with the control. @@ -900,7 +1008,7 @@ public: using the specified @a fnSortCallBack function. This function must have the following prototype: @code - int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData) + int wxCALLBACK wxListCompareFunction(wxIntPtr item1, wxIntPtr item2, wxIntPtr sortData) @endcode It is called each time when the two items must be compared and should return 0 @@ -1032,7 +1140,7 @@ protected: @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)} The right mouse button has been clicked on an item. @event{EVT_LIST_KEY_DOWN(id, func)} - A key has been pressed. + A key has been pressed. GetIndex() may be -1 if no item is selected. @event{EVT_LIST_INSERT_ITEM(id, func)} An item has been inserted. @event{EVT_LIST_COL_CLICK(id, func)}