/////////////////////////////////////////////////////////////////////////////
-// 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
/**
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;
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.
+
+ @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;
/**
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;
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;
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;
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);
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);
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);
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.
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
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, long data);
+ bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
protected:
The base class version always returns @NULL.
- @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText()
+ @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
The base class version always calls OnGetItemImage() for the first column, else
it returns -1.
- @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr()
+ @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 @ref SetImageList() "image list"
- (if the control doesn't have an image list, it is not necessary to overload it).
+ @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.
/**
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