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