include/wx/mac/carbon/listctrl.h

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