X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b5176f6d75abef41a427b2297e07f5329b5b6200..f54c646fb0561e54bca0ee2c17847bb9e7123304:/interface/wx/listctrl.h diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h index 6a7a539801..d634fe8b14 100644 --- a/interface/wx/listctrl.h +++ b/interface/wx/listctrl.h @@ -2,10 +2,126 @@ // Name: wx/listctrl.h // Purpose: interface of wxListCtrl // Author: wxWidgets team -// RCS-ID: $Id$ // 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,71 +202,71 @@ @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. + Processes a @c wxEVT_LIST_BEGIN_DRAG event type. @event{EVT_LIST_BEGIN_RDRAG(id, func)} Begin dragging with the right mouse button. - Processes a @c wxEVT_COMMAND_LIST_BEGIN_RDRAG event type. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_LIST_ITEM_FOCUSED event type. @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)} 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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_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. + Processes a @c wxEVT_LIST_CACHE_HINT event type. @endEventTable @library{wxcore} @category{ctrl} - @appearance{listctrl.png} + @appearance{listctrl} @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList, wxListEvent, wxListItem, wxEditableListBox @@ -207,7 +323,7 @@ public: @since 2.9.4 */ long AppendColumn(const wxString& heading, - int format = wxLIST_FORMAT_LEFT, + wxListColumnFormat format = wxLIST_FORMAT_LEFT, int width = -1); /** @@ -233,7 +349,7 @@ public: /** Deletes all items and all columns. - @note This sends an event of type @c wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS + @note This sends an event of type @c wxEVT_LIST_DELETE_ALL_ITEMS under all platforms. */ void ClearAll(); @@ -251,10 +367,10 @@ public: /** Deletes all items in the list control. - This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM + This function does @e not send the @c wxEVT_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. + wxEVT_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 @@ -270,7 +386,7 @@ public: /** Deletes the specified item. - This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the + This function sends the @c wxEVT_LIST_DELETE_ITEM event for the item being deleted. @see DeleteAllItems() @@ -290,6 +406,39 @@ public: wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl)); + /** + Enable alternating row background colours (also called zebra striping). + + This method can only be called for the control in virtual report mode, + i.e. having ::wxLC_REPORT and ::wxLC_VIRTUAL styles. + + When enabling alternating colours, the appropriate colour for the even + rows is chosen automatically depending on the default foreground and + background colours which are used for the odd rows. + + @param enable + If @true, enable alternating row background colours, i.e. different + colours for the odd and even rows. If @false, disable this feature + and use the same background colour for all rows. + + @since 2.9.5 + + @see SetAlternateRowColour() + */ + void EnableAlternateRowColours(bool enable = true); + + /** + Enable or disable a beep if there is no match for the currently + entered text when searching for the item from keyboard. + + The default is to not beep in this case except in wxMSW where the + beep is always generated by the native control and cannot be disabled, + i.e. calls to this function do nothing there. + + @since 2.9.5 + */ + void EnableBellOnNoMatch(bool on = true); + /** Finish editing the label. @@ -621,6 +770,26 @@ public: */ wxRect GetViewRect() const; + /** + Set the alternative row background colour to a specific colour. + + It is recommended to call EnableAlternateRowColours() instead of using + these methods as native implementations of this control might support + alternating row colours but not setting the exact colour to be used for + them. + + As EnableAlternateRowColours(), this method can only be used with + controls having ::wxLC_REPORT and ::wxLC_VIRTUAL styles. + + @param colour + A valid alternative row background colour to enable alternating + rows or invalid colour to disable them and use the same colour for + all rows. + + @since 2.9.5 + */ + void SetAlternateRowColour(const wxColour& colour); + /** Determines which item (if any) is at the specified point, giving details in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at @@ -944,15 +1113,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. @@ -971,8 +1131,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); @@ -1159,7 +1335,7 @@ protected: @endEventTable - @library{wxbase} + @library{wxcore} @category{events} @see wxListCtrl @@ -1249,13 +1425,34 @@ public: }; +wxEventType wxEVT_LIST_BEGIN_DRAG; +wxEventType wxEVT_LIST_BEGIN_RDRAG; +wxEventType wxEVT_LIST_BEGIN_LABEL_EDIT; +wxEventType wxEVT_LIST_END_LABEL_EDIT; +wxEventType wxEVT_LIST_DELETE_ITEM; +wxEventType wxEVT_LIST_DELETE_ALL_ITEMS; +wxEventType wxEVT_LIST_ITEM_SELECTED; +wxEventType wxEVT_LIST_ITEM_DESELECTED; +wxEventType wxEVT_LIST_KEY_DOWN; +wxEventType wxEVT_LIST_INSERT_ITEM; +wxEventType wxEVT_LIST_COL_CLICK; +wxEventType wxEVT_LIST_ITEM_RIGHT_CLICK; +wxEventType wxEVT_LIST_ITEM_MIDDLE_CLICK; +wxEventType wxEVT_LIST_ITEM_ACTIVATED; +wxEventType wxEVT_LIST_CACHE_HINT; +wxEventType wxEVT_LIST_COL_RIGHT_CLICK; +wxEventType wxEVT_LIST_COL_BEGIN_DRAG; +wxEventType wxEVT_LIST_COL_DRAGGING; +wxEventType wxEVT_LIST_COL_END_DRAG; +wxEventType wxEVT_LIST_ITEM_FOCUSED; + /** @class wxListItemAttr Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem. - @library{wxbase} + @library{wxcore} @category{data} @see @ref overview_listctrl, wxListCtrl, wxListItem @@ -1339,7 +1536,7 @@ public: @library{wxcore} @category{ctrl} - @appearance{listview.png} + @appearance{listview} @see wxListView::SetColumnImage */ @@ -1419,16 +1616,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 @@ -1467,7 +1654,7 @@ enum wxListColumnFormat or SetFont() functions on it passing it the colour/font to use. If the colour/font is not specified, the default list control colour/font is used. - @library{wxbase} + @library{wxcore} @category{data} @see wxListCtrl