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