X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5267aefd85739afd26bd19bfba998005119db446..e3c3dfb409452ec0079ab101d743682f8e87f46d:/interface/wx/listctrl.h
diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index ea1f76ef46..222af7f596 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
@@ -272,18 +264,31 @@ public:
/**
Find an item whose data matches this data, starting from start or the
beginning if 'start' is @c -1.
+
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as FindItemData(start, data).
+ @endWxPerlOnly
*/
- long FindItem(long start, long data);
+ long FindItem(long start, wxUIntPtr data);
/**
Find an item nearest this position in the specified direction,
starting from @a start or the beginning if @a start is -1.
+
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
+ @endWxPerlOnly
*/
long FindItem(long start, const wxPoint& pt, int direction);
/**
Gets information about this column.
See SetItem() for more information.
+
+ @beginWxPerlOnly
+ In wxPerl this method takes only the @a col parameter and
+ returns a @c Wx::ListItem (or @c undef).
+ @endWxPerlOnly
*/
bool GetColumn(int col, wxListItem& item) const;
@@ -293,12 +298,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;
@@ -309,7 +332,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;
@@ -339,8 +368,15 @@ 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.
+
+ @beginWxPerlOnly
+ In wxPerl this method takes as parameter the ID of the item
+ and (optionally) the column, and returns a Wx::ListItem object.
+ @endWxPerlOnly
*/
bool GetItem(wxListItem& info) const;
@@ -370,6 +406,11 @@ public:
/**
Returns the position of the item, in icon or small icon view.
+
+ @beginWxPerlOnly
+ In wxPerl this method takes only the @a item parameter and
+ returns a @c Wx::Point (or @c undef).
+ @endWxPerlOnly
*/
bool GetItemPosition(long item, wxPoint& pos) const;
@@ -378,6 +419,11 @@ public:
coordinates.
@a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
+
+ @beginWxPerlOnly
+ In wxPerl this method takes only the @a item and @a code parameters and
+ returns a @c Wx::Rect (or @c undef).
+ @endWxPerlOnly
*/
bool GetItemRect(long item, wxRect& rect,
int code = wxLIST_RECT_BOUNDS) const;
@@ -523,6 +569,11 @@ public:
the host system or the value stored in @a ptrSubItem will be always -1.
To compile this feature into wxWidgets library you need to have access to
commctrl.h of version 4.70 that is provided by Microsoft.
+
+ @beginWxPerlOnly
+ In wxPerl this method only takes the @a point parameter
+ and returns a 2-element list (item, flags).
+ @endWxPerlOnly
*/
long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
@@ -553,6 +604,10 @@ public:
Index of the new item, supplied by the application
@param label
String label
+
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as InsertStringItem(index, label).
+ @endWxPerlOnly
*/
long InsertItem(long index, const wxString& label);
@@ -563,6 +618,10 @@ public:
Index of the new item, supplied by the application
@param imageIndex
Index into the image list associated with this control and view style
+
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
+ @endWxPerlOnly
*/
long InsertItem(long index, int imageIndex);
@@ -575,61 +634,14 @@ public:
String label
@param imageIndex
Index into the image list associated with this control and view style
+
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
+ @endWxPerlOnly
*/
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.
@@ -690,14 +702,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.
+
+ 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.
- This function is valid in report view only.
+ @see GetColumnsOrder()
*/
- bool SetColumnOrder(const wxArrayInt& orders) const;
+ bool SetColumnsOrder(const wxArrayInt& orders) const;
/**
Sets the image list associated with the control.
@@ -837,7 +888,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,8 +905,86 @@ public:
items in the control.
Please see the @ref page_samples_listctrl for an example of using this function.
+
+ @beginWxPerlOnly
+ In wxPerl the comparison function must take just two parameters;
+ however, you may use a closure to achieve an effect similar to the
+ SortItems third parameter.
+ @endWxPerlOnly
+ */
+ 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()
*/
- bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
+ 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;
};
@@ -921,7 +1050,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
@@ -1007,7 +1136,7 @@ public:
Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
@library{wxbase}
- @category{ctrl}
+ @category{data}
@see @ref overview_listctrl, wxListCtrl, wxListItem
*/
@@ -1023,9 +1152,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.
@@ -1219,7 +1348,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
*/