X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/320ab87c57a457bd953e248d5a51273f9103b34a..574be073c070a9bbe81ad68e98187b0b9e82c2df:/interface/wx/listctrl.h
diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index 66acc9a65e..bfd05c44af 100644
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
-// Name: listctrl.h
+// Name: wx/listctrl.h
// Purpose: interface of wxListCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -23,6 +23,7 @@
(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.
@@ -39,29 +40,19 @@
wxMac Note: 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.
-
- wxMSW Note: 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}
@@ -92,7 +83,7 @@
@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)}
@@ -160,9 +151,10 @@ public:
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
@@ -252,7 +244,8 @@ public:
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.
@@ -272,7 +265,7 @@ public:
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,
@@ -292,12 +285,30 @@ public:
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;
@@ -308,7 +319,13 @@ public:
/**
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;
@@ -338,8 +355,10 @@ public:
/**
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;
@@ -360,7 +379,7 @@ public:
/**
Gets the application-defined data associated with this item.
*/
- long GetItemData(long item) const;
+ wxUIntPtr GetItemData(long item) const;
/**
Returns the item's font.
@@ -523,7 +542,7 @@ public:
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().
@@ -578,57 +597,6 @@ public:
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.
@@ -664,7 +632,7 @@ public:
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.
@@ -689,14 +657,53 @@ public:
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.
@@ -770,7 +777,7 @@ public:
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.
@@ -780,7 +787,7 @@ public:
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.
@@ -836,7 +843,7 @@ public:
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
@@ -854,7 +861,79 @@ public:
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;
};
@@ -920,7 +999,7 @@ public:
/**
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
@@ -961,7 +1040,7 @@ public:
/**
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.
@@ -971,7 +1050,7 @@ public:
/**
The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
*/
- const wxString GetLabel() const;
+ const wxString& GetLabel() const;
/**
The mask.
@@ -986,7 +1065,7 @@ public:
/**
The text.
*/
- const wxString GetText() const;
+ const wxString& GetText() const;
/**
This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
@@ -1006,7 +1085,7 @@ public:
Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
@library{wxbase}
- @category{ctrl}
+ @category{data}
@see @ref overview_listctrl, wxListCtrl, wxListItem
*/
@@ -1022,9 +1101,9 @@ public:
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.
@@ -1218,7 +1297,7 @@ enum wxListColumnFormat
If the colour/font is not specified, the default list control colour/font is used.
@library{wxbase}
- @category{ctrl}
+ @category{data}
@see wxListCtrl
*/
@@ -1255,7 +1334,7 @@ public:
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.