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