interface/wx/listctrl.h

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