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 #if wxUSE_LISTCTRL
  16
  17 #include "wx/control.h"
  18 #include "wx/event.h"
  19 #include "wx/hash.h"
  20 #include "wx/textctrl.h"
  21
  22
  23 class WXDLLEXPORT wxImageList;
  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 WXDLLEXPORT wxListCtrl: public wxControl
  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     // Gets the number of items that can fit vertically in the
 132     // visible area of the list control (list or report view)
 133     // or the total number of items in the list control (icon
 134     // or small icon view)
 135     int GetCountPerPage() const;
 136
 137     // return the total area occupied by all the items (icon/small icon only)
 138     wxRect GetViewRect() const;
 139
 140     // Gets the edit control for editing labels.
 141     wxTextCtrl* GetEditControl() const;
 142
 143     // Gets information about the item
 144     bool GetItem(wxListItem& info) const ;
 145
 146     // Sets information about the item
 147     bool SetItem(wxListItem& info) ;
 148
 149     // Sets a string field at a particular column
 150     long SetItem(long index, int col, const wxString& label, int imageId = -1);
 151
 152     // Gets the item state
 153     int  GetItemState(long item, long stateMask) const ;
 154
 155     // Sets the item state
 156     bool SetItemState(long item, long state, long stateMask) ;
 157
 158     // Sets the item image
 159     bool SetItemImage(long item, int image, int selImage = -1) ;
 160     bool SetItemColumnImage(long item, long column, int image);
 161
 162     // Gets the item text
 163     wxString GetItemText(long item) const ;
 164
 165     // Sets the item text
 166     void SetItemText(long item, const wxString& str) ;
 167
 168     // Gets the item data
 169     wxUIntPtr GetItemData(long item) const ;
 170
 171     // Sets the item data
 172     bool SetItemData(long item, long data) ;
 173
 174     // Gets the item rectangle
 175     bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
 176
 177     // Gets the subitem rectangle in report mode
 178     bool GetSubItemRect(long item, long subItem, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
 179
 180     // Gets the item position
 181     bool GetItemPosition(long item, wxPoint& pos) const ;
 182
 183     // Sets the item position
 184     bool SetItemPosition(long item, const wxPoint& pos) ;
 185
 186     // Gets the number of items in the list control
 187     int GetItemCount() const;
 188
 189     // Gets the number of columns in the list control
 190     int GetColumnCount() const { return m_colCount; }
 191
 192     // get the horizontal and vertical components of the item spacing
 193     wxSize GetItemSpacing() const;
 194
 195     // Foreground colour of an item.
 196     void SetItemTextColour( long item, const wxColour& col);
 197     wxColour GetItemTextColour( long item ) const;
 198
 199     // Background colour of an item.
 200     void SetItemBackgroundColour( long item, const wxColour &col);
 201     wxColour GetItemBackgroundColour( long item ) const;
 202
 203     // Font of an item.
 204     void SetItemFont( long item, const wxFont &f);
 205     wxFont GetItemFont( long item ) const;
 206
 207     // Gets the number of selected items in the list control
 208     int GetSelectedItemCount() const;
 209
 210     // Gets the text colour of the listview
 211     wxColour GetTextColour() const;
 212
 213     // Sets the text colour of the listview
 214     void SetTextColour(const wxColour& col);
 215
 216     // Gets the index of the topmost visible item when in
 217     // list or report view
 218     long GetTopItem() const ;
 219
 220     // Add or remove a single window style
 221     void SetSingleStyle(long style, bool add = true) ;
 222
 223     // Set the whole window style
 224     void SetWindowStyleFlag(long style) ;
 225
 226     // Searches for an item, starting from 'item'.
 227     // item can be -1 to find the first item that matches the
 228     // specified flags.
 229     // Returns the item or -1 if unsuccessful.
 230     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
 231
 232     // Gets one of the three image lists
 233     wxImageList *GetImageList(int which) const ;
 234
 235     // Sets the image list
 236     // N.B. There's a quirk in the Win95 list view implementation.
 237     // If in wxLC_LIST mode, it'll *still* display images by the labels if
 238     // there's a small-icon image list set for the control - even though you
 239     // haven't specified wxLIST_MASK_IMAGE when inserting.
 240     // So you have to set a NULL small-icon image list to be sure that
 241     // the wxLC_LIST mode works without icons. Of course, you may want icons...
 242     void SetImageList(wxImageList *imageList, int which) ;
 243     void AssignImageList(wxImageList *imageList, int which) ;
 244
 245     // are we in report mode?
 246     bool InReportView() const { return HasFlag(wxLC_REPORT); }
 247
 248     // are we in virtual report mode?
 249     bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); }
 250
 251     // refresh items selectively (only useful for virtual list controls)
 252     void RefreshItem(long item);
 253     void RefreshItems(long itemFrom, long itemTo);
 254
 255     // Operations
 256     ////////////////////////////////////////////////////////////////////////////
 257
 258     // Arranges the items
 259     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 260
 261     // Deletes an item
 262     bool DeleteItem(long item);
 263
 264     // Deletes all items
 265     bool DeleteAllItems() ;
 266
 267     // Deletes a column
 268     bool DeleteColumn(int col);
 269
 270     // Deletes all columns
 271     bool DeleteAllColumns();
 272
 273     // Clears items, and columns if there are any.
 274     void ClearAll();
 275
 276     // Edit the label
 277     wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 278
 279     // End label editing, optionally cancelling the edit
 280     bool EndEditLabel(bool cancel);
 281
 282     // Ensures this item is visible
 283     bool EnsureVisible(long item) ;
 284
 285     // Find an item whose label matches this string, starting from the item after 'start'
 286     // or the beginning if 'start' is -1.
 287     long FindItem(long start, const wxString& str, bool partial = false);
 288
 289     // Find an item whose data matches this data, starting from the item after 'start'
 290     // or the beginning if 'start' is -1.
 291     long FindItem(long start, wxUIntPtr data);
 292
 293     // Find an item nearest this position in the specified direction, starting from
 294     // the item after 'start' or the beginning if 'start' is -1.
 295     long FindItem(long start, const wxPoint& pt, int direction);
 296
 297     // Determines which item (if any) is at the specified point,
 298     // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 299     // Request the subitem number as well at the given coordinate.
 300     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 301
 302     // Inserts an item, returning the index of the new item if successful,
 303     // -1 otherwise.
 304     long InsertItem(const wxListItem& info);
 305
 306     // Insert a string item
 307     long InsertItem(long index, const wxString& label);
 308
 309     // Insert an image item
 310     long InsertItem(long index, int imageIndex);
 311
 312     // Insert an image/string item
 313     long InsertItem(long index, const wxString& label, int imageIndex);
 314
 315     // For list view mode (only), inserts a column.
 316     long InsertColumn(long col, const wxListItem& info);
 317
 318     long InsertColumn(long col,
 319                       const wxString& heading,
 320                       int format = wxLIST_FORMAT_LEFT,
 321                       int width = -1);
 322
 323     // set the number of items in a virtual list control
 324     void SetItemCount(long count);
 325
 326     // Scrolls the list control. If in icon, small icon or report view mode,
 327     // x specifies the number of pixels to scroll. If in list view mode, x
 328     // specifies the number of columns to scroll.
 329     // If in icon, small icon or list view mode, y specifies the number of pixels
 330     // to scroll. If in report view mode, y specifies the number of lines to scroll.
 331     bool ScrollList(int dx, int dy);
 332
 333     // Sort items.
 334
 335     // fn is a function which takes 3 long arguments: item1, item2, data.
 336     // item1 is the long data associated with a first item (NOT the index).
 337     // item2 is the long data associated with a second item (NOT the index).
 338     // data is the same value as passed to SortItems.
 339     // The return value is a negative number if the first item should precede the second
 340     // item, a positive number of the second item should precede the first,
 341     // or zero if the two items are equivalent.
 342
 343     // data is arbitrary data to be passed to the sort function.
 344     bool SortItems(wxListCtrlCompare fn, long data);
 345
 346     // IMPLEMENTATION
 347     virtual bool MSWCommand(WXUINT param, WXWORD id);
 348     virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 349     virtual bool MSWShouldPreProcessMessage(WXMSG* msg);
 350
 351     // bring the control in sync with current m_windowStyle value
 352     void UpdateStyle();
 353
 354     // Event handlers
 355     ////////////////////////////////////////////////////////////////////////////
 356     // Necessary for drawing hrules and vrules, if specified
 357     void OnPaint(wxPaintEvent& event);
 358
 359
 360     virtual bool ShouldInheritColours() const { return false; }
 361
 362     virtual wxVisualAttributes GetDefaultAttributes() const
 363     {
 364         return GetClassDefaultAttributes(GetWindowVariant());
 365     }
 366
 367     static wxVisualAttributes
 368     GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
 369
 370
 371 #if WXWIN_COMPATIBILITY_2_6
 372     // obsolete stuff, for compatibility only -- don't use
 373     wxDEPRECATED( int GetItemSpacing(bool isSmall) const);
 374 #endif // WXWIN_COMPATIBILITY_2_6
 375
 376     // convert our styles to Windows
 377     virtual WXDWORD MSWGetStyle(long style, WXDWORD *exstyle) const;
 378
 379     // special Windows message handling
 380     virtual WXLRESULT MSWWindowProc(WXUINT nMsg,
 381                                     WXWPARAM wParam,
 382                                     WXLPARAM lParam);
 383
 384 protected:
 385     // common part of all ctors
 386     void Init();
 387
 388     // free memory taken by all internal data
 389     void FreeAllInternalData();
 390
 391     // get the item attribute, either by quering it for virtual control, or by
 392     // returning the one previously set using setter methods for a normal one
 393     wxListItemAttr *DoGetItemAttr(long item) const;
 394
 395
 396     wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 397     wxImageList *     m_imageListNormal; // The image list for normal icons
 398     wxImageList *     m_imageListSmall;  // The image list for small icons
 399     wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 400     bool              m_ownsImageListNormal,
 401                       m_ownsImageListSmall,
 402                       m_ownsImageListState;
 403
 404     int               m_colCount;   // Windows doesn't have GetColumnCount so must
 405                                     // keep track of inserted/deleted columns
 406     long              m_count;      // Keep track of item count to save calls to
 407                                     // ListView_GetItemCount
 408     bool              m_ignoreChangeMessages;
 409
 410     // true if we have any internal data (user data & attributes)
 411     bool m_AnyInternalData;
 412
 413     // true if we have any items with custom attributes
 414     bool m_hasAnyAttr;
 415
 416     // these functions are only used for virtual list view controls, i.e. the
 417     // ones with wxLC_VIRTUAL style
 418
 419     // return the text for the given column of the given item
 420     virtual wxString OnGetItemText(long item, long column) const;
 421
 422     // return the icon for the given item. In report view, OnGetItemImage will
 423     // only be called for the first column. See OnGetItemColumnImage for
 424     // details.
 425     virtual int OnGetItemImage(long item) const;
 426
 427     // return the icon for the given item and column.
 428     virtual int OnGetItemColumnImage(long item, long column) const;
 429
 430     // return the attribute for the item (may return NULL if none)
 431     virtual wxListItemAttr *OnGetItemAttr(long item) const;
 432
 433 private:
 434     // process NM_CUSTOMDRAW notification message
 435     WXLPARAM OnCustomDraw(WXLPARAM lParam);
 436
 437     DECLARE_DYNAMIC_CLASS(wxListCtrl)
 438     DECLARE_EVENT_TABLE()
 439     DECLARE_NO_COPY_CLASS(wxListCtrl)
 440 };
 441
 442 #endif // wxUSE_LISTCTRL
 443
 444 #endif // _WX_LISTCTRL_H_