// Purpose: interface of wxListCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@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
*/
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:
/**
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();
/**
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();
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.
/**
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.
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().
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.
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.
@see GetColumnsOrder()
*/
- bool SetColumnsOrder(const wxArrayInt& orders) const;
+ bool SetColumnsOrder(const wxArrayInt& orders);
/**
Sets the image list associated with the control.
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
@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)}
projects / wxWidgets.git / blobdiff