/////////////////////////////////////////////////////////////////////////////
-// 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)}
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;
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.
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.
Please see the @ref page_samples_listctrl for an example of using this function.
*/
bool SortItems(wxListCtrlCompare fnSortCallBack, long 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
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
*/
projects / wxWidgets.git / blobdiff