/////////////////////////////////////////////////////////////////////////////
-// Name: listctrl.h
+// Name: wx/listctrl.h
// Purpose: interface of wxListCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
(and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
wxListCtrl::OnGetItemAttr) to return the information about the items when the
control requests it.
+
Virtual list control can be used as a normal one except that no operations
which can take time proportional to the number of items in the control happen
-- this is required to allow having a practically infinite number of items.
<b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
implementation for report mode, and uses a generic implementation for other
modes. You can use the generic implementation for report mode as well by setting
- the @c mac.listctrl.always_use_generic system option (see wxSystemOption) to 1.
-
- <b>wxMSW Note</b>: In report view, the control has several columns
- which are identified by their internal indices. By default, these indices
- correspond to their order on screen, i.e. the column 0 appears first (in the
- left-to-right or maybe right-to-left if the current language uses this writing
- direction), the column 1 next and so on. However it is possible to reorder the
- columns visual order using SetColumnsOrder() method and the user can also
- rearrange the columns interactively by dragging them. In this case, the index
- of the column is not the same as its order and the functions GetColumnOrder()
- and GetColumnIndexFromOrder() should be used to translate between them.
+ the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
@beginStyleTable
@style{wxLC_LIST}
Multicolumn list view, with optional small icons. Columns are
computed automatically, i.e. you don't set columns as in
- wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
+ @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
@style{wxLC_REPORT}
Single or multicolumn report view, with optional header.
@style{wxLC_VIRTUAL}
The application provides items text on demand. May only be used
- with wxLC_REPORT.
+ with @c wxLC_REPORT.
@style{wxLC_ICON}
Large icon view, with optional labels.
@style{wxLC_SMALL_ICON}
@endStyleTable
- @beginEventTable{wxListEvent}
+ @beginEventEmissionTable{wxListEvent}
@event{EVT_LIST_BEGIN_DRAG(id, func)}
Begin dragging with the left mouse button.
@event{EVT_LIST_BEGIN_RDRAG(id, func)}
Window identifier. The value wxID_ANY indicates a default value.
@param pos
Window position.
+ If ::wxDefaultPosition is specified then a default position is chosen.
@param size
Window size.
- If wxDefaultSize is specified then the window is sized appropriately.
+ If ::wxDefaultSize is specified then the window is sized appropriately.
@param style
Window style. See wxListCtrl.
@param validator
the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
will be sent which can be vetoed as well.
*/
- void EditLabel(long item);
+ wxTextCtrl* EditLabel(long item,
+ wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
/**
Ensures this item is visible.
Find an item whose data matches this data, starting from start or the
beginning if 'start' is @c -1.
*/
- long FindItem(long start, long data);
+ long FindItem(long start, wxUIntPtr data);
/**
Find an item nearest this position in the specified direction,
int GetColumnCount() const;
/**
- Gets the column number by visual order index (report view only).
+ Gets the column index from its position in visual order.
+
+ After calling SetColumnsOrder(), the index returned by this function
+ corresponds to the value of the element number @a pos in the array
+ returned by GetColumnsOrder().
+
+ Please see SetColumnsOrder() documentation for an example and
+ additional remarks about the columns ordering.
+
+ @see GetColumnOrder()
*/
- int GetColumnIndexFromOrder(int order) const;
+ int GetColumnIndexFromOrder(int pos) const;
/**
- Gets the column visual order index (valid in report view only).
+ Gets the column visual order position.
+
+ This function returns the index of the column which appears at the
+ given visual position, e.g. calling it with @a col equal to 0 returns
+ the index of the first shown column.
+
+ Please see SetColumnsOrder() documentation for an example and
+ additional remarks about the columns ordering.
+
+ @see GetColumnsOrder(), GetColumnIndexFromOrder()
*/
int GetColumnOrder(int col) const;
/**
Returns the array containing the orders of all columns.
+
On error, an empty array is returned.
+
+ Please see SetColumnsOrder() documentation for an example and
+ additional remarks about the columns ordering.
+
+ @see GetColumnOrder(), GetColumnIndexFromOrder()
*/
wxArrayInt GetColumnsOrder() const;
/**
Gets information about the item. See SetItem() for more information.
- You must call @e info.SetId() to the ID of item you're interested in
- before calling this method.
+
+ You must call @e info.SetId() to set the ID of item you're interested in
+ before calling this method, and @e info.SetMask() with the flags indicating
+ what fields you need to retrieve from @a info.
*/
bool GetItem(wxListItem& info) const;
/**
Gets the application-defined data associated with this item.
*/
- long GetItemData(long item) const;
+ wxUIntPtr GetItemData(long item) const;
/**
Returns the item's font.
To compile this feature into wxWidgets library you need to have access to
commctrl.h of version 4.70 that is provided by Microsoft.
*/
- long HitTest(const wxPoint& point, int& flags, long* ptrSubItem) const;
+ long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
/**
For report view mode (only), inserts a column. For more details, see SetItem().
long InsertItem(long index, const wxString& label,
int imageIndex);
- /**
- This function may be overloaded 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.
-
- wxListCtrl will not delete the pointer or keep a reference of it.
- You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
-
- The base class version always returns @NULL.
-
- @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText()
- */
- virtual wxListItemAttr* OnGetItemAttr(long item) const;
-
- /**
- Overload 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.
-
- The base class version always calls OnGetItemImage() for the first column, else
- it returns -1.
-
- @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr()
- */
- virtual int OnGetItemColumnImage(long item, long column) const;
-
- /**
- This function must be overloaded in the derived class for a control with
- @c wxLC_VIRTUAL style having an @ref SetImageList() "image list"
- (if the control doesn't have an image list, it is not necessary to overload it).
- It should return the index of the items image in the controls image list
- or -1 for no image.
-
- In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
- the first column of each line.
-
- The base class version always returns -1.
-
- @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
- */
- virtual int OnGetItemImage(long item) const;
-
- /**
- This function @b must be overloaded 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.
-
- @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
- */
- virtual wxString OnGetItemText(long item, long column) const;
-
/**
Redraws the given @e item.
Note that the wxWindow::GetBackgroundColour() function of wxWindow base
class can be used to retrieve the current background colour.
*/
- void SetBackgroundColour(const wxColour& col);
+ virtual bool SetBackgroundColour(const wxColour& col);
/**
Sets information about this column.
bool SetColumnWidth(int col, int width);
/**
- Sets the order of all columns at once.
+ Changes the order in which the columns are shown.
+
+ By default, the columns of a list control appear on the screen in order
+ of their indices, i.e. the column 0 appears first, the column 1 next
+ and so on. However by using this function it is possible to arbitrarily
+ reorder the columns visual order and the user can also rearrange the
+ columns interactively by dragging them. In this case, the index of the
+ column is not the same as its order and the functions GetColumnOrder()
+ and GetColumnIndexFromOrder() should be used to translate between them.
+ Notice that all the other functions still work with the column indices,
+ i.e. the visual positioning of the columns on screen doesn't affect the
+ code setting or getting their values for example.
The @a orders array must have the same number elements as the number of
- columns and contain each position exactly once.
+ columns and contain each position exactly once. Its n-th element
+ contains the index of the column to be shown in n-th position, so for a
+ control with three columns passing an array with elements 2, 0 and 1
+ results in the third column being displayed first, the first one next
+ and the second one last.
- This function is valid in report view only.
+ Example of using it:
+ @code
+ wxListCtrl *list = new wxListCtrl(...);
+ for ( int i = 0; i < 3; i++ )
+ list->InsertColumn(i, wxString::Format("Column %d", i));
+
+ wxArrayInt order(3);
+ order[0] = 2;
+ order[1] = 0;
+ order[2] = 1;
+ list->SetColumnsOrder(order);
+
+ // now list->GetColumnsOrder() will return order and
+ // list->GetColumnIndexFromOrder(n) will return order[n] and
+ // list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
+ // 1 and 2 respectively
+ @endcode
+
+ Please notice that this function makes sense for report view only and
+ currently is only implemented in wxMSW port. To avoid explicit tests
+ for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
+ as this will allow it to start working under the other platforms when
+ support for the column reordering is added there.
+
+ @see GetColumnsOrder()
*/
- bool SetColumnOrder(const wxArrayInt& orders) const;
+ bool SetColumnsOrder(const wxArrayInt& orders) const;
/**
Sets the image list associated with the control.
Sets the unselected and selected images associated with the item.
The images are indices into the image list associated with the list control.
*/
- bool SetItemImage(long item, int image);
+ bool SetItemImage(long item, int image, int selImage = -1);
/**
Sets the unselected and selected images associated with the item.
This form is deprecated: @a selImage is not used; use the other
SetItemImage() overload.
*/
- bool SetItemImage(long item, int image, int selImage);
+ bool SetItemImage(long item, int image, int selImage = -1);
/**
Sets the position of the item, in icon or small icon view. Windows only.
using the specified @a fnSortCallBack function. This function must have the
following prototype:
@code
- int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
+ int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData)
@endcode
It is called each time when the two items must be compared and should return 0
Please see the @ref page_samples_listctrl for an example of using this function.
*/
- bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
+ bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
+
+protected:
+
+ /**
+ This function may be overloaded 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.
+
+ wxListCtrl will not delete the pointer or keep a reference of it.
+ You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
+
+ The base class version always returns @NULL.
+
+ @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
+ OnGetItemColumnAttr()
+ */
+ virtual wxListItemAttr* OnGetItemAttr(long item) const;
+
+ /**
+ This function may be overridden in the derived class for a control with
+ @c wxLC_VIRTUAL style.
+
+ It should return the attribute for the for the specified @a item and @a
+ column or @NULL to use the default appearance parameters.
+
+ The base class version returns @c OnGetItemAttr(item).
+
+ @note Currently this function is only called under wxMSW, the other
+ ports only support OnGetItemAttr()
+
+ @see OnGetItemAttr(), OnGetItemText(),
+ OnGetItemImage(), OnGetItemColumnImage(),
+ */
+ virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
+
+ /**
+ Overload 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.
+
+ The base class version always calls OnGetItemImage() for the first column, else
+ it returns -1.
+
+ @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
+ OnGetItemColumnAttr()
+ */
+ virtual int OnGetItemColumnImage(long item, long column) const;
+
+ /**
+ This function must be overloaded 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).
+ It should return the index of the items image in the controls image list
+ or -1 for no image.
+
+ In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
+ the first column of each line.
+
+ The base class version always returns -1.
+
+ @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
+ */
+ virtual int OnGetItemImage(long item) const;
+
+ /**
+ This function @b must be overloaded 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.
+
+ @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
+ */
+ virtual wxString OnGetItemText(long item, long column) const;
};
/**
Constructor.
*/
- wxListEvent(wxEventType commandType = 0, int id = 0);
+ wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
/**
For @c EVT_LIST_CACHE_HINT event only: return the first item which the
/**
An item object, used by some events. See also wxListCtrl::SetItem.
*/
- const wxListItem GetItem() const;
+ const wxListItem& GetItem() const;
/**
Key code if the event is a keypress event.
/**
The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
*/
- const wxString GetLabel() const;
+ const wxString& GetLabel() const;
/**
The mask.
/**
The text.
*/
- const wxString GetText() const;
+ const wxString& GetText() const;
/**
This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
@library{wxbase}
- @category{ctrl}
+ @category{data}
@see @ref overview_listctrl, wxListCtrl, wxListItem
*/
Construct a wxListItemAttr with the specified foreground and
background colors and font.
*/
- wxListItemAttr(const wxColour colText,
- const wxColour colBack,
- const wxFont font);
+ wxListItemAttr(const wxColour& colText,
+ const wxColour& colBack,
+ const wxFont& font);
/**
Returns the currently set background color.
If the colour/font is not specified, the default list control colour/font is used.
@library{wxbase}
- @category{ctrl}
+ @category{data}
@see wxListCtrl
*/
Returns client data associated with the control.
Please note that client data is associated with the item and not with subitems.
*/
- long GetData() const;
+ wxUIntPtr GetData() const;
/**
Returns the font used to display the item.
projects / wxWidgets.git / blobdiff