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