interface/listctrl.h

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