include/wx/stubs/listctrl.h

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