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