include/wx/msw/listctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/msw/listctrl.h
   3 // Purpose:     wxListCtrl class
   4 // Author:      Julian Smart
   5 // Modified by: Agron Selimaj
   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 #include "wx/textctrl.h"
  16 #include "wx/dynarray.h"
  17 #include "wx/vector.h"
  18
  19 class wxMSWListItemData;
  20
  21 // define this symbol to indicate the availability of SetColumnsOrder() and
  22 // related functions
  23 #define wxHAS_LISTCTRL_COLUMN_ORDER
  24
  25 /*
  26     The wxListCtrl can show lists of items in four different modes:
  27     wxLC_LIST:   multicolumn list view, with optional small icons (icons could be
  28                  optional for some platforms). Columns are computed automatically,
  29                  i.e. you don't set columns as in wxLC_REPORT. In other words,
  30                  the list wraps, unlike a wxListBox.
  31     wxLC_REPORT: single or multicolumn report view (with optional header)
  32     wxLC_ICON:   large icon view, with optional labels
  33     wxLC_SMALL_ICON: small icon view, with optional labels
  34
  35     You can change the style dynamically, either with SetSingleStyle or
  36     SetWindowStyleFlag.
  37
  38     Further window styles:
  39
  40     wxLC_ALIGN_TOP          icons align to the top (default)
  41     wxLC_ALIGN_LEFT         icons align to the left
  42     wxLC_AUTOARRANGE        icons arrange themselves
  43     wxLC_USER_TEXT          the app provides label text on demand, except for column headers
  44     wxLC_EDIT_LABELS        labels are editable: app will be notified.
  45     wxLC_NO_HEADER          no header in report mode
  46     wxLC_NO_SORT_HEADER     can't click on header
  47     wxLC_SINGLE_SEL         single selection
  48     wxLC_SORT_ASCENDING     sort ascending (must still supply a comparison callback in SortItems)
  49     wxLC_SORT_DESCENDING    sort descending (ditto)
  50
  51     Items are referred to by their index (position in the list starting from zero).
  52
  53     Label text is supplied via insertion/setting functions and is stored by the
  54     control, unless the wxLC_USER_TEXT style has been specified, in which case
  55     the app will be notified when text is required (see sample).
  56
  57     Images are dealt with by (optionally) associating 3 image lists with the control.
  58     Zero-based indexes into these image lists indicate which image is to be used for
  59     which item. Each image in an image list can contain a mask, and can be made out
  60     of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
  61
  62     Notifications are passed via the wxWidgets 2.0 event system, or using virtual
  63     functions in wxWidgets 1.66.
  64
  65     See the sample wxListCtrl app for API usage.
  66
  67     TODO:
  68      - addition of further convenience functions
  69        to avoid use of wxListItem in some functions
  70      - state/overlay images: probably not needed.
  71      - in Win95, you can be called back to supply other information
  72        besides text, such as state information. This saves no memory
  73        and is probably superfluous to requirements.
  74      - testing of whole API, extending current sample.
  75
  76
  77  */
  78
  79 class WXDLLIMPEXP_CORE wxListCtrl: public wxListCtrlBase
  80 {
  81 public:
  82     /*
  83      * Public interface
  84      */
  85
  86     wxListCtrl() { Init(); }
  87
  88     wxListCtrl(wxWindow *parent,
  89                wxWindowID id = wxID_ANY,
  90                const wxPoint& pos = wxDefaultPosition,
  91                const wxSize& size = wxDefaultSize,
  92                long style = wxLC_ICON,
  93                const wxValidator& validator = wxDefaultValidator,
  94                const wxString& name = wxListCtrlNameStr)
  95     {
  96         Init();
  97
  98         Create(parent, id, pos, size, style, validator, name);
  99     }
 100
 101     virtual ~wxListCtrl();
 102
 103     bool Create(wxWindow *parent,
 104                 wxWindowID id = wxID_ANY,
 105                 const wxPoint& pos = wxDefaultPosition,
 106                 const wxSize& size = wxDefaultSize,
 107                 long style = wxLC_ICON,
 108                 const wxValidator& validator = wxDefaultValidator,
 109                 const wxString& name = wxListCtrlNameStr);
 110
 111
 112     // Attributes
 113     ////////////////////////////////////////////////////////////////////////////
 114
 115     // Set the control colours
 116     bool SetForegroundColour(const wxColour& col);
 117     bool SetBackgroundColour(const wxColour& col);
 118
 119     // Gets information about this column
 120     bool GetColumn(int col, wxListItem& item) const;
 121
 122     // Sets information about this column
 123     bool SetColumn(int col, const wxListItem& item);
 124
 125     // Gets the column width
 126     int GetColumnWidth(int col) const;
 127
 128     // Sets the column width
 129     bool SetColumnWidth(int col, int width);
 130
 131
 132     // Gets the column order from its index or index from its order
 133     int GetColumnOrder(int col) const;
 134     int GetColumnIndexFromOrder(int order) const;
 135
 136     // Gets the column order for all columns
 137     wxArrayInt GetColumnsOrder() const;
 138
 139     // Sets the column order for all columns
 140     bool SetColumnsOrder(const wxArrayInt& orders);
 141
 142
 143     // Gets the number of items that can fit vertically in the
 144     // visible area of the list control (list or report view)
 145     // or the total number of items in the list control (icon
 146     // or small icon view)
 147     int GetCountPerPage() const;
 148
 149     // return the total area occupied by all the items (icon/small icon only)
 150     wxRect GetViewRect() const;
 151
 152     // Gets the edit control for editing labels.
 153     wxTextCtrl* GetEditControl() const;
 154
 155     // Gets information about the item
 156     bool GetItem(wxListItem& info) const;
 157
 158     // Sets information about the item
 159     bool SetItem(wxListItem& info);
 160
 161     // Sets a string field at a particular column
 162     long SetItem(long index, int col, const wxString& label, int imageId = -1);
 163
 164     // Gets the item state
 165     int  GetItemState(long item, long stateMask) const;
 166
 167     // Sets the item state
 168     bool SetItemState(long item, long state, long stateMask);
 169
 170     // Sets the item image
 171     bool SetItemImage(long item, int image, int selImage = -1);
 172     bool SetItemColumnImage(long item, long column, int image);
 173
 174     // Gets the item text
 175     wxString GetItemText(long item, int col = 0) const;
 176
 177     // Sets the item text
 178     void SetItemText(long item, const wxString& str);
 179
 180     // Gets the item data
 181     wxUIntPtr GetItemData(long item) const;
 182
 183     // Sets the item data
 184     bool SetItemPtrData(long item, wxUIntPtr data);
 185     bool SetItemData(long item, long data) { return SetItemPtrData(item, data); }
 186
 187     // Gets the item rectangle
 188     bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const;
 189
 190     // Gets the subitem rectangle in report mode
 191     bool GetSubItemRect(long item, long subItem, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const;
 192
 193     // Gets the item position
 194     bool GetItemPosition(long item, wxPoint& pos) const;
 195
 196     // Sets the item position
 197     bool SetItemPosition(long item, const wxPoint& pos);
 198
 199     // Gets the number of items in the list control
 200     int GetItemCount() const;
 201
 202     // Gets the number of columns in the list control
 203     int GetColumnCount() const { return m_colCount; }
 204
 205     // get the horizontal and vertical components of the item spacing
 206     wxSize GetItemSpacing() const;
 207
 208     // Foreground colour of an item.
 209     void SetItemTextColour( long item, const wxColour& col);
 210     wxColour GetItemTextColour( long item ) const;
 211
 212     // Background colour of an item.
 213     void SetItemBackgroundColour( long item, const wxColour &col);
 214     wxColour GetItemBackgroundColour( long item ) const;
 215
 216     // Font of an item.
 217     void SetItemFont( long item, const wxFont &f);
 218     wxFont GetItemFont( long item ) const;
 219
 220     // Gets the number of selected items in the list control
 221     int GetSelectedItemCount() const;
 222
 223     // Gets the text colour of the listview
 224     wxColour GetTextColour() const;
 225
 226     // Sets the text colour of the listview
 227     void SetTextColour(const wxColour& col);
 228
 229     // Gets the index of the topmost visible item when in
 230     // list or report view
 231     long GetTopItem() const;
 232
 233     // Add or remove a single window style
 234     void SetSingleStyle(long style, bool add = true);
 235
 236     // Set the whole window style
 237     void SetWindowStyleFlag(long style);
 238
 239     // Searches for an item, starting from 'item'.
 240     // item can be -1 to find the first item that matches the
 241     // specified flags.
 242     // Returns the item or -1 if unsuccessful.
 243     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const;
 244
 245     // Gets one of the three image lists
 246     wxImageList *GetImageList(int which) const;
 247
 248     // Sets the image list
 249     // N.B. There's a quirk in the Win95 list view implementation.
 250     // If in wxLC_LIST mode, it'll *still* display images by the labels if
 251     // there's a small-icon image list set for the control - even though you
 252     // haven't specified wxLIST_MASK_IMAGE when inserting.
 253     // So you have to set a NULL small-icon image list to be sure that
 254     // the wxLC_LIST mode works without icons. Of course, you may want icons...
 255     void SetImageList(wxImageList *imageList, int which);
 256     void AssignImageList(wxImageList *imageList, int which);
 257
 258     // refresh items selectively (only useful for virtual list controls)
 259     void RefreshItem(long item);
 260     void RefreshItems(long itemFrom, long itemTo);
 261
 262     // Operations
 263     ////////////////////////////////////////////////////////////////////////////
 264
 265     // Arranges the items
 266     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 267
 268     // Deletes an item
 269     bool DeleteItem(long item);
 270
 271     // Deletes all items
 272     bool DeleteAllItems();
 273
 274     // Deletes a column
 275     bool DeleteColumn(int col);
 276
 277     // Deletes all columns
 278     bool DeleteAllColumns();
 279
 280     // Clears items, and columns if there are any.
 281     void ClearAll();
 282
 283     // Edit the label
 284     wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
 285
 286     // End label editing, optionally cancelling the edit
 287     bool EndEditLabel(bool cancel);
 288
 289     // Ensures this item is visible
 290     bool EnsureVisible(long item);
 291
 292     // Find an item whose label matches this string, starting from the item after 'start'
 293     // or the beginning if 'start' is -1.
 294     long FindItem(long start, const wxString& str, bool partial = false);
 295
 296     // Find an item whose data matches this data, starting from the item after 'start'
 297     // or the beginning if 'start' is -1.
 298     long FindItem(long start, wxUIntPtr data);
 299
 300     // Find an item nearest this position in the specified direction, starting from
 301     // the item after 'start' or the beginning if 'start' is -1.
 302     long FindItem(long start, const wxPoint& pt, int direction);
 303
 304     // Determines which item (if any) is at the specified point,
 305     // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 306     // Request the subitem number as well at the given coordinate.
 307     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 308
 309     // Inserts an item, returning the index of the new item if successful,
 310     // -1 otherwise.
 311     long InsertItem(const wxListItem& info);
 312
 313     // Insert a string item
 314     long InsertItem(long index, const wxString& label);
 315
 316     // Insert an image item
 317     long InsertItem(long index, int imageIndex);
 318
 319     // Insert an image/string item
 320     long InsertItem(long index, const wxString& label, int imageIndex);
 321
 322     // set the number of items in a virtual list control
 323     void SetItemCount(long count);
 324
 325     // Scrolls the list control. If in icon, small icon or report view mode,
 326     // x specifies the number of pixels to scroll. If in list view mode, x
 327     // specifies the number of columns to scroll.
 328     // If in icon, small icon or list view mode, y specifies the number of pixels
 329     // to scroll. If in report view mode, y specifies the number of lines to scroll.
 330     bool ScrollList(int dx, int dy);
 331
 332     // Sort items.
 333
 334     // fn is a function which takes 3 long arguments: item1, item2, data.
 335     // item1 is the long data associated with a first item (NOT the index).
 336     // item2 is the long data associated with a second item (NOT the index).
 337     // data is the same value as passed to SortItems.
 338     // The return value is a negative number if the first item should precede the second
 339     // item, a positive number of the second item should precede the first,
 340     // or zero if the two items are equivalent.
 341
 342     // data is arbitrary data to be passed to the sort function.
 343     bool SortItems(wxListCtrlCompare fn, wxIntPtr data);
 344
 345     // IMPLEMENTATION
 346     virtual bool MSWCommand(WXUINT param, WXWORD id);
 347     virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 348     virtual bool MSWShouldPreProcessMessage(WXMSG* msg);
 349
 350     // bring the control in sync with current m_windowStyle value
 351     void UpdateStyle();
 352
 353     // Event handlers
 354     ////////////////////////////////////////////////////////////////////////////
 355     // Necessary for drawing hrules and vrules, if specified
 356     void OnPaint(wxPaintEvent& event);
 357
 358
 359     virtual bool ShouldInheritColours() const { return false; }
 360
 361     virtual wxVisualAttributes GetDefaultAttributes() const
 362     {
 363         return GetClassDefaultAttributes(GetWindowVariant());
 364     }
 365
 366     static wxVisualAttributes
 367     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 368
 369
 370 #if WXWIN_COMPATIBILITY_2_6
 371     // obsolete stuff, for compatibility only -- don't use
 372     wxDEPRECATED( int GetItemSpacing(bool isSmall) const);
 373 #endif // WXWIN_COMPATIBILITY_2_6
 374
 375     // convert our styles to Windows
 376     virtual WXDWORD MSWGetStyle(long style, WXDWORD *exstyle) const;
 377
 378     // special Windows message handling
 379     virtual WXLRESULT MSWWindowProc(WXUINT nMsg,
 380                                     WXWPARAM wParam,
 381                                     WXLPARAM lParam);
 382
 383 protected:
 384     // common part of all ctors
 385     void Init();
 386
 387     // Implement constrained best size calculation.
 388     virtual int DoGetBestClientHeight(int width) const
 389         { return MSWGetBestViewRect(width, -1).y; }
 390     virtual int DoGetBestClientWidth(int height) const
 391         { return MSWGetBestViewRect(-1, height).x; }
 392
 393     wxSize MSWGetBestViewRect(int x, int y) const;
 394
 395     // Implement base class pure virtual methods.
 396     long DoInsertColumn(long col, const wxListItem& info);
 397
 398     // free memory taken by all internal data
 399     void FreeAllInternalData();
 400
 401     // get the internal data object for this item (may return NULL)
 402     wxMSWListItemData *MSWGetItemData(long item) const;
 403
 404     // get the item attribute, either by quering it for virtual control, or by
 405     // returning the one previously set using setter methods for a normal one
 406     wxListItemAttr *DoGetItemColumnAttr(long item, long column) const;
 407
 408
 409     wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 410     wxImageList *     m_imageListNormal; // The image list for normal icons
 411     wxImageList *     m_imageListSmall;  // The image list for small icons
 412     wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 413     bool              m_ownsImageListNormal,
 414                       m_ownsImageListSmall,
 415                       m_ownsImageListState;
 416
 417     int               m_colCount;   // Windows doesn't have GetColumnCount so must
 418                                     // keep track of inserted/deleted columns
 419     long              m_count;      // Keep track of item count to save calls to
 420                                     // ListView_GetItemCount
 421
 422     // all wxMSWListItemData objects we use
 423     wxVector<wxMSWListItemData *> m_internalData;
 424
 425     // true if we have any items with custom attributes
 426     bool m_hasAnyAttr;
 427
 428     // these functions are only used for virtual list view controls, i.e. the
 429     // ones with wxLC_VIRTUAL style
 430
 431     // return the text for the given column of the given item
 432     virtual wxString OnGetItemText(long item, long column) const;
 433
 434     // return the icon for the given item. In report view, OnGetItemImage will
 435     // only be called for the first column. See OnGetItemColumnImage for
 436     // details.
 437     virtual int OnGetItemImage(long item) const;
 438
 439     // return the icon for the given item and column.
 440     virtual int OnGetItemColumnImage(long item, long column) const;
 441
 442     // return the attribute for the item (may return NULL if none)
 443     virtual wxListItemAttr *OnGetItemAttr(long item) const;
 444
 445     // return the attribute for the given item and column (may return NULL if none)
 446     virtual wxListItemAttr *OnGetItemColumnAttr(long item, long WXUNUSED(column)) const
 447     {
 448         return OnGetItemAttr(item);
 449     }
 450
 451 private:
 452     // process NM_CUSTOMDRAW notification message
 453     WXLPARAM OnCustomDraw(WXLPARAM lParam);
 454
 455     // set the extended styles for the control (used by Create() and
 456     // UpdateStyle()), only should be called if InReportView()
 457     void MSWSetExListStyles();
 458
 459     // initialize the (already created) m_textCtrl with the associated HWND
 460     void InitEditControl(WXHWND hWnd);
 461
 462     // destroy m_textCtrl if it's currently valid and reset it to NULL
 463     void DeleteEditControl();
 464
 465     // Intercept Escape and Enter keys to avoid them being stolen from our
 466     // in-place editor control.
 467     void OnCharHook(wxKeyEvent& event);
 468
 469
 470     DECLARE_DYNAMIC_CLASS(wxListCtrl)
 471     DECLARE_EVENT_TABLE()
 472     wxDECLARE_NO_COPY_CLASS(wxListCtrl);
 473 };
 474
 475 #endif // _WX_LISTCTRL_H_