// Purpose: interface of wxListCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
and attributes) is managed by the main program and is requested by the control
itself only when needed which allows to have controls with millions of items
without consuming much memory. To use virtual list control you must use
- wxListCtrl::SetItemCount first and overload at least wxListCtrl::OnGetItemText
+ wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
(and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
wxListCtrl::OnGetItemAttr) to return the information about the items when the
control requests it.
@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
/**
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.
protected:
/**
- This function may be overloaded in the derived class for a control with
+ This function may be overridden in the derived class for a control with
@c wxLC_VIRTUAL style. It should return the attribute for the specified
@c item or @NULL to use the default appearance parameters.
virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
/**
- Overload this function in the derived class for a control with
+ Override this function in the derived class for a control with
@c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
index for the given line and column.
virtual int OnGetItemColumnImage(long item, long column) const;
/**
- This function must be overloaded in the derived class for a control with
+ This function must be overridden in the derived class for a control with
@c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
- control doesn't have an image list, it is not necessary to overload it).
+ control doesn't have an image list, it is not necessary to override it).
It should return the index of the items image in the controls image list
or -1 for no image.
virtual int OnGetItemImage(long item) const;
/**
- This function @b must be overloaded in the derived class for a control with
+ This function @b must be overridden in the derived class for a control with
@c wxLC_VIRTUAL style. It should return the string containing the text of
the given @a column for the specified @c item.
@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