include/wx/msw/listctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        listctrl.h
   3 // Purpose:     wxListCtrl class
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     01/02/97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_LISTCTRL_H_
  13 #define _WX_LISTCTRL_H_
  14
  15 #ifdef __GNUG__
  16 #pragma interface "listctrl.h"
  17 #endif
  18
  19 #include "wx/control.h"
  20 #include "wx/event.h"
  21 #include "wx/imaglist.h"
  22
  23 /*
  24     The wxListCtrl can show lists of items in four different modes:
  25     wxLC_LIST:   multicolumn list view, with optional small icons (icons could be
  26                  optional for some platforms). Columns are computed automatically,
  27                  i.e. you don't set columns as in wxLC_REPORT. In other words,
  28                  the list wraps, unlike a wxListBox.
  29     wxLC_REPORT: single or multicolumn report view (with optional header)
  30     wxLC_ICON:   large icon view, with optional labels
  31     wxLC_SMALL_ICON: small icon view, with optional labels
  32
  33     You can change the style dynamically, either with SetSingleStyle or
  34     SetWindowStyleFlag.
  35
  36     Further window styles:
  37
  38     wxLC_ALIGN_TOP          icons align to the top (default)
  39     wxLC_ALIGN_LEFT         icons align to the left
  40     wxLC_AUTOARRANGE        icons arrange themselves
  41     wxLC_USER_TEXT          the app provides label text on demand, except for column headers
  42     wxLC_EDIT_LABELS        labels are editable: app will be notified.
  43     wxLC_NO_HEADER          no header in report mode
  44     wxLC_NO_SORT_HEADER     can't click on header
  45     wxLC_SINGLE_SEL         single selection
  46     wxLC_SORT_ASCENDING     sort ascending (must still supply a comparison callback in SortItems)
  47     wxLC_SORT_DESCENDING    sort descending (ditto)
  48
  49     Items are referred to by their index (position in the list starting from zero).
  50
  51     Label text is supplied via insertion/setting functions and is stored by the
  52     control, unless the wxLC_USER_TEXT style has been specified, in which case
  53     the app will be notified when text is required (see sample).
  54
  55     Images are dealt with by (optionally) associating 3 image lists with the control.
  56     Zero-based indexes into these image lists indicate which image is to be used for
  57     which item. Each image in an image list can contain a mask, and can be made out
  58     of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
  59
  60     Notifications are passed via the wxWindows 2.0 event system, or using virtual
  61     functions in wxWindows 1.66.
  62
  63     See the sample wxListCtrl app for API usage.
  64
  65     TODO:
  66      - addition of further convenience functions
  67        to avoid use of wxListItem in some functions
  68      - state/overlay images: probably not needed.
  69      - in Win95, you can be called back to supply other information
  70        besides text, such as state information. This saves no memory
  71        and is probably superfluous to requirements.
  72      - discover why SetWindowLong doesn't properly change the
  73        style, requiring RecreateWindow instead.
  74      - testing of whole API, extending current sample.
  75
  76
  77  */
  78
  79 // Mask flags to tell app/GUI what fields of wxListItem are valid
  80 #define wxLIST_MASK_STATE           0x0001
  81 #define wxLIST_MASK_TEXT            0x0002
  82 #define wxLIST_MASK_IMAGE           0x0004
  83 #define wxLIST_MASK_DATA            0x0008
  84 #define wxLIST_SET_ITEM             0x0010
  85 #define wxLIST_MASK_WIDTH           0x0020
  86 #define wxLIST_MASK_FORMAT          0x0040
  87
  88 // State flags for indicating the state of an item
  89 #define wxLIST_STATE_DONTCARE       0x0000
  90 #define wxLIST_STATE_DROPHILITED    0x0001
  91 #define wxLIST_STATE_FOCUSED        0x0002
  92 #define wxLIST_STATE_SELECTED       0x0004
  93 #define wxLIST_STATE_CUT            0x0008
  94
  95 // Hit test flags, used in HitTest
  96 #define wxLIST_HITTEST_ABOVE            0x0001  // Above the client area.
  97 #define wxLIST_HITTEST_BELOW            0x0002  // Below the client area.
  98 #define wxLIST_HITTEST_NOWHERE          0x0004  // In the client area but below the last item.
  99 #define wxLIST_HITTEST_ONITEMICON       0x0020  // On the bitmap associated with an item.
 100 #define wxLIST_HITTEST_ONITEMLABEL      0x0080  // On the label (string) associated with an item.
 101 #define wxLIST_HITTEST_ONITEMRIGHT      0x0100  // In the area to the right of an item.
 102 #define wxLIST_HITTEST_ONITEMSTATEICON  0x0200  // On the state icon for a tree view item that is in a user-defined state.
 103 #define wxLIST_HITTEST_TOLEFT           0x0400  // To the left of the client area.
 104 #define wxLIST_HITTEST_TORIGHT          0x0800  // To the right of the client area.
 105
 106 #define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON)
 107
 108 // Flags for GetNextItem
 109 enum {
 110     wxLIST_NEXT_ABOVE,          // Searches for an item above the specified item
 111     wxLIST_NEXT_ALL,            // Searches for subsequent item by index
 112     wxLIST_NEXT_BELOW,          // Searches for an item below the specified item
 113     wxLIST_NEXT_LEFT,           // Searches for an item to the left of the specified item
 114     wxLIST_NEXT_RIGHT,          // Searches for an item to the right of the specified item
 115 };
 116
 117 // Alignment flags for Arrange
 118 enum {
 119     wxLIST_ALIGN_DEFAULT,
 120     wxLIST_ALIGN_LEFT,
 121     wxLIST_ALIGN_TOP,
 122     wxLIST_ALIGN_SNAP_TO_GRID
 123 };
 124
 125 // Column format
 126 enum {
 127     wxLIST_FORMAT_LEFT,
 128     wxLIST_FORMAT_RIGHT,
 129     wxLIST_FORMAT_CENTRE,
 130     wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE
 131 };
 132
 133 // Autosize values for SetColumnWidth
 134 enum {
 135     wxLIST_AUTOSIZE = -1,
 136     wxLIST_AUTOSIZE_USEHEADER = -2
 137 };
 138
 139 // Flag values for GetItemRect
 140 enum {
 141     wxLIST_RECT_BOUNDS,
 142     wxLIST_RECT_ICON,
 143     wxLIST_RECT_LABEL
 144 };
 145
 146 // Flag values for FindItem
 147 enum {
 148     wxLIST_FIND_UP,
 149     wxLIST_FIND_DOWN,
 150     wxLIST_FIND_LEFT,
 151     wxLIST_FIND_RIGHT
 152 };
 153
 154 // wxListItem: data representing an item, or report field.
 155 // It also doubles up to represent entire column information
 156 // when inserting or setting a column.
 157 class WXDLLEXPORT wxListItem: public wxObject
 158 {
 159  DECLARE_DYNAMIC_CLASS(wxListItem)
 160 public:
 161     long            m_mask;     // Indicates what fields are valid
 162     long            m_itemId;   // The zero-based item position
 163     int             m_col;      // Zero-based column, if in report mode
 164     long            m_state;    // The state of the item
 165     long            m_stateMask; // Which flags of m_state are valid (uses same flags)
 166     wxString        m_text;     // The label/header text
 167     int             m_image;    // The zero-based index into an image list
 168     long            m_data;     // App-defined data
 169
 170     // For columns only
 171     int             m_format;   // left, right, centre
 172     int             m_width;    // width of column
 173
 174     wxListItem();
 175 };
 176
 177 // type of compare function for wxListCtrl sort operation
 178 typedef int (*wxListCtrlCompare)(long item1, long item2, long sortData);
 179
 180 class WXDLLEXPORT wxListCtrl: public wxControl
 181 {
 182   DECLARE_DYNAMIC_CLASS(wxListCtrl)
 183  public:
 184   /*
 185    * Public interface
 186    */
 187
 188   wxListCtrl();
 189
 190   inline wxListCtrl(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
 191             long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator,
 192             const wxString& name = "listCtrl")
 193   {
 194     Create(parent, id, pos, size, style, validator, name);
 195   }
 196   ~wxListCtrl();
 197
 198   bool Create(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
 199             long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, const wxString& name = "wxListCtrl");
 200
 201
 202   // Attributes
 203   ////////////////////////////////////////////////////////////////////////////
 204
 205   // Sets the background colour (GetBackgroundColour already implicit in
 206   // wxWindow class)
 207   void SetBackgroundColour(const wxColour& col);
 208
 209   // Gets information about this column
 210   bool GetColumn(int col, wxListItem& item) const;
 211
 212   // Sets information about this column
 213   bool SetColumn(int col, wxListItem& item) ;
 214
 215   // Gets the column width
 216   int GetColumnWidth(int col) const;
 217
 218   // Sets the column width
 219   bool SetColumnWidth(int col, int width) ;
 220
 221   // Gets the number of items that can fit vertically in the
 222   // visible area of the list control (list or report view)
 223   // or the total number of items in the list control (icon
 224   // or small icon view)
 225   int GetCountPerPage() const;
 226
 227   // Gets the edit control for editing labels.
 228   wxTextCtrl* GetEditControl() const;
 229
 230   // Gets information about the item
 231   bool GetItem(wxListItem& info) const ;
 232
 233   // Sets information about the item
 234   bool SetItem(wxListItem& info) ;
 235
 236   // Sets a string field at a particular column
 237   long SetItem(long index, int col, const wxString& label, int imageId = -1);
 238
 239   // Gets the item state
 240   int  GetItemState(long item, long stateMask) const ;
 241
 242   // Sets the item state
 243   bool SetItemState(long item, long state, long stateMask) ;
 244
 245   // Sets the item image
 246   bool SetItemImage(long item, int image, int selImage) ;
 247
 248   // Gets the item text
 249   wxString GetItemText(long item) const ;
 250
 251   // Sets the item text
 252   void SetItemText(long item, const wxString& str) ;
 253
 254   // Gets the item data
 255   long GetItemData(long item) const ;
 256
 257   // Sets the item data
 258   bool SetItemData(long item, long data) ;
 259
 260   // Gets the item rectangle
 261   bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
 262
 263   // Gets the item position
 264   bool GetItemPosition(long item, wxPoint& pos) const ;
 265
 266   // Sets the item position
 267   bool SetItemPosition(long item, const wxPoint& pos) ;
 268
 269   // Gets the number of items in the list control
 270   int GetItemCount() const;
 271
 272   // Gets the number of columns in the list control
 273   int GetColumnCount() const { return m_colCount; }
 274
 275   // Retrieves the spacing between icons in pixels.
 276   // If small is TRUE, gets the spacing for the small icon
 277   // view, otherwise the large icon view.
 278   int GetItemSpacing(bool isSmall) const;
 279
 280   // Gets the number of selected items in the list control
 281   int GetSelectedItemCount() const;
 282
 283   // Gets the text colour of the listview
 284   wxColour GetTextColour() const;
 285
 286   // Sets the text colour of the listview
 287   void SetTextColour(const wxColour& col);
 288
 289   // Gets the index of the topmost visible item when in
 290   // list or report view
 291   long GetTopItem() const ;
 292
 293   // Add or remove a single window style
 294   void SetSingleStyle(long style, bool add = TRUE) ;
 295
 296   // Set the whole window style
 297   void SetWindowStyleFlag(long style) ;
 298
 299   // Searches for an item, starting from 'item'.
 300   // item can be -1 to find the first item that matches the
 301   // specified flags.
 302   // Returns the item or -1 if unsuccessful.
 303   long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
 304
 305   // Implementation: converts wxWindows style to MSW style.
 306   // Can be a single style flag or a bit list.
 307   // oldStyle is 'normalised' so that it doesn't contain
 308   // conflicting styles.
 309   long ConvertToMSWStyle(long& oldStyle, long style) const;
 310
 311   // Gets one of the three image lists
 312   wxImageList *GetImageList(int which) const ;
 313
 314   // Sets the image list
 315   // N.B. There's a quirk in the Win95 list view implementation.
 316   // If in wxLC_LIST mode, it'll *still* display images by the labels if
 317   // there's a small-icon image list set for the control - even though you
 318   // haven't specified wxLIST_MASK_IMAGE when inserting.
 319   // So you have to set a NULL small-icon image list to be sure that
 320   // the wxLC_LIST mode works without icons. Of course, you may want icons...
 321   void SetImageList(wxImageList *imageList, int which) ;
 322
 323   // Operations
 324   ////////////////////////////////////////////////////////////////////////////
 325
 326   // Arranges the items
 327   bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 328
 329   // Deletes an item
 330   bool DeleteItem(long item);
 331
 332   // Deletes all items
 333   bool DeleteAllItems() ;
 334
 335   // Deletes a column
 336   bool DeleteColumn(int col);
 337
 338   // Deletes all columns
 339   bool DeleteAllColumns();
 340
 341   // Clears items, and columns if there are any.
 342   void ClearAll();
 343
 344   // Edit the label
 345   wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 346
 347   // End label editing, optionally cancelling the edit
 348   bool EndEditLabel(bool cancel);
 349
 350   // Ensures this item is visible
 351   bool EnsureVisible(long item) ;
 352
 353   // Find an item whose label matches this string, starting from the item after 'start'
 354   // or the beginning if 'start' is -1.
 355   long FindItem(long start, const wxString& str, bool partial = FALSE);
 356
 357   // Find an item whose data matches this data, starting from the item after 'start'
 358   // or the beginning if 'start' is -1.
 359   long FindItem(long start, long data);
 360
 361   // Find an item nearest this position in the specified direction, starting from
 362   // the item after 'start' or the beginning if 'start' is -1.
 363   long FindItem(long start, const wxPoint& pt, int direction);
 364
 365   // Determines which item (if any) is at the specified point,
 366   // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 367   long HitTest(const wxPoint& point, int& flags);
 368
 369   // Inserts an item, returning the index of the new item if successful,
 370   // -1 otherwise.
 371   // TOD: Should also have some further convenience functions
 372   // which don't require setting a wxListItem object
 373   long InsertItem(wxListItem& info);
 374
 375   // Insert a string item
 376   long InsertItem(long index, const wxString& label);
 377
 378   // Insert an image item
 379   long InsertItem(long index, int imageIndex);
 380
 381   // Insert an image/string item
 382   long InsertItem(long index, const wxString& label, int imageIndex);
 383
 384   // For list view mode (only), inserts a column.
 385   long InsertColumn(long col, wxListItem& info);
 386
 387   long InsertColumn(long col, const wxString& heading, int format = wxLIST_FORMAT_LEFT,
 388     int width = -1);
 389
 390   // Scrolls the list control. If in icon, small icon or report view mode,
 391   // x specifies the number of pixels to scroll. If in list view mode, x
 392   // specifies the number of columns to scroll.
 393   // If in icon, small icon or list view mode, y specifies the number of pixels
 394   // to scroll. If in report view mode, y specifies the number of lines to scroll.
 395   bool ScrollList(int dx, int dy);
 396
 397   // Sort items.
 398
 399   // fn is a function which takes 3 long arguments: item1, item2, data.
 400   // item1 is the long data associated with a first item (NOT the index).
 401   // item2 is the long data associated with a second item (NOT the index).
 402   // data is the same value as passed to SortItems.
 403   // The return value is a negative number if the first item should precede the second
 404   // item, a positive number of the second item should precede the first,
 405   // or zero if the two items are equivalent.
 406
 407   // data is arbitrary data to be passed to the sort function.
 408   bool SortItems(wxListCtrlCompare fn, long data);
 409
 410 /* Why should we need this function? Leave for now.
 411  * WE NEED IT because item data may have changed,
 412  * but the display needs refreshing (in string callback mode)
 413   // Updates an item. If the list control has the wxLI_AUTO_ARRANGE style,
 414   // the items will be rearranged.
 415   bool Update(long item);
 416 */
 417
 418   void Command(wxCommandEvent& event) { ProcessCommand(event); };
 419
 420   // IMPLEMENTATION
 421   virtual bool MSWCommand(WXUINT param, WXWORD id);
 422   virtual bool MSWNotify(WXWPARAM wParam, WXLPARAM lParam, WXLPARAM *result);
 423
 424   // Recreate window - seems to be necessary when changing a style.
 425   void RecreateWindow();
 426
 427   // Add to pool: necessary because Windows needs to have a string
 428   // still exist across 3 callbacks.
 429   char *AddPool(const wxString& str);
 430
 431 protected:
 432   wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 433   wxImageList *     m_imageListNormal; // The image list for normal icons
 434   wxImageList *     m_imageListSmall;  // The image list for small icons
 435   wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 436
 437   long              m_baseStyle;  // Basic Windows style flags, for recreation purposes
 438   wxStringList      m_stringPool; // Pool of 3 strings to satisfy Windows callback
 439                                   // requirements
 440   int               m_colCount;   // Windows doesn't have GetColumnCount so must
 441                                   // keep track of inserted/deleted columns
 442
 443 };
 444
 445 class WXDLLEXPORT wxListEvent : public wxNotifyEvent
 446 {
 447 public:
 448   wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
 449
 450   int           m_code;
 451   long          m_itemIndex;
 452   long          m_oldItemIndex;
 453   int           m_col;
 454   bool          m_cancelled;
 455   wxPoint       m_pointDrag;
 456
 457   wxListItem    m_item;
 458
 459   DECLARE_DYNAMIC_CLASS(wxListEvent)
 460 };
 461
 462 typedef void (wxEvtHandler::*wxListEventFunction)(wxListEvent&);
 463
 464 #define EVT_LIST_BEGIN_DRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_DRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 465 #define EVT_LIST_BEGIN_RDRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_RDRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 466 #define EVT_LIST_BEGIN_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 467 #define EVT_LIST_END_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_END_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 468 #define EVT_LIST_DELETE_ITEM(id, fn) { wxEVT_COMMAND_LIST_DELETE_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 469 #define EVT_LIST_DELETE_ALL_ITEMS(id, fn) { wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 470 #define EVT_LIST_GET_INFO(id, fn) { wxEVT_COMMAND_LIST_GET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 471 #define EVT_LIST_SET_INFO(id, fn) { wxEVT_COMMAND_LIST_SET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 472 #define EVT_LIST_ITEM_SELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 473 #define EVT_LIST_ITEM_DESELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_DESELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 474 #define EVT_LIST_KEY_DOWN(id, fn) { wxEVT_COMMAND_LIST_KEY_DOWN, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 475 #define EVT_LIST_INSERT_ITEM(id, fn) { wxEVT_COMMAND_LIST_INSERT_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 476 #define EVT_LIST_COL_CLICK(id, fn) { wxEVT_COMMAND_LIST_COL_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 477 #define EVT_LIST_ITEM_ACTIVATED(id, fn) { wxEVT_COMMAND_LIST_ITEM_ACTIVATED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL },
 478
 479 #endif
 480     // _WX_LISTCTRL_H_