interface/wx/listctrl.h

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