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