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      - testing of whole API, extending current sample.
  73
  74
  75  */
  76
  77 // Mask flags to tell app/GUI what fields of wxListItem are valid
  78 #define wxLIST_MASK_STATE           0x0001
  79 #define wxLIST_MASK_TEXT            0x0002
  80 #define wxLIST_MASK_IMAGE           0x0004
  81 #define wxLIST_MASK_DATA            0x0008
  82 #define wxLIST_SET_ITEM             0x0010
  83 #define wxLIST_MASK_WIDTH           0x0020
  84 #define wxLIST_MASK_FORMAT          0x0040
  85
  86 // State flags for indicating the state of an item
  87 #define wxLIST_STATE_DONTCARE       0x0000
  88 #define wxLIST_STATE_DROPHILITED    0x0001
  89 #define wxLIST_STATE_FOCUSED        0x0002
  90 #define wxLIST_STATE_SELECTED       0x0004
  91 #define wxLIST_STATE_CUT            0x0008
  92
  93 // Hit test flags, used in HitTest
  94 #define wxLIST_HITTEST_ABOVE            0x0001  // Above the client area.
  95 #define wxLIST_HITTEST_BELOW            0x0002  // Below the client area.
  96 #define wxLIST_HITTEST_NOWHERE          0x0004  // In the client area but below the last item.
  97 #define wxLIST_HITTEST_ONITEMICON       0x0020  // On the bitmap associated with an item.
  98 #define wxLIST_HITTEST_ONITEMLABEL      0x0080  // On the label (string) associated with an item.
  99 #define wxLIST_HITTEST_ONITEMRIGHT      0x0100  // In the area to the right of an item.
 100 #define wxLIST_HITTEST_ONITEMSTATEICON  0x0200  // On the state icon for a tree view item that is in a user-defined state.
 101 #define wxLIST_HITTEST_TOLEFT           0x0400  // To the left of the client area.
 102 #define wxLIST_HITTEST_TORIGHT          0x0800  // To the right of the client area.
 103
 104 #define wxLIST_HITTEST_ONITEM (wxLIST_HITTEST_ONITEMICON | wxLIST_HITTEST_ONITEMLABEL | wxLIST_HITTEST_ONITEMSTATEICON)
 105
 106 // Flags for GetNextItem
 107 enum {
 108     wxLIST_NEXT_ABOVE,          // Searches for an item above the specified item
 109     wxLIST_NEXT_ALL,            // Searches for subsequent item by index
 110     wxLIST_NEXT_BELOW,          // Searches for an item below the specified item
 111     wxLIST_NEXT_LEFT,           // Searches for an item to the left of the specified item
 112     wxLIST_NEXT_RIGHT,          // Searches for an item to the right of the specified item
 113 };
 114
 115 // Alignment flags for Arrange
 116 enum {
 117     wxLIST_ALIGN_DEFAULT,
 118     wxLIST_ALIGN_LEFT,
 119     wxLIST_ALIGN_TOP,
 120     wxLIST_ALIGN_SNAP_TO_GRID
 121 };
 122
 123 // Column format
 124 enum {
 125     wxLIST_FORMAT_LEFT,
 126     wxLIST_FORMAT_RIGHT,
 127     wxLIST_FORMAT_CENTRE,
 128     wxLIST_FORMAT_CENTER = wxLIST_FORMAT_CENTRE
 129 };
 130
 131 // Autosize values for SetColumnWidth
 132 enum {
 133     wxLIST_AUTOSIZE = -1,
 134     wxLIST_AUTOSIZE_USEHEADER = -2
 135 };
 136
 137 // Flag values for GetItemRect
 138 enum {
 139     wxLIST_RECT_BOUNDS,
 140     wxLIST_RECT_ICON,
 141     wxLIST_RECT_LABEL
 142 };
 143
 144 // Flag values for FindItem
 145 enum {
 146     wxLIST_FIND_UP,
 147     wxLIST_FIND_DOWN,
 148     wxLIST_FIND_LEFT,
 149     wxLIST_FIND_RIGHT
 150 };
 151
 152 // wxListItem: data representing an item, or report field.
 153 // It also doubles up to represent entire column information
 154 // when inserting or setting a column.
 155 class WXDLLEXPORT wxListItem: public wxObject
 156 {
 157  DECLARE_DYNAMIC_CLASS(wxListItem)
 158 public:
 159     long            m_mask;     // Indicates what fields are valid
 160     long            m_itemId;   // The zero-based item position
 161     int             m_col;      // Zero-based column, if in report mode
 162     long            m_state;    // The state of the item
 163     long            m_stateMask; // Which flags of m_state are valid (uses same flags)
 164     wxString        m_text;     // The label/header text
 165     int             m_image;    // The zero-based index into an image list
 166     long            m_data;     // App-defined data
 167
 168     // For columns only
 169     int             m_format;   // left, right, centre
 170     int             m_width;    // width of column
 171
 172     wxListItem();
 173 };
 174
 175 // type of compare function for wxListCtrl sort operation
 176 typedef int (*wxListCtrlCompare)(long item1, long item2, long sortData);
 177
 178 class WXDLLEXPORT wxListCtrl: public wxControl
 179 {
 180   DECLARE_DYNAMIC_CLASS(wxListCtrl)
 181  public:
 182   /*
 183    * Public interface
 184    */
 185
 186   wxListCtrl();
 187
 188   inline wxListCtrl(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
 189             long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator,
 190             const wxString& name = "listCtrl")
 191   {
 192     Create(parent, id, pos, size, style, validator, name);
 193   }
 194   ~wxListCtrl();
 195
 196   bool Create(wxWindow *parent, wxWindowID id = -1, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize,
 197             long style = wxLC_ICON, const wxValidator& validator = wxDefaultValidator, const wxString& name = "wxListCtrl");
 198
 199
 200   // Attributes
 201   ////////////////////////////////////////////////////////////////////////////
 202
 203   // Sets the background colour (GetBackgroundColour already implicit in
 204   // wxWindow class)
 205   bool SetBackgroundColour(const wxColour& col);
 206
 207   // Gets information about this column
 208   bool GetColumn(int col, wxListItem& item) const;
 209
 210   // Sets information about this column
 211   bool SetColumn(int col, wxListItem& item) ;
 212
 213   // Gets the column width
 214   int GetColumnWidth(int col) const;
 215
 216   // Sets the column width
 217   bool SetColumnWidth(int col, int width) ;
 218
 219   // Gets the number of items that can fit vertically in the
 220   // visible area of the list control (list or report view)
 221   // or the total number of items in the list control (icon
 222   // or small icon view)
 223   int GetCountPerPage() const;
 224
 225   // Gets the edit control for editing labels.
 226   wxTextCtrl* GetEditControl() const;
 227
 228   // Gets information about the item
 229   bool GetItem(wxListItem& info) const ;
 230
 231   // Sets information about the item
 232   bool SetItem(wxListItem& info) ;
 233
 234   // Sets a string field at a particular column
 235   long SetItem(long index, int col, const wxString& label, int imageId = -1);
 236
 237   // Gets the item state
 238   int  GetItemState(long item, long stateMask) const ;
 239
 240   // Sets the item state
 241   bool SetItemState(long item, long state, long stateMask) ;
 242
 243   // Sets the item image
 244   bool SetItemImage(long item, int image, int selImage) ;
 245
 246   // Gets the item text
 247   wxString GetItemText(long item) const ;
 248
 249   // Sets the item text
 250   void SetItemText(long item, const wxString& str) ;
 251
 252   // Gets the item data
 253   long GetItemData(long item) const ;
 254
 255   // Sets the item data
 256   bool SetItemData(long item, long data) ;
 257
 258   // Gets the item rectangle
 259   bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
 260
 261   // Gets the item position
 262   bool GetItemPosition(long item, wxPoint& pos) const ;
 263
 264   // Sets the item position
 265   bool SetItemPosition(long item, const wxPoint& pos) ;
 266
 267   // Gets the number of items in the list control
 268   int GetItemCount() const;
 269
 270   // Gets the number of columns in the list control
 271   int GetColumnCount() const { return m_colCount; }
 272
 273   // Retrieves the spacing between icons in pixels.
 274   // If small is TRUE, gets the spacing for the small icon
 275   // view, otherwise the large icon view.
 276   int GetItemSpacing(bool isSmall) const;
 277
 278   // Gets the number of selected items in the list control
 279   int GetSelectedItemCount() const;
 280
 281   // Gets the text colour of the listview
 282   wxColour GetTextColour() const;
 283
 284   // Sets the text colour of the listview
 285   void SetTextColour(const wxColour& col);
 286
 287   // Gets the index of the topmost visible item when in
 288   // list or report view
 289   long GetTopItem() const ;
 290
 291   // Add or remove a single window style
 292   void SetSingleStyle(long style, bool add = TRUE) ;
 293
 294   // Set the whole window style
 295   void SetWindowStyleFlag(long style) ;
 296
 297   // Searches for an item, starting from 'item'.
 298   // item can be -1 to find the first item that matches the
 299   // specified flags.
 300   // Returns the item or -1 if unsuccessful.
 301   long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
 302
 303   // Implementation: converts wxWindows style to MSW style.
 304   // Can be a single style flag or a bit list.
 305   // oldStyle is 'normalised' so that it doesn't contain
 306   // conflicting styles.
 307   long ConvertToMSWStyle(long& oldStyle, long style) const;
 308
 309   // Gets one of the three image lists
 310   wxImageList *GetImageList(int which) const ;
 311
 312   // Sets the image list
 313   // N.B. There's a quirk in the Win95 list view implementation.
 314   // If in wxLC_LIST mode, it'll *still* display images by the labels if
 315   // there's a small-icon image list set for the control - even though you
 316   // haven't specified wxLIST_MASK_IMAGE when inserting.
 317   // So you have to set a NULL small-icon image list to be sure that
 318   // the wxLC_LIST mode works without icons. Of course, you may want icons...
 319   void SetImageList(wxImageList *imageList, int which) ;
 320
 321   // Operations
 322   ////////////////////////////////////////////////////////////////////////////
 323
 324   // Arranges the items
 325   bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 326
 327   // Deletes an item
 328   bool DeleteItem(long item);
 329
 330   // Deletes all items
 331   bool DeleteAllItems() ;
 332
 333   // Deletes a column
 334   bool DeleteColumn(int col);
 335
 336   // Deletes all columns
 337   bool DeleteAllColumns();
 338
 339   // Clears items, and columns if there are any.
 340   void ClearAll();
 341
 342   // Edit the label
 343   wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 344
 345   // End label editing, optionally cancelling the edit
 346   bool EndEditLabel(bool cancel);
 347
 348   // Ensures this item is visible
 349   bool EnsureVisible(long item) ;
 350
 351   // Find an item whose label matches this string, starting from the item after 'start'
 352   // or the beginning if 'start' is -1.
 353   long FindItem(long start, const wxString& str, bool partial = FALSE);
 354
 355   // Find an item whose data matches this data, starting from the item after 'start'
 356   // or the beginning if 'start' is -1.
 357   long FindItem(long start, long data);
 358
 359   // Find an item nearest this position in the specified direction, starting from
 360   // the item after 'start' or the beginning if 'start' is -1.
 361   long FindItem(long start, const wxPoint& pt, int direction);
 362
 363   // Determines which item (if any) is at the specified point,
 364   // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 365   long HitTest(const wxPoint& point, int& flags);
 366
 367   // Inserts an item, returning the index of the new item if successful,
 368   // -1 otherwise.
 369   // TOD: Should also have some further convenience functions
 370   // which don't require setting a wxListItem object
 371   long InsertItem(wxListItem& info);
 372
 373   // Insert a string item
 374   long InsertItem(long index, const wxString& label);
 375
 376   // Insert an image item
 377   long InsertItem(long index, int imageIndex);
 378
 379   // Insert an image/string item
 380   long InsertItem(long index, const wxString& label, int imageIndex);
 381
 382   // For list view mode (only), inserts a column.
 383   long InsertColumn(long col, wxListItem& info);
 384
 385   long InsertColumn(long col, const wxString& heading, int format = wxLIST_FORMAT_LEFT,
 386     int width = -1);
 387
 388   // Scrolls the list control. If in icon, small icon or report view mode,
 389   // x specifies the number of pixels to scroll. If in list view mode, x
 390   // specifies the number of columns to scroll.
 391   // If in icon, small icon or list view mode, y specifies the number of pixels
 392   // to scroll. If in report view mode, y specifies the number of lines to scroll.
 393   bool ScrollList(int dx, int dy);
 394
 395   // Sort items.
 396
 397   // fn is a function which takes 3 long arguments: item1, item2, data.
 398   // item1 is the long data associated with a first item (NOT the index).
 399   // item2 is the long data associated with a second item (NOT the index).
 400   // data is the same value as passed to SortItems.
 401   // The return value is a negative number if the first item should precede the second
 402   // item, a positive number of the second item should precede the first,
 403   // or zero if the two items are equivalent.
 404
 405   // data is arbitrary data to be passed to the sort function.
 406   bool SortItems(wxListCtrlCompare fn, long data);
 407
 408   // IMPLEMENTATION
 409   virtual bool MSWCommand(WXUINT param, WXWORD id);
 410   virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 411
 412   // bring the control in sync with current m_windowStyle value
 413   void UpdateStyle();
 414
 415   // Add to pool: necessary because Windows needs to have a string
 416   // still exist across 3 callbacks.
 417   wxChar *AddPool(const wxString& str);
 418
 419 protected:
 420   wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 421   wxImageList *     m_imageListNormal; // The image list for normal icons
 422   wxImageList *     m_imageListSmall;  // The image list for small icons
 423   wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 424
 425   long              m_baseStyle;  // Basic Windows style flags, for recreation purposes
 426   wxStringList      m_stringPool; // Pool of 3 strings to satisfy Windows callback
 427                                   // requirements
 428   int               m_colCount;   // Windows doesn't have GetColumnCount so must
 429                                   // keep track of inserted/deleted columns
 430
 431 private:
 432   bool DoCreateControl(int x, int y, int w, int h);
 433 };
 434
 435 class WXDLLEXPORT wxListEvent : public wxNotifyEvent
 436 {
 437 public:
 438   wxListEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
 439
 440   int           m_code;
 441   long          m_itemIndex;
 442   long          m_oldItemIndex;
 443   int           m_col;
 444   bool          m_cancelled;
 445   wxPoint       m_pointDrag;
 446
 447   wxListItem    m_item;
 448
 449   DECLARE_DYNAMIC_CLASS(wxListEvent)
 450 };
 451
 452 typedef void (wxEvtHandler::*wxListEventFunction)(wxListEvent&);
 453
 454 #define EVT_LIST_BEGIN_DRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_DRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 455 #define EVT_LIST_BEGIN_RDRAG(id, fn) { wxEVT_COMMAND_LIST_BEGIN_RDRAG, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 456 #define EVT_LIST_BEGIN_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_BEGIN_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 457 #define EVT_LIST_END_LABEL_EDIT(id, fn) { wxEVT_COMMAND_LIST_END_LABEL_EDIT, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 458 #define EVT_LIST_DELETE_ITEM(id, fn) { wxEVT_COMMAND_LIST_DELETE_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 459 #define EVT_LIST_DELETE_ALL_ITEMS(id, fn) { wxEVT_COMMAND_LIST_DELETE_ALL_ITEMS, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 460 #define EVT_LIST_GET_INFO(id, fn) { wxEVT_COMMAND_LIST_GET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 461 #define EVT_LIST_SET_INFO(id, fn) { wxEVT_COMMAND_LIST_SET_INFO, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 462 #define EVT_LIST_ITEM_SELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_SELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 463 #define EVT_LIST_ITEM_DESELECTED(id, fn) { wxEVT_COMMAND_LIST_ITEM_DESELECTED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 464 #define EVT_LIST_KEY_DOWN(id, fn) { wxEVT_COMMAND_LIST_KEY_DOWN, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 465 #define EVT_LIST_INSERT_ITEM(id, fn) { wxEVT_COMMAND_LIST_INSERT_ITEM, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 466 #define EVT_LIST_COL_CLICK(id, fn) { wxEVT_COMMAND_LIST_COL_CLICK, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, NULL },
 467 #define EVT_LIST_ITEM_ACTIVATED(id, fn) { wxEVT_COMMAND_LIST_ITEM_ACTIVATED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxListEventFunction) & fn, (wxObject *) NULL },
 468
 469 #endif
 470     // _WX_LISTCTRL_H_