include/wx/msw/listctrl.h

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