interface/wx/listctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/listctrl.h
   3 // Purpose:     interface of wxListCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxListCtrl
  11
  12     A list control presents lists in a number of formats: list view, report view,
  13     icon view and small icon view. In any case, elements are numbered from zero.
  14     For all these modes, the items are stored in the control and must be added to
  15     it using wxListCtrl::InsertItem method.
  16
  17     A special case of report view quite different from the other modes of the list
  18     control is a virtual control in which the items data (including text, images
  19     and attributes) is managed by the main program and is requested by the control
  20     itself only when needed which allows to have controls with millions of items
  21     without consuming much memory. To use virtual list control you must use
  22     wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText
  23     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
  24     wxListCtrl::OnGetItemAttr) to return the information about the items when the
  25     control requests it.
  26
  27     Virtual list control can be used as a normal one except that no operations
  28     which can take time proportional to the number of items in the control happen
  29     -- this is required to allow having a practically infinite number of items.
  30     For example, in a multiple selection virtual list control, the selections won't
  31     be sent when many items are selected at once because this could mean iterating
  32     over all the items.
  33
  34     Using many of wxListCtrl features is shown in the
  35     @ref page_samples_listctrl "corresponding sample".
  36
  37     To intercept events from a list control, use the event table macros described
  38     in wxListEvent.
  39
  40     <b>wxMac Note</b>: Starting with wxWidgets 2.8, wxListCtrl uses a native
  41     implementation for report mode, and uses a generic implementation for other
  42     modes. You can use the generic implementation for report mode as well by setting
  43     the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
  44
  45
  46     @beginStyleTable
  47     @style{wxLC_LIST}
  48            Multicolumn list view, with optional small icons. Columns are
  49            computed automatically, i.e. you don't set columns as in
  50            @c wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
  51     @style{wxLC_REPORT}
  52            Single or multicolumn report view, with optional header.
  53     @style{wxLC_VIRTUAL}
  54            The application provides items text on demand. May only be used
  55            with @c wxLC_REPORT.
  56     @style{wxLC_ICON}
  57            Large icon view, with optional labels.
  58     @style{wxLC_SMALL_ICON}
  59            Small icon view, with optional labels.
  60     @style{wxLC_ALIGN_TOP}
  61            Icons align to the top. Win32 default, Win32 only.
  62     @style{wxLC_ALIGN_LEFT}
  63            Icons align to the left.
  64     @style{wxLC_AUTOARRANGE}
  65            Icons arrange themselves. Win32 only.
  66     @style{wxLC_EDIT_LABELS}
  67            Labels are editable: the application will be notified when editing
  68            starts.
  69     @style{wxLC_NO_HEADER}
  70            No header in report mode.
  71     @style{wxLC_SINGLE_SEL}
  72            Single selection (default is multiple).
  73     @style{wxLC_SORT_ASCENDING}
  74            Sort in ascending order. (You must still supply a comparison callback
  75            in wxListCtrl::SortItems.)
  76     @style{wxLC_SORT_DESCENDING}
  77            Sort in descending order. (You must still supply a comparison callback
  78            in wxListCtrl::SortItems.)
  79     @style{wxLC_HRULES}
  80            Draws light horizontal rules between rows in report mode.
  81     @style{wxLC_VRULES}
  82            Draws light vertical rules between columns in report mode.
  83     @endStyleTable
  84
  85
  86     @beginEventEmissionTable{wxListEvent}
  87     @event{EVT_LIST_BEGIN_DRAG(id, func)}
  88            Begin dragging with the left mouse button.
  89     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
  90            Begin dragging with the right mouse button..
  91     @event{EVT_BEGIN_LABEL_EDIT(id, func)}
  92            Begin editing a label. This can be prevented by calling Veto().
  93     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
  94            Finish editing a label. This can be prevented by calling Veto().
  95     @event{EVT_LIST_DELETE_ITEM(id, func)}
  96            An item was deleted.
  97     @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
  98            All items were deleted.
  99     @event{EVT_LIST_ITEM_SELECTED(id, func)}
 100            The item has been selected.
 101     @event{EVT_LIST_ITEM_DESELECTED(id, func)}
 102            The item has been deselected.
 103     @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
 104            The item has been activated (ENTER or double click).
 105     @event{EVT_LIST_ITEM_FOCUSED(id, func)}
 106            The currently focused item has changed.
 107     @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
 108            The middle mouse button has been clicked on an item.
 109     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
 110           The right mouse button has been clicked on an item.
 111     @event{EVT_LIST_KEY_DOWN(id, func)}
 112            A key has been pressed.
 113     @event{EVT_LIST_INSERT_ITEM(id, func)}
 114            An item has been inserted.
 115     @event{EVT_LIST_COL_CLICK(id, func)}
 116            A column (m_col) has been left-clicked.
 117     @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
 118            A column (m_col) has been right-clicked.
 119     @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
 120            The user started resizing a column - can be vetoed.
 121     @event{EVT_LIST_COL_DRAGGING(id, func)}
 122            The divider between columns is being dragged.
 123     @event{EVT_LIST_COL_END_DRAG(id, func)}
 124            A column has been resized by the user.
 125     @event{EVT_LIST_CACHE_HINT(id, func)}
 126            Prepare cache for a virtual list control.
 127     @endEventTable
 128
 129
 130     @library{wxcore}
 131     @category{ctrl}
 132     @appearance{listctrl.png}
 133
 134     @see @ref overview_listctrl, wxListView, wxListBox, wxTreeCtrl, wxImageList,
 135          wxListEvent, wxListItem, wxEditableListBox
 136 */
 137 class wxListCtrl : public wxControl
 138 {
 139 public:
 140     /**
 141        Default constructor.
 142     */
 143     wxListCtrl();
 144
 145     /**
 146         Constructor, creating and showing a list control.
 147
 148         @param parent
 149             Parent window. Must not be @NULL.
 150         @param id
 151             Window identifier. The value wxID_ANY indicates a default value.
 152         @param pos
 153             Window position.
 154             If ::wxDefaultPosition is specified then a default position is chosen.
 155         @param size
 156             Window size.
 157             If ::wxDefaultSize is specified then the window is sized appropriately.
 158         @param style
 159             Window style. See wxListCtrl.
 160         @param validator
 161             Window validator.
 162         @param name
 163             Window name.
 164
 165         @see Create(), wxValidator
 166     */
 167     wxListCtrl(wxWindow* parent, wxWindowID id,
 168                const wxPoint& pos = wxDefaultPosition,
 169                const wxSize& size = wxDefaultSize,
 170                long style = wxLC_ICON,
 171                const wxValidator& validator = wxDefaultValidator,
 172                const wxString& name = wxListCtrlNameStr);
 173
 174     /**
 175         Destructor, destroying the list control.
 176     */
 177     virtual ~wxListCtrl();
 178
 179     /**
 180         Arranges the items in icon or small icon view.
 181         This only has effect on Win32. @a flag is one of:
 182         - wxLIST_ALIGN_DEFAULT: Default alignment.
 183         - wxLIST_ALIGN_LEFT: Align to the left side of the control.
 184         - wxLIST_ALIGN_TOP: Align to the top side of the control.
 185         - wxLIST_ALIGN_SNAP_TO_GRID: Snap to grid.
 186     */
 187     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 188
 189     /**
 190         Sets the image list associated with the control and takes ownership of it
 191         (i.e. the control will, unlike when using SetImageList(), delete the list
 192         when destroyed). @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
 193         @c wxIMAGE_LIST_STATE (the last is unimplemented).
 194
 195         @see SetImageList()
 196     */
 197     void AssignImageList(wxImageList* imageList, int which);
 198
 199     /**
 200         Deletes all items and all columns.
 201     */
 202     void ClearAll();
 203
 204     /**
 205         Creates the list control. See wxListCtrl() for further details.
 206     */
 207     bool Create(wxWindow* parent, wxWindowID id,
 208                 const wxPoint& pos = wxDefaultPosition,
 209                 const wxSize& size = wxDefaultSize,
 210                 long style = wxLC_ICON,
 211                 const wxValidator& validator = wxDefaultValidator,
 212                 const wxString& name = wxListCtrlNameStr);
 213
 214     /**
 215         Deletes all items in the list control.
 216
 217         @note This function does @e not send the @c wxEVT_COMMAND_LIST_DELETE_ITEM
 218               event because deleting many items from the control would be too slow
 219               then (unlike wxListCtrl::DeleteItem).
 220     */
 221     bool DeleteAllItems();
 222
 223     /**
 224         Deletes a column.
 225     */
 226     bool DeleteColumn(int col);
 227
 228     /**
 229         Deletes the specified item.
 230         This function sends the @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the
 231         item being deleted.
 232
 233         @see DeleteAllItems()
 234     */
 235     bool DeleteItem(long item);
 236
 237     /**
 238         Starts editing the label of the given item.
 239
 240         This function generates a @c EVT_LIST_BEGIN_LABEL_EDIT event which can be
 241         vetoed so that no text control will appear for in-place editing.
 242
 243         If the user changed the label (i.e. s/he does not press ESC or leave
 244         the text control without changes, a @c EVT_LIST_END_LABEL_EDIT event
 245         will be sent which can be vetoed as well.
 246     */
 247     wxTextCtrl* EditLabel(long item,
 248                           wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 249
 250     /**
 251         Ensures this item is visible.
 252     */
 253     bool EnsureVisible(long item);
 254
 255     /**
 256         Find an item whose label matches this string, starting from start or the
 257         beginning if start is @c -1. The string comparison is case insensitive.
 258
 259         If @a partial is @true then this method will look for items which begin with @a str.
 260
 261         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 262     */
 263     long FindItem(long start, const wxString& str,
 264                   bool partial = false);
 265
 266     /**
 267         Find an item whose data matches this data, starting from start or the
 268         beginning if 'start' is @c -1.
 269
 270         @beginWxPerlOnly
 271         In wxPerl this method is implemented as FindItemData(start, data).
 272         @endWxPerlOnly
 273
 274         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 275     */
 276     long FindItem(long start, wxUIntPtr data);
 277
 278     /**
 279         Find an item nearest this position in the specified direction,
 280         starting from @a start or the beginning if @a start is -1.
 281
 282         @beginWxPerlOnly
 283         In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
 284         @endWxPerlOnly
 285
 286         @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.
 287     */
 288     long FindItem(long start, const wxPoint& pt, int direction);
 289
 290     /**
 291         Gets information about this column.
 292         See SetItem() for more information.
 293
 294         @beginWxPerlOnly
 295         In wxPerl this method takes only the @a col parameter and
 296         returns a @c Wx::ListItem (or @c undef).
 297         @endWxPerlOnly
 298     */
 299     bool GetColumn(int col, wxListItem& item) const;
 300
 301     /**
 302         Returns the number of columns.
 303     */
 304     int GetColumnCount() const;
 305
 306     /**
 307         Gets the column index from its position in visual order.
 308
 309         After calling SetColumnsOrder(), the index returned by this function
 310         corresponds to the value of the element number @a pos in the array
 311         returned by GetColumnsOrder().
 312
 313         Please see SetColumnsOrder() documentation for an example and
 314         additional remarks about the columns ordering.
 315
 316         @see GetColumnOrder()
 317     */
 318     int GetColumnIndexFromOrder(int pos) const;
 319
 320     /**
 321         Gets the column visual order position.
 322
 323         This function returns the index of the column which appears at the
 324         given visual position, e.g. calling it with @a col equal to 0 returns
 325         the index of the first shown column.
 326
 327         Please see SetColumnsOrder() documentation for an example and
 328         additional remarks about the columns ordering.
 329
 330         @see GetColumnsOrder(), GetColumnIndexFromOrder()
 331     */
 332     int GetColumnOrder(int col) const;
 333
 334     /**
 335         Gets the column width (report view only).
 336     */
 337     int GetColumnWidth(int col) const;
 338
 339     /**
 340         Returns the array containing the orders of all columns.
 341
 342         On error, an empty array is returned.
 343
 344         Please see SetColumnsOrder() documentation for an example and
 345         additional remarks about the columns ordering.
 346
 347         @see GetColumnOrder(), GetColumnIndexFromOrder()
 348     */
 349     wxArrayInt GetColumnsOrder() const;
 350
 351     /**
 352         Gets the number of items that can fit vertically in the visible area of
 353         the list control (list or report view) or the total number of items in
 354         the list control (icon or small icon view).
 355     */
 356     int GetCountPerPage() const;
 357
 358     /**
 359         Returns the edit control being currently used to edit a label.
 360         Returns @NULL if no label is being edited.
 361
 362         @note It is currently only implemented for wxMSW and the generic version,
 363               not for the native Mac OS X version.
 364     */
 365     wxTextCtrl* GetEditControl() const;
 366
 367     /**
 368         Returns the specified image list. @a which may be one of:
 369         - wxIMAGE_LIST_NORMAL: The normal (large icon) image list.
 370         - wxIMAGE_LIST_SMALL: The small icon image list.
 371         - wxIMAGE_LIST_STATE: The user-defined state image list (unimplemented).
 372     */
 373     wxImageList* GetImageList(int which) const;
 374
 375     /**
 376         Gets information about the item. See SetItem() for more information.
 377
 378         You must call @e info.SetId() to set the ID of item you're interested in
 379         before calling this method, and @e info.SetMask() with the flags indicating
 380         what fields you need to retrieve from @a info.
 381
 382         @beginWxPerlOnly
 383         In wxPerl this method takes as parameter the ID of the item
 384         and (optionally) the column, and returns a Wx::ListItem object.
 385         @endWxPerlOnly
 386     */
 387     bool GetItem(wxListItem& info) const;
 388
 389     /**
 390         Returns the colour for this item.
 391         If the item has no specific colour, returns an invalid colour
 392         (and not the default background control of the control itself).
 393
 394         @see GetItemTextColour()
 395     */
 396     wxColour GetItemBackgroundColour(long item) const;
 397
 398     /**
 399         Returns the number of items in the list control.
 400     */
 401     int GetItemCount() const;
 402
 403     /**
 404         Gets the application-defined data associated with this item.
 405     */
 406     wxUIntPtr GetItemData(long item) const;
 407
 408     /**
 409         Returns the item's font.
 410     */
 411     wxFont GetItemFont(long item) const;
 412
 413     /**
 414         Returns the position of the item, in icon or small icon view.
 415
 416         @beginWxPerlOnly
 417         In wxPerl this method takes only the @a item parameter and
 418         returns a @c Wx::Point (or @c undef).
 419         @endWxPerlOnly
 420     */
 421     bool GetItemPosition(long item, wxPoint& pos) const;
 422
 423     /**
 424         Returns the rectangle representing the item's size and position, in physical
 425         coordinates.
 426
 427         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
 428
 429         @beginWxPerlOnly
 430         In wxPerl this method takes only the @a item and @a code parameters and
 431         returns a @c Wx::Rect (or @c undef).
 432         @endWxPerlOnly
 433     */
 434     bool GetItemRect(long item, wxRect& rect,
 435                      int code = wxLIST_RECT_BOUNDS) const;
 436
 437     /**
 438         Retrieves the spacing between icons in pixels: horizontal spacing is
 439         returned as @c x component of the wxSize object and the vertical spacing
 440         as its @c y component.
 441     */
 442     wxSize GetItemSpacing() const;
 443
 444     /**
 445         Gets the item state. For a list of state flags, see SetItem().
 446         The @a stateMask indicates which state flags are of interest.
 447     */
 448     int GetItemState(long item, long stateMask) const;
 449
 450     /**
 451         Gets the item text for this item.
 452
 453         @param item
 454             Item (zero-based) index.
 455         @param col
 456             Item column (zero-based) index. Column 0 is the default. This
 457             parameter is new in wxWidgets 2.9.1.
 458     */
 459     wxString GetItemText(long item, int col = 0) const;
 460
 461     /**
 462         Returns the colour for this item.
 463
 464         If the item has no specific colour, returns an invalid colour (and not the
 465         default foreground control of the control itself as this wouldn't allow
 466         distinguishing between items having the same colour as the current control
 467         foreground and items with default colour which, hence, have always the
 468         same colour as the control).
 469     */
 470     wxColour GetItemTextColour(long item) const;
 471
 472     /**
 473         Searches for an item with the given geometry or state, starting from
 474         @a item but excluding the @a item itself.
 475
 476         If @a item is -1, the first item that matches the specified flags will be returned.
 477         Returns the first item with given state following @a item or -1 if no such item found.
 478         This function may be used to find all selected items in the control like this:
 479
 480         @code
 481         long item = -1;
 482         for ( ;; )
 483         {
 484             item = listctrl->GetNextItem(item,
 485                                         wxLIST_NEXT_ALL,
 486                                         wxLIST_STATE_SELECTED);
 487             if ( item == -1 )
 488                 break;
 489
 490             // this item is selected - do whatever is needed with it
 491             wxLogMessage("Item %ld is selected.", item);
 492         }
 493         @endcode
 494
 495         @a geometry can be one of:
 496         - wxLIST_NEXT_ABOVE: Searches for an item above the specified item.
 497         - wxLIST_NEXT_ALL: Searches for subsequent item by index.
 498         - wxLIST_NEXT_BELOW: Searches for an item below the specified item.
 499         - wxLIST_NEXT_LEFT: Searches for an item to the left of the specified item.
 500         - wxLIST_NEXT_RIGHT: Searches for an item to the right of the specified item.
 501
 502         @note this parameter is only supported by wxMSW currently and ignored on
 503               other platforms.
 504
 505         @a state can be a bitlist of the following:
 506         - wxLIST_STATE_DONTCARE: Don't care what the state is.
 507         - wxLIST_STATE_DROPHILITED: The item indicates it is a drop target.
 508         - wxLIST_STATE_FOCUSED: The item has the focus.
 509         - wxLIST_STATE_SELECTED: The item is selected.
 510         - wxLIST_STATE_CUT: The item is selected as part of a cut and paste operation.
 511     */
 512     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL,
 513                      int state = wxLIST_STATE_DONTCARE) const;
 514
 515     /**
 516         Returns the number of selected items in the list control.
 517     */
 518     int GetSelectedItemCount() const;
 519
 520     /**
 521         Returns the rectangle representing the size and position, in physical
 522         coordinates, of the given subitem, i.e. the part of the row @a item in the
 523         column @a subItem.
 524
 525         This method is only meaningfull when the wxListCtrl is in the report mode.
 526         If @a subItem parameter is equal to the special value
 527         @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as
 528         for GetItemRect().
 529
 530         @a code can be one of @c wxLIST_RECT_BOUNDS, @c wxLIST_RECT_ICON or
 531         @c wxLIST_RECT_LABEL.
 532
 533         @since 2.7.0
 534     */
 535     bool GetSubItemRect(long item, long subItem, wxRect& rect,
 536                         int code = wxLIST_RECT_BOUNDS) const;
 537
 538     /**
 539         Gets the text colour of the list control.
 540     */
 541     wxColour GetTextColour() const;
 542
 543     /**
 544         Gets the index of the topmost visible item when in list or report view.
 545     */
 546     long GetTopItem() const;
 547
 548     /**
 549         Returns the rectangle taken by all items in the control. In other words, if the
 550         controls client size were equal to the size of this rectangle, no scrollbars
 551         would be needed and no free space would be left.
 552
 553         Note that this function only works in the icon and small icon views, not in
 554         list or report views (this is a limitation of the native Win32 control).
 555     */
 556     wxRect GetViewRect() const;
 557
 558     /**
 559         Determines which item (if any) is at the specified point, giving details
 560         in @a flags. Returns index of the item or @c wxNOT_FOUND if no item is at
 561         the specified point.
 562
 563         @a flags will be a combination of the following flags:
 564         - wxLIST_HITTEST_ABOVE: Above the client area.
 565         - wxLIST_HITTEST_BELOW: Below the client area.
 566         - wxLIST_HITTEST_NOWHERE: In the client area but below the last item.
 567         - wxLIST_HITTEST_ONITEMICON: On the bitmap associated with an item.
 568         - wxLIST_HITTEST_ONITEMLABEL: On the label (string) associated with an item.
 569         - wxLIST_HITTEST_ONITEMRIGHT: In the area to the right of an item.
 570         - wxLIST_HITTEST_ONITEMSTATEICON: On the state icon for a tree view item
 571           that is in a user-defined state.
 572         - wxLIST_HITTEST_TOLEFT: To the right of the client area.
 573         - wxLIST_HITTEST_TORIGHT: To the left of the client area.
 574         - wxLIST_HITTEST_ONITEM: Combination of @c wxLIST_HITTEST_ONITEMICON,
 575           @c wxLIST_HITTEST_ONITEMLABEL, @c wxLIST_HITTEST_ONITEMSTATEICON.
 576
 577         If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
 578         mode the subitem (or column) number will also be provided.
 579         This feature is only available in version 2.7.0 or higher and is currently only
 580         implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on
 581         the host system or the value stored in @a ptrSubItem will be always -1.
 582         To compile this feature into wxWidgets library you need to have access to
 583         commctrl.h of version 4.70 that is provided by Microsoft.
 584
 585         @beginWxPerlOnly
 586         In wxPerl this method only takes the @a point parameter
 587         and returns a 2-element list (item, flags).
 588         @endWxPerlOnly
 589     */
 590     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 591
 592     /**
 593         For report view mode (only), inserts a column. For more details, see SetItem().
 594     */
 595     long InsertColumn(long col, wxListItem& info);
 596
 597     /**
 598         For report view mode (only), inserts a column. For more details, see SetItem().
 599     */
 600     long InsertColumn(long col, const wxString& heading,
 601                       int format = wxLIST_FORMAT_LEFT,
 602                       int width = -1);
 603
 604     /**
 605         Inserts an item, returning the index of the new item if successful, -1 otherwise.
 606
 607         @param info
 608             wxListItem object
 609     */
 610     long InsertItem(wxListItem& info);
 611
 612     /**
 613         Insert an string item.
 614
 615         @param index
 616             Index of the new item, supplied by the application
 617         @param label
 618             String label
 619
 620         @beginWxPerlOnly
 621         In wxPerl this method is implemented as InsertStringItem(index, label).
 622         @endWxPerlOnly
 623     */
 624     long InsertItem(long index, const wxString& label);
 625
 626     /**
 627         Insert an image item.
 628
 629         @param index
 630             Index of the new item, supplied by the application
 631         @param imageIndex
 632             Index into the image list associated with this control and view style
 633
 634         @beginWxPerlOnly
 635         In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
 636         @endWxPerlOnly
 637     */
 638     long InsertItem(long index, int imageIndex);
 639
 640     /**
 641         Insert an image/string item.
 642
 643         @param index
 644             Index of the new item, supplied by the application
 645         @param label
 646             String label
 647         @param imageIndex
 648             Index into the image list associated with this control and view style
 649
 650         @beginWxPerlOnly
 651         In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
 652         @endWxPerlOnly
 653     */
 654     long InsertItem(long index, const wxString& label,
 655                     int imageIndex);
 656
 657     /**
 658         Redraws the given @e item.
 659
 660         This is only useful for the virtual list controls as without calling this
 661         function the displayed value of the item doesn't change even when the
 662         underlying data does change.
 663
 664         @see RefreshItems()
 665     */
 666     void RefreshItem(long item);
 667
 668     /**
 669         Redraws the items between @a itemFrom and @e itemTo.
 670         The starting item must be less than or equal to the ending one.
 671
 672         Just as RefreshItem() this is only useful for virtual list controls.
 673     */
 674     void RefreshItems(long itemFrom, long itemTo);
 675
 676     /**
 677         Scrolls the list control. If in icon, small icon or report view mode,
 678         @a dx specifies the number of pixels to scroll. If in list view mode,
 679         @a dx specifies the number of columns to scroll. @a dy always specifies
 680         the number of pixels to scroll vertically.
 681
 682         @note This method is currently only implemented in the Windows version.
 683     */
 684     bool ScrollList(int dx, int dy);
 685
 686     /**
 687         Sets the background colour.
 688
 689         Note that the wxWindow::GetBackgroundColour() function of wxWindow base
 690         class can be used to retrieve the current background colour.
 691     */
 692     virtual bool SetBackgroundColour(const wxColour& col);
 693
 694     /**
 695         Sets information about this column.
 696         See SetItem() for more information.
 697     */
 698     bool SetColumn(int col, wxListItem& item);
 699
 700     /**
 701         Sets the column width.
 702
 703         @a width can be a width in pixels or @c wxLIST_AUTOSIZE (-1) or
 704         @c wxLIST_AUTOSIZE_USEHEADER (-2).
 705
 706         @c wxLIST_AUTOSIZE will resize the column to the length of its longest item.
 707
 708         @c wxLIST_AUTOSIZE_USEHEADER will resize the column to the length of the
 709         header (Win32) or 80 pixels (other platforms).
 710
 711         In small or normal icon view, @a col must be -1, and the column width is set
 712         for all columns.
 713     */
 714     bool SetColumnWidth(int col, int width);
 715
 716     /**
 717         Changes the order in which the columns are shown.
 718
 719         By default, the columns of a list control appear on the screen in order
 720         of their indices, i.e. the column 0 appears first, the column 1 next
 721         and so on. However by using this function it is possible to arbitrarily
 722         reorder the columns visual order and the user can also rearrange the
 723         columns interactively by dragging them. In this case, the index of the
 724         column is not the same as its order and the functions GetColumnOrder()
 725         and GetColumnIndexFromOrder() should be used to translate between them.
 726         Notice that all the other functions still work with the column indices,
 727         i.e. the visual positioning of the columns on screen doesn't affect the
 728         code setting or getting their values for example.
 729
 730         The @a orders array must have the same number elements as the number of
 731         columns and contain each position exactly once. Its n-th element
 732         contains the index of the column to be shown in n-th position, so for a
 733         control with three columns passing an array with elements 2, 0 and 1
 734         results in the third column being displayed first, the first one next
 735         and the second one last.
 736
 737         Example of using it:
 738         @code
 739             wxListCtrl *list = new wxListCtrl(...);
 740             for ( int i = 0; i < 3; i++ )
 741                 list->InsertColumn(i, wxString::Format("Column %d", i));
 742
 743             wxArrayInt order(3);
 744             order[0] = 2;
 745             order[1] = 0;
 746             order[2] = 1;
 747             list->SetColumnsOrder(order);
 748
 749             // now list->GetColumnsOrder() will return order and
 750             // list->GetColumnIndexFromOrder(n) will return order[n] and
 751             // list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
 752             // 1 and 2 respectively
 753         @endcode
 754
 755         Please notice that this function makes sense for report view only and
 756         currently is only implemented in wxMSW port. To avoid explicit tests
 757         for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
 758         as this will allow it to start working under the other platforms when
 759         support for the column reordering is added there.
 760
 761         @see GetColumnsOrder()
 762     */
 763     bool SetColumnsOrder(const wxArrayInt& orders) const;
 764
 765     /**
 766         Sets the image list associated with the control.
 767
 768         @a which is one of @c wxIMAGE_LIST_NORMAL, @c wxIMAGE_LIST_SMALL,
 769         @c wxIMAGE_LIST_STATE (the last is unimplemented).
 770
 771         This method does not take ownership of the image list, you have to
 772         delete it yourself.
 773
 774         @see AssignImageList()
 775     */
 776     void SetImageList(wxImageList* imageList, int which);
 777
 778     /**
 779         Sets the data of an item.
 780
 781         Using the wxListItem's mask and state mask, you can change only selected
 782         attributes of a wxListCtrl item.
 783     */
 784     bool SetItem(wxListItem& info);
 785
 786     /**
 787         Sets an item string field at a particular column.
 788     */
 789     long SetItem(long index, int column, const wxString& label, int imageId = -1);
 790
 791     /**
 792         Sets the background colour for this item.
 793         This function only works in report view mode.
 794         The colour can be retrieved using GetItemBackgroundColour().
 795     */
 796     void SetItemBackgroundColour(long item, const wxColour& col);
 797
 798     /**
 799         Sets the image associated with the item.
 800         In report view, you can specify the column.
 801         The image is an index into the image list associated with the list control.
 802     */
 803     bool SetItemColumnImage(long item, long column, int image);
 804
 805     /**
 806         This method can only be used with virtual list controls.
 807
 808         It is used to indicate to the control the number of items it contains.
 809         After calling it, the main program should be ready to handle calls to
 810         various item callbacks (such as wxListCtrl::OnGetItemText) for all
 811         items in the range from 0 to @a count.
 812
 813         Notice that the control is not necessarily redrawn after this call as
 814         it may be undesirable if an item which is not visible on the screen
 815         anyhow was added to or removed from a control displaying many items, if
 816         you do need to refresh the display you can just call Refresh() manually.
 817     */
 818     void SetItemCount(long count);
 819
 820     /**
 821         Associates application-defined data with this item.
 822
 823         Notice that this function cannot be used to associate pointers with the control
 824         items, use SetItemPtrData() instead.
 825     */
 826     bool SetItemData(long item, long data);
 827
 828     /**
 829          Sets the item's font.
 830     */
 831     void SetItemFont(long item, const wxFont& font);
 832
 833     /**
 834         Sets the unselected and selected images associated with the item.
 835         The images are indices into the image list associated with the list control.
 836     */
 837     bool SetItemImage(long item, int image, int selImage = -1);
 838
 839     /**
 840         Sets the unselected and selected images associated with the item.
 841         The images are indices into the image list associated with the list control.
 842
 843         @deprecated
 844         This form is deprecated: @a selImage is not used; use the other
 845         SetItemImage() overload.
 846     */
 847     bool SetItemImage(long item, int image, int selImage = -1);
 848
 849     /**
 850         Sets the position of the item, in icon or small icon view. Windows only.
 851     */
 852     bool SetItemPosition(long item, const wxPoint& pos);
 853
 854     /**
 855         Associates application-defined data with this item.
 856
 857         The @a data parameter may be either an integer or a pointer cast to the
 858         @c wxUIntPtr type which is guaranteed to be large enough to be able to
 859         contain all integer types and pointers.
 860
 861         @since 2.8.4
 862     */
 863     bool SetItemPtrData(long item, wxUIntPtr data);
 864
 865     /**
 866         Sets the item state. For a list of state flags, see SetItem().
 867         The @b stateMask indicates which state flags are valid.
 868     */
 869     bool SetItemState(long item, long state, long stateMask);
 870
 871     /**
 872         Sets the item text for this item.
 873     */
 874     void SetItemText(long item, const wxString& text);
 875
 876     /**
 877         Sets the colour for this item.
 878         This function only works in report view.
 879         The colour can be retrieved using GetItemTextColour().
 880     */
 881     void SetItemTextColour(long item, const wxColour& col);
 882
 883     /**
 884         Adds or removes a single window style.
 885     */
 886     void SetSingleStyle(long style, bool add = true);
 887
 888     /**
 889         Sets the text colour of the list control.
 890     */
 891     void SetTextColour(const wxColour& col);
 892
 893     /**
 894         Sets the whole window style, deleting all items.
 895     */
 896     void SetWindowStyleFlag(long style);
 897
 898     /**
 899         Call this function to sort the items in the list control. Sorting is done
 900         using the specified @a fnSortCallBack function. This function must have the
 901         following prototype:
 902         @code
 903         int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData)
 904         @endcode
 905
 906         It is called each time when the two items must be compared and should return 0
 907         if the items are equal, negative value if the first item is less than the
 908         second one and positive value if the first one is greater than the second one
 909         (the same convention as used by @c qsort(3)).
 910
 911         The parameter @e item1 is the client data associated with the first item (NOT the index).
 912         The parameter @e item2 is the client data associated with the second item (NOT the index).
 913         The parameter @e data is the value passed to SortItems() itself.
 914
 915         Notice that the control may only be sorted on client data associated with
 916         the items, so you must use SetItemData if you want to be able to sort the
 917         items in the control.
 918
 919         Please see the @ref page_samples_listctrl for an example of using this function.
 920
 921         @beginWxPerlOnly
 922         In wxPerl the comparison function must take just two parameters;
 923         however, you may use a closure to achieve an effect similar to the
 924         SortItems third parameter.
 925         @endWxPerlOnly
 926     */
 927     bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);
 928
 929 protected:
 930
 931     /**
 932         This function may be overridden in the derived class for a control with
 933         @c wxLC_VIRTUAL style. It should return the attribute for the specified
 934         @c item or @NULL to use the default appearance parameters.
 935
 936         wxListCtrl will not delete the pointer or keep a reference of it.
 937         You can return the same wxListItemAttr pointer for every OnGetItemAttr() call.
 938
 939         The base class version always returns @NULL.
 940
 941         @see OnGetItemImage(), OnGetItemColumnImage(), OnGetItemText(),
 942              OnGetItemColumnAttr()
 943     */
 944     virtual wxListItemAttr* OnGetItemAttr(long item) const;
 945
 946      /**
 947         This function may be overridden in the derived class for a control with
 948         @c wxLC_VIRTUAL style.
 949
 950         It should return the attribute for the for the specified @a item and @a
 951         column or @NULL to use the default appearance parameters.
 952
 953         The base class version returns @c OnGetItemAttr(item).
 954
 955         @note Currently this function is only called under wxMSW, the other
 956             ports only support OnGetItemAttr()
 957
 958         @see OnGetItemAttr(), OnGetItemText(),
 959              OnGetItemImage(), OnGetItemColumnImage(),
 960     */
 961     virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
 962
 963     /**
 964         Override this function in the derived class for a control with
 965         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
 966         index for the given line and column.
 967
 968         The base class version always calls OnGetItemImage() for the first column, else
 969         it returns -1.
 970
 971         @see OnGetItemText(), OnGetItemImage(), OnGetItemAttr(),
 972              OnGetItemColumnAttr()
 973     */
 974     virtual int OnGetItemColumnImage(long item, long column) const;
 975
 976     /**
 977         This function must be overridden in the derived class for a control with
 978         @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
 979         control doesn't have an image list, it is not necessary to override it).
 980         It should return the index of the items image in the controls image list
 981         or -1 for no image.
 982
 983         In a control with @c wxLC_REPORT style, OnGetItemImage() only gets called for
 984         the first column of each line.
 985
 986         The base class version always returns -1.
 987
 988         @see OnGetItemText(), OnGetItemColumnImage(), OnGetItemAttr()
 989     */
 990     virtual int OnGetItemImage(long item) const;
 991
 992     /**
 993         This function @b must be overridden in the derived class for a control with
 994         @c wxLC_VIRTUAL style. It should return the string containing the text of
 995         the given @a column for the specified @c item.
 996
 997         @see SetItemCount(), OnGetItemImage(), OnGetItemColumnImage(), OnGetItemAttr()
 998     */
 999     virtual wxString OnGetItemText(long item, long column) const;
1000 };
1001
1002
1003
1004 /**
1005     @class wxListEvent
1006
1007     A list event holds information about events associated with wxListCtrl objects.
1008
1009     @beginEventTable{wxListEvent}
1010     @event{EVT_LIST_BEGIN_DRAG(id, func)}
1011         Begin dragging with the left mouse button.
1012     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
1013         Begin dragging with the right mouse button.
1014     @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}
1015         Begin editing a label. This can be prevented by calling Veto().
1016     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
1017         Finish editing a label. This can be prevented by calling Veto().
1018     @event{EVT_LIST_DELETE_ITEM(id, func)}
1019         Delete an item.
1020     @event{EVT_LIST_DELETE_ALL_ITEMS(id, func)}
1021         Delete all items.
1022     @event{EVT_LIST_ITEM_SELECTED(id, func)}
1023         The item has been selected.
1024     @event{EVT_LIST_ITEM_DESELECTED(id, func)}
1025         The item has been deselected.
1026     @event{EVT_LIST_ITEM_ACTIVATED(id, func)}
1027         The item has been activated (ENTER or double click).
1028     @event{EVT_LIST_ITEM_FOCUSED(id, func)}
1029         The currently focused item has changed.
1030     @event{EVT_LIST_ITEM_MIDDLE_CLICK(id, func)}
1031         The middle mouse button has been clicked on an item.
1032     @event{EVT_LIST_ITEM_RIGHT_CLICK(id, func)}
1033         The right mouse button has been clicked on an item.
1034     @event{EVT_LIST_KEY_DOWN(id, func)}
1035         A key has been pressed.
1036     @event{EVT_LIST_INSERT_ITEM(id, func)}
1037         An item has been inserted.
1038     @event{EVT_LIST_COL_CLICK(id, func)}
1039         A column (m_col) has been left-clicked.
1040     @event{EVT_LIST_COL_RIGHT_CLICK(id, func)}
1041         A column (m_col) (which can be -1 if the click occurred outside any column)
1042         has been right-clicked.
1043     @event{EVT_LIST_COL_BEGIN_DRAG(id, func)}
1044         The user started resizing a column - can be vetoed.
1045     @event{EVT_LIST_COL_DRAGGING(id, func)}
1046         The divider between columns is being dragged.
1047     @event{EVT_LIST_COL_END_DRAG(id, func)}
1048         A column has been resized by the user.
1049     @event{EVT_LIST_CACHE_HINT(id, func)}
1050         Prepare cache for a virtual list control
1051     @endEventTable
1052
1053
1054     @library{wxbase}
1055     @category{events}
1056
1057     @see wxListCtrl
1058 */
1059 class wxListEvent : public wxNotifyEvent
1060 {
1061 public:
1062     /**
1063         Constructor.
1064     */
1065     wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
1066
1067     /**
1068         For @c EVT_LIST_CACHE_HINT event only: return the first item which the
1069         list control advises us to cache.
1070     */
1071     long GetCacheFrom() const;
1072
1073     /**
1074         For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive)
1075         which the list control advises us to cache.
1076     */
1077     long GetCacheTo() const;
1078
1079     /**
1080         The column position: it is only used with @c COL events.
1081
1082         For the column dragging events, it is the column to the left of the divider
1083         being dragged, for the column click events it may be -1 if the user clicked
1084         in the list control header outside any column.
1085     */
1086     int GetColumn() const;
1087
1088     /**
1089         The data.
1090     */
1091     long GetData() const;
1092
1093     /**
1094         The image.
1095     */
1096     int GetImage() const;
1097
1098     /**
1099         The item index.
1100     */
1101     long GetIndex() const;
1102
1103     /**
1104         An item object, used by some events. See also wxListCtrl::SetItem.
1105     */
1106     const wxListItem& GetItem() const;
1107
1108     /**
1109         Key code if the event is a keypress event.
1110     */
1111     int GetKeyCode() const;
1112
1113     /**
1114         The (new) item label for @c EVT_LIST_END_LABEL_EDIT event.
1115     */
1116     const wxString& GetLabel() const;
1117
1118     /**
1119         The mask.
1120     */
1121     long GetMask() const;
1122
1123     /**
1124         The position of the mouse pointer if the event is a drag event.
1125     */
1126     wxPoint GetPoint() const;
1127
1128     /**
1129         The text.
1130     */
1131     const wxString& GetText() const;
1132
1133     /**
1134         This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message and
1135         returns @true if it the label editing has been cancelled by the user
1136         (GetLabel() returns an empty string in this case but it doesn't allow the
1137         application to distinguish between really cancelling the edit and the
1138         admittedly rare case when the user wants to rename it to an empty string).
1139     */
1140     bool IsEditCancelled() const;
1141 };
1142
1143
1144
1145 /**
1146     @class wxListItemAttr
1147
1148     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
1149
1150     @library{wxbase}
1151     @category{data}
1152
1153     @see @ref overview_listctrl, wxListCtrl, wxListItem
1154 */
1155 class wxListItemAttr
1156 {
1157 public:
1158     /**
1159         Default Constructor.
1160     */
1161     wxListItemAttr();
1162
1163     /**
1164         Construct a wxListItemAttr with the specified foreground and
1165         background colors and font.
1166     */
1167     wxListItemAttr(const wxColour& colText,
1168                    const wxColour& colBack,
1169                    const wxFont& font);
1170
1171     /**
1172         Returns the currently set background color.
1173     */
1174     const wxColour& GetBackgroundColour() const;
1175
1176     /**
1177         Returns the currently set font.
1178     */
1179     const wxFont& GetFont() const;
1180
1181     /**
1182         Returns the currently set text color.
1183     */
1184     const wxColour& GetTextColour() const;
1185
1186     /**
1187         Returns @true if the currently set background color is valid.
1188     */
1189     bool HasBackgroundColour() const;
1190
1191     /**
1192         Returns @true if the currently set font is valid.
1193     */
1194     bool HasFont() const;
1195
1196     /**
1197         Returns @true if the currently set text color is valid.
1198     */
1199     bool HasTextColour() const;
1200
1201     /**
1202         Sets a new background color.
1203     */
1204     void SetBackgroundColour(const wxColour& colour);
1205
1206     /**
1207         Sets a new font.
1208     */
1209     void SetFont(const wxFont& font);
1210
1211     /**
1212         Sets a new text color.
1213     */
1214     void SetTextColour(const wxColour& colour);
1215 };
1216
1217
1218
1219 /**
1220     @class wxListView
1221
1222     This class currently simply presents a simpler to use interface for the
1223     wxListCtrl -- it can be thought of as a @e façade for that complicated class.
1224
1225     Using it is preferable to using wxListCtrl directly whenever possible because
1226     in the future some ports might implement wxListView but not the full set of
1227     wxListCtrl features.
1228
1229     Other than different interface, this class is identical to wxListCtrl.
1230     In particular, it uses the same events, same window styles and so on.
1231
1232     @library{wxcore}
1233     @category{ctrl}
1234     @appearance{listview.png}
1235
1236     @see wxListView::SetColumnImage
1237 */
1238 class wxListView : public wxListCtrl
1239 {
1240 public:
1241     /**
1242         Resets the column image -- after calling this function, no image will be shown.
1243
1244         @param col
1245             the column to clear image for
1246
1247         @see SetColumnImage()
1248     */
1249     void ClearColumnImage(int col);
1250
1251     /**
1252         Sets focus to the item with the given @a index.
1253     */
1254     void Focus(long index);
1255
1256     /**
1257         Returns the first selected item in a (presumably) multiple selection control.
1258         Together with GetNextSelected() it can be used to iterate over all selected
1259         items in the control.
1260
1261         @return The first selected item, if any, -1 otherwise.
1262     */
1263     long GetFirstSelected() const;
1264
1265     /**
1266         Returns the currently focused item or -1 if none.
1267
1268         @see IsSelected(), Focus()
1269     */
1270     long GetFocusedItem() const;
1271
1272     /**
1273         Used together with GetFirstSelected() to iterate over all selected items
1274         in the control.
1275
1276         @return Returns the next selected item or -1 if there are no more of them.
1277     */
1278     long GetNextSelected(long item) const;
1279
1280     /**
1281         Returns @true if the item with the given @a index is selected,
1282         @false otherwise.
1283
1284         @see GetFirstSelected(), GetNextSelected()
1285     */
1286     bool IsSelected(long index) const;
1287
1288     /**
1289         Selects or unselects the given item.
1290
1291         @param n
1292             the item to select or unselect
1293         @param on
1294             if @true (default), selects the item, otherwise unselects it
1295
1296         @see wxListCtrl::SetItemState
1297     */
1298     void Select(long n, bool on = true);
1299
1300     /**
1301         Sets the column image for the specified column.
1302         To use the column images, the control must have a valid image list with
1303         at least one image.
1304
1305         @param col
1306             the column to set image for
1307         @param image
1308             the index of the column image in the controls image list
1309     */
1310     void SetColumnImage(int col, int image);
1311 };
1312
1313
1314 /**
1315     Column format (MSW only except wxLIST_FORMAT_LEFT).
1316 */
1317 enum wxListColumnFormat
1318 {
1319     wxLIST_FORMAT_LEFT,
1320     wxLIST_FORMAT_RIGHT,
1321     wxLIST_FORMAT_CENTRE,
1322     wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE
1323 };
1324
1325 /**
1326     @class wxListItem
1327
1328     This class stores information about a wxListCtrl item or column.
1329
1330     wxListItem is a class which contains informations about:
1331     - Zero based item position; see SetId() and GetId().
1332     - Zero based column index; see SetColumn() and GetColumn().
1333     - The label (or header for columns); see SetText() and GetText().
1334     - The zero based index into an image list; see GetImage() and SetImage().
1335     - Application defined data; see SetData() and GetData().
1336     - For columns only: the width of the column; see SetWidth() and GetWidth().
1337     - For columns only: the format of the column; one of @c wxLIST_FORMAT_LEFT,
1338       @c wxLIST_FORMAT_RIGHT, @c wxLIST_FORMAT_CENTRE. See SetAlign() and GetAlign().
1339     - The state of the item; see SetState() and GetState().
1340       This is a bitlist of the following flags:
1341         - @c wxLIST_STATE_FOCUSED: The item has the focus.
1342         - @c wxLIST_STATE_SELECTED: The item is selected.
1343         - @c wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1344         - @c wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1345         - @c wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1346     - A mask indicating which state flags are valid; this is a bitlist of the
1347       flags reported above for the item state. See SetStateMask() and GetStateMask().
1348     - A mask indicating which fields of this class are valid; see SetMask() and GetMask().
1349       This is a bitlist of the following flags:
1350         - @c wxLIST_MASK_STATE: The state field is valid.
1351         - @c wxLIST_MASK_TEXT: The label field is valid.
1352         - @c wxLIST_MASK_IMAGE: The image field is valid.
1353         - @c wxLIST_MASK_DATA: The application-defined data field is valid.
1354         - @c wxLIST_MASK_WIDTH: The column width field is valid.
1355         - @c wxLIST_MASK_FORMAT: The column format field is valid.
1356
1357     The wxListItem object can also contain item-specific colour and font
1358     information: for this you need to call one of SetTextColour(), SetBackgroundColour()
1359     or SetFont() functions on it passing it the colour/font to use.
1360     If the colour/font is not specified, the default list control colour/font is used.
1361
1362     @library{wxbase}
1363     @category{data}
1364
1365     @see wxListCtrl
1366 */
1367 class wxListItem : public wxObject
1368 {
1369 public:
1370     /**
1371         Constructor.
1372     */
1373     wxListItem();
1374
1375     /**
1376         Resets the item state to the default.
1377     */
1378     void Clear();
1379
1380     /**
1381         Returns the alignment for this item.
1382         Can be one of @c wxLIST_FORMAT_LEFT, @c wxLIST_FORMAT_RIGHT or @c wxLIST_FORMAT_CENTRE.
1383     */
1384     wxListColumnFormat GetAlign() const;
1385
1386     /**
1387         Returns the background colour for this item.
1388     */
1389     wxColour GetBackgroundColour() const;
1390
1391     /**
1392         Returns the zero-based column; meaningful only in report mode.
1393     */
1394     int GetColumn() const;
1395
1396     /**
1397         Returns client data associated with the control.
1398         Please note that client data is associated with the item and not with subitems.
1399     */
1400     wxUIntPtr GetData() const;
1401
1402     /**
1403         Returns the font used to display the item.
1404     */
1405     wxFont GetFont() const;
1406
1407     /**
1408         Returns the zero-based item position.
1409     */
1410     long GetId() const;
1411
1412     /**
1413         Returns the zero-based index of the image associated with the item into
1414         the image list.
1415     */
1416     int GetImage() const;
1417
1418     /**
1419         Returns a bit mask indicating which fields of the structure are valid.
1420
1421         Can be any combination of the following values:
1422         - wxLIST_MASK_STATE: @b GetState is valid.
1423         - wxLIST_MASK_TEXT: @b GetText is valid.
1424         - wxLIST_MASK_IMAGE: @b GetImage is valid.
1425         - wxLIST_MASK_DATA: @b GetData is valid.
1426         - wxLIST_MASK_WIDTH: @b GetWidth is valid.
1427         - wxLIST_MASK_FORMAT: @b GetFormat is valid.
1428     */
1429     long GetMask() const;
1430
1431     /**
1432         Returns a bit field representing the state of the item.
1433
1434         Can be any combination of:
1435         - wxLIST_STATE_DONTCARE: Don't care what the state is. Win32 only.
1436         - wxLIST_STATE_DROPHILITED: The item is highlighted to receive a drop event. Win32 only.
1437         - wxLIST_STATE_FOCUSED: The item has the focus.
1438         - wxLIST_STATE_SELECTED: The item is selected.
1439         - wxLIST_STATE_CUT: The item is in the cut state. Win32 only.
1440     */
1441     long GetState() const;
1442
1443     /**
1444         Returns the label/header text.
1445     */
1446     const wxString& GetText() const;
1447
1448     /**
1449         Returns the text colour.
1450     */
1451     wxColour GetTextColour() const;
1452
1453     /**
1454         Meaningful only for column headers in report mode. Returns the column width.
1455     */
1456     int GetWidth() const;
1457
1458     /**
1459         Sets the alignment for the item. See also GetAlign()
1460     */
1461     void SetAlign(wxListColumnFormat align);
1462
1463     /**
1464         Sets the background colour for the item.
1465     */
1466     void SetBackgroundColour(const wxColour& colBack);
1467
1468     /**
1469         Sets the zero-based column. Meaningful only in report mode.
1470     */
1471     void SetColumn(int col);
1472
1473     //@{
1474     /**
1475         Sets client data for the item.
1476         Please note that client data is associated with the item and not with subitems.
1477     */
1478     void SetData(long data);
1479     void SetData(void* data);
1480     //@}
1481
1482     /**
1483         Sets the font for the item.
1484     */
1485     void SetFont(const wxFont& font);
1486
1487     /**
1488         Sets the zero-based item position.
1489     */
1490     void SetId(long id);
1491
1492     /**
1493         Sets the zero-based index of the image associated with the item
1494         into the image list.
1495     */
1496     void SetImage(int image);
1497
1498     /**
1499         Sets the mask of valid fields. See GetMask().
1500     */
1501     void SetMask(long mask);
1502
1503     /**
1504         Sets the item state flags (note that the valid state flags are influenced
1505         by the value of the state mask, see wxListItem::SetStateMask).
1506
1507         See GetState() for valid flag values.
1508     */
1509     void SetState(long state);
1510
1511     /**
1512         Sets the bitmask that is used to determine which of the state flags
1513         are to be set. See also SetState().
1514     */
1515     void SetStateMask(long stateMask);
1516
1517     /**
1518         Sets the text label for the item.
1519     */
1520     void SetText(const wxString& text);
1521
1522     /**
1523         Sets the text colour for the item.
1524     */
1525     void SetTextColour(const wxColour& colText);
1526
1527     /**
1528         Meaningful only for column headers in report mode. Sets the column width.
1529     */
1530     void SetWidth(int width);
1531 };
1532