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