interface/wx/listctrl.h

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