interface/wx/listctrl.h

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