X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/75504144d2ee5ce2bc62d186f04b2d445c2048c5..5eeccdd52c8a7140bfa220d412aa9dc181f7a4d8:/interface/wx/listctrl.h diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h index fe29f57455..0e746bde7a 100644 --- a/interface/wx/listctrl.h +++ b/interface/wx/listctrl.h @@ -3,9 +3,126 @@ // Purpose: interface of wxListCtrl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/// style flags +#define wxLC_VRULES 0x0001 +#define wxLC_HRULES 0x0002 + +#define wxLC_ICON 0x0004 +#define wxLC_SMALL_ICON 0x0008 +#define wxLC_LIST 0x0010 +#define wxLC_REPORT 0x0020 + +#define wxLC_ALIGN_TOP 0x0040 +#define wxLC_ALIGN_LEFT 0x0080 +#define wxLC_AUTOARRANGE 0x0100 +#define wxLC_VIRTUAL 0x0200 +#define wxLC_EDIT_LABELS 0x0400 +#define wxLC_NO_HEADER 0x0800 +#define wxLC_NO_SORT_HEADER 0x1000 +#define wxLC_SINGLE_SEL 0x2000 +#define wxLC_SORT_ASCENDING 0x4000 +#define wxLC_SORT_DESCENDING 0x8000 + +#define wxLC_MASK_TYPE (wxLC_ICON | wxLC_SMALL_ICON | wxLC_LIST | wxLC_REPORT) +#define wxLC_MASK_ALIGN (wxLC_ALIGN_TOP | wxLC_ALIGN_LEFT) +#define wxLC_MASK_SORT (wxLC_SORT_ASCENDING | wxLC_SORT_DESCENDING) + + +/// Mask flags to tell app/GUI what fields of wxListItem are valid +#define wxLIST_MASK_STATE 0x0001 +#define wxLIST_MASK_TEXT 0x0002 +#define wxLIST_MASK_IMAGE 0x0004 +#define wxLIST_MASK_DATA 0x0008 +#define wxLIST_SET_ITEM 0x0010 +#define wxLIST_MASK_WIDTH 0x0020 +#define wxLIST_MASK_FORMAT 0x0040 + +/// State flags for indicating the state of an item +#define wxLIST_STATE_DONTCARE 0x0000 +#define wxLIST_STATE_DROPHILITED 0x0001 // MSW only +#define wxLIST_STATE_FOCUSED 0x0002 +#define wxLIST_STATE_SELECTED 0x0004 +#define wxLIST_STATE_CUT 0x0008 // MSW only +#define wxLIST_STATE_DISABLED 0x0010 // OS2 only +#define wxLIST_STATE_FILTERED 0x0020 // OS2 only +#define wxLIST_STATE_INUSE 0x0040 // OS2 only +#define wxLIST_STATE_PICKED 0x0080 // OS2 only +#define wxLIST_STATE_SOURCE 0x0100 // OS2 only + +/// Hit test flags, used in HitTest +#define wxLIST_HITTEST_ABOVE 0x0001 // Above the client area. +#define wxLIST_HITTEST_BELOW 0x0002 // Below the client area. +#define wxLIST_HITTEST_NOWHERE 0x0004 // In the client area but below the last item. +#define wxLIST_HITTEST_ONITEMICON 0x0020 // On the bitmap associated with an item. +#define wxLIST_HITTEST_ONITEMLABEL 0x0080 // On the label (string) associated with an item. +#define wxLIST_HITTEST_ONITEMRIGHT 0x0100 // In the area to the right of an item. +#define wxLIST_HITTEST_ONITEMSTATEICON 0x0200 // On the state icon for a tree view item that is in a user-defined state. +#define wxLIST_HITTEST_TOLEFT 0x0400 // To the left of the client area. +#define wxLIST_HITTEST_TORIGHT 0x0800 // To the right of the client area. + +#define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON) + +/// GetSubItemRect constants +#define wxLIST_GETSUBITEMRECT_WHOLEITEM -1l + +/// Flags for GetNextItem (MSW only except wxLIST_NEXT_ALL) +enum +{ + wxLIST_NEXT_ABOVE, // Searches for an item above the specified item + wxLIST_NEXT_ALL, // Searches for subsequent item by index + wxLIST_NEXT_BELOW, // Searches for an item below the specified item + wxLIST_NEXT_LEFT, // Searches for an item to the left of the specified item + wxLIST_NEXT_RIGHT // Searches for an item to the right of the specified item +}; + +/// Alignment flags for Arrange (MSW only except wxLIST_ALIGN_LEFT) +enum +{ + wxLIST_ALIGN_DEFAULT, + wxLIST_ALIGN_LEFT, + wxLIST_ALIGN_TOP, + wxLIST_ALIGN_SNAP_TO_GRID +}; + +/// Column format (MSW only except wxLIST_FORMAT_LEFT) +enum wxListColumnFormat +{ + wxLIST_FORMAT_LEFT, + wxLIST_FORMAT_RIGHT, + wxLIST_FORMAT_CENTRE, + wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE +}; + +/// Autosize values for SetColumnWidth +enum +{ + wxLIST_AUTOSIZE = -1, + wxLIST_AUTOSIZE_USEHEADER = -2 // partly supported by generic version +}; + +/// Flag values for GetItemRect +enum +{ + wxLIST_RECT_BOUNDS, + wxLIST_RECT_ICON, + wxLIST_RECT_LABEL +}; + +/// Flag values for FindItem (MSW only) +enum +{ + wxLIST_FIND_UP, + wxLIST_FIND_DOWN, + wxLIST_FIND_LEFT, + wxLIST_FIND_RIGHT +}; + + + + /** @class wxListCtrl @@ -86,44 +203,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 +314,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 +349,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 +368,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 +405,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. @@ -449,8 +632,14 @@ public: /** Gets the item text for this item. + + @param item + Item (zero-based) index. + @param col + Item column (zero-based) index. Column 0 is the default. This + parameter is new in wxWidgets 2.9.1. */ - wxString GetItemText(long item) const; + wxString GetItemText(long item, int col = 0) const; /** Returns the colour for this item. @@ -516,7 +705,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(). @@ -584,16 +773,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. @@ -648,6 +874,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. @@ -754,7 +985,7 @@ public: @see GetColumnsOrder() */ - bool SetColumnsOrder(const wxArrayInt& orders) const; + bool SetColumnsOrder(const wxArrayInt& orders); /** Sets the image list associated with the control. @@ -830,15 +1061,6 @@ public: */ bool SetItemImage(long item, int image, int selImage = -1); - /** - Sets the unselected and selected images associated with the item. - The images are indices into the image list associated with the list control. - - @deprecated - This form is deprecated: @a selImage is not used; use the other - SetItemImage() overload. - */ - bool SetItemImage(long item, int image, int selImage = -1); /** Sets the position of the item, in icon or small icon view. Windows only. @@ -857,8 +1079,24 @@ public: bool SetItemPtrData(long item, wxUIntPtr data); /** - Sets the item state. For a list of state flags, see SetItem(). - The @b stateMask indicates which state flags are valid. + Sets the item state. + + The @a stateMask is a combination of @c wxLIST_STATE_XXX constants + described in wxListItem documentation. For each of the bits specified + in @a stateMask, the corresponding state is set or cleared depending on + whether @a state argument contains the same bit or not. + + So to select an item you can use + @code + list->SetItemState(item, wxLIST_STATE_SELECTED, wxLIST_STATE_SELECTED); + @endcode + while to deselect it you should use + @code + list->SetItemState(item, 0, wxLIST_STATE_SELECTED); + @endcode + + Consider using wxListView if possible to avoid dealing with this + error-prone and confusing method. */ bool SetItemState(long item, long state, long stateMask); @@ -894,7 +1132,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 @@ -1026,7 +1264,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)} @@ -1135,6 +1373,27 @@ public: }; +wxEventType wxEVT_COMMAND_LIST_BEGIN_DRAG; +wxEventType wxEVT_COMMAND_LIST_BEGIN_RDRAG; +wxEventType wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT; +wxEventType wxEVT_COMMAND_LIST_END_LABEL_EDIT; +wxEventType wxEVT_COMMAND_LIST_DELETE_ITEM; +wxEventType wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS; +wxEventType wxEVT_COMMAND_LIST_ITEM_SELECTED; +wxEventType wxEVT_COMMAND_LIST_ITEM_DESELECTED; +wxEventType wxEVT_COMMAND_LIST_KEY_DOWN; +wxEventType wxEVT_COMMAND_LIST_INSERT_ITEM; +wxEventType wxEVT_COMMAND_LIST_COL_CLICK; +wxEventType wxEVT_COMMAND_LIST_ITEM_RIGHT_CLICK; +wxEventType wxEVT_COMMAND_LIST_ITEM_MIDDLE_CLICK; +wxEventType wxEVT_COMMAND_LIST_ITEM_ACTIVATED; +wxEventType wxEVT_COMMAND_LIST_CACHE_HINT; +wxEventType wxEVT_COMMAND_LIST_COL_RIGHT_CLICK; +wxEventType wxEVT_COMMAND_LIST_COL_BEGIN_DRAG; +wxEventType wxEVT_COMMAND_LIST_COL_DRAGGING; +wxEventType wxEVT_COMMAND_LIST_COL_END_DRAG; +wxEventType wxEVT_COMMAND_LIST_ITEM_FOCUSED; + /** @class wxListItemAttr @@ -1305,16 +1564,6 @@ public: }; -/** - Column format (MSW only except wxLIST_FORMAT_LEFT). -*/ -enum wxListColumnFormat -{ - wxLIST_FORMAT_LEFT, - wxLIST_FORMAT_RIGHT, - wxLIST_FORMAT_CENTRE, - wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE -}; /** @class wxListItem