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 #ifdef __GNUG__
  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 wxWindows 2.0 event system, or using virtual
  67     functions in wxWindows 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 = -1,
  94                const wxPoint& pos = wxDefaultPosition,
  95                const wxSize& size = wxDefaultSize,
  96                long style = wxLC_ICON,
  97                const wxValidator& validator = wxDefaultValidator,
  98                const wxString& name = _T("wxListCtrl"))
  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 = -1,
 109                 const wxPoint& pos = wxDefaultPosition,
 110                 const wxSize& size = wxDefaultSize,
 111                 long style = wxLC_ICON,
 112                 const wxValidator& validator = wxDefaultValidator,
 113                 const wxString& name = _T("wxListCtrl"));
 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     // Gets the edit control for editing labels.
 142     wxTextCtrl* GetEditControl() const;
 143
 144     // Gets information about the item
 145     bool GetItem(wxListItem& info) const ;
 146
 147     // Sets information about the item
 148     bool SetItem(wxListItem& info) ;
 149
 150     // Sets a string field at a particular column
 151     long SetItem(long index, int col, const wxString& label, int imageId = -1);
 152
 153     // Gets the item state
 154     int  GetItemState(long item, long stateMask) const ;
 155
 156     // Sets the item state
 157     bool SetItemState(long item, long state, long stateMask) ;
 158
 159     // Sets the item image
 160     bool SetItemImage(long item, int image, int selImage) ;
 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     long 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 item position
 178     bool GetItemPosition(long item, wxPoint& pos) const ;
 179
 180     // Sets the item position
 181     bool SetItemPosition(long item, const wxPoint& pos) ;
 182
 183     // Gets the number of items in the list control
 184     int GetItemCount() const;
 185
 186     // Gets the number of columns in the list control
 187     int GetColumnCount() const { return m_colCount; }
 188
 189     // Retrieves the spacing between icons in pixels.
 190     // If small is TRUE, gets the spacing for the small icon
 191     // view, otherwise the large icon view.
 192     int GetItemSpacing(bool isSmall) const;
 193
 194     // Foreground colour of an item.
 195     void SetItemTextColour( long item, const wxColour& col);
 196     wxColour GetItemTextColour( long item ) const;
 197
 198     // Background colour of an item.
 199     void SetItemBackgroundColour( long item, const wxColour &col);
 200     wxColour GetItemBackgroundColour( 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     // returns true if it is a virtual list control
 241     bool IsVirtual() const { return (GetWindowStyle() & wxLC_VIRTUAL) != 0; }
 242
 243     // refresh items selectively (only useful for virtual list controls)
 244     void RefreshItem(long item);
 245     void RefreshItems(long itemFrom, long itemTo);
 246
 247     // Operations
 248     ////////////////////////////////////////////////////////////////////////////
 249
 250     // Arranges the items
 251     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 252
 253     // Deletes an item
 254     bool DeleteItem(long item);
 255
 256     // Deletes all items
 257     bool DeleteAllItems() ;
 258
 259     // Deletes a column
 260     bool DeleteColumn(int col);
 261
 262     // Deletes all columns
 263     bool DeleteAllColumns();
 264
 265     // Clears items, and columns if there are any.
 266     void ClearAll();
 267
 268     // Edit the label
 269     wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 270
 271     // End label editing, optionally cancelling the edit
 272     bool EndEditLabel(bool cancel);
 273
 274     // Ensures this item is visible
 275     bool EnsureVisible(long item) ;
 276
 277     // Find an item whose label matches this string, starting from the item after 'start'
 278     // or the beginning if 'start' is -1.
 279     long FindItem(long start, const wxString& str, bool partial = FALSE);
 280
 281     // Find an item whose data matches this data, starting from the item after 'start'
 282     // or the beginning if 'start' is -1.
 283     long FindItem(long start, long data);
 284
 285     // Find an item nearest this position in the specified direction, starting from
 286     // the item after 'start' or the beginning if 'start' is -1.
 287     long FindItem(long start, const wxPoint& pt, int direction);
 288
 289     // Determines which item (if any) is at the specified point,
 290     // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 291     long HitTest(const wxPoint& point, int& flags);
 292
 293     // Inserts an item, returning the index of the new item if successful,
 294     // -1 otherwise.
 295     long InsertItem(wxListItem& info);
 296
 297     // Insert a string item
 298     long InsertItem(long index, const wxString& label);
 299
 300     // Insert an image item
 301     long InsertItem(long index, int imageIndex);
 302
 303     // Insert an image/string item
 304     long InsertItem(long index, const wxString& label, int imageIndex);
 305
 306     // For list view mode (only), inserts a column.
 307     long InsertColumn(long col, wxListItem& info);
 308
 309     long InsertColumn(long col,
 310                       const wxString& heading,
 311                       int format = wxLIST_FORMAT_LEFT,
 312                       int width = -1);
 313
 314     // set the number of items in a virtual list control
 315     void SetItemCount(long count);
 316
 317     // Scrolls the list control. If in icon, small icon or report view mode,
 318     // x specifies the number of pixels to scroll. If in list view mode, x
 319     // specifies the number of columns to scroll.
 320     // If in icon, small icon or list view mode, y specifies the number of pixels
 321     // to scroll. If in report view mode, y specifies the number of lines to scroll.
 322     bool ScrollList(int dx, int dy);
 323
 324     // Sort items.
 325
 326     // fn is a function which takes 3 long arguments: item1, item2, data.
 327     // item1 is the long data associated with a first item (NOT the index).
 328     // item2 is the long data associated with a second item (NOT the index).
 329     // data is the same value as passed to SortItems.
 330     // The return value is a negative number if the first item should precede the second
 331     // item, a positive number of the second item should precede the first,
 332     // or zero if the two items are equivalent.
 333
 334     // data is arbitrary data to be passed to the sort function.
 335     bool SortItems(wxListCtrlCompare fn, long data);
 336
 337     // IMPLEMENTATION
 338     virtual bool MSWCommand(WXUINT param, WXWORD id);
 339     virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 340
 341     // bring the control in sync with current m_windowStyle value
 342     void UpdateStyle();
 343
 344     // Implementation: converts wxWindows style to MSW style.
 345     // Can be a single style flag or a bit list.
 346     // oldStyle is 'normalised' so that it doesn't contain
 347     // conflicting styles.
 348     long ConvertToMSWStyle(long& oldStyle, long style) const;
 349
 350     // Event handlers
 351     ////////////////////////////////////////////////////////////////////////////
 352     // Necessary for drawing hrules and vrules, if specified
 353     void OnPaint(wxPaintEvent& event);
 354
 355 protected:
 356     // common part of all ctors
 357     void Init();
 358
 359     // free memory taken by all attributes and recreate the hash table
 360     void FreeAllAttrs(bool dontRecreate = FALSE);
 361
 362     wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 363     wxImageList *     m_imageListNormal; // The image list for normal icons
 364     wxImageList *     m_imageListSmall;  // The image list for small icons
 365     wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 366     bool              m_ownsImageListNormal,
 367                       m_ownsImageListSmall,
 368                       m_ownsImageListState;
 369
 370     long              m_baseStyle;  // Basic Windows style flags, for recreation purposes
 371     int               m_colCount;   // Windows doesn't have GetColumnCount so must
 372                                     // keep track of inserted/deleted columns
 373
 374     // the hash table we use for storing pointers to the items attributes
 375     wxHashTable m_attrs;
 376
 377     // TRUE if we have any items with custom attributes
 378     bool m_hasAnyAttr;
 379
 380     // these functions are only used for virtual list view controls, i.e. the
 381     // ones with wxLC_VIRTUAL style
 382
 383     // return the text for the given column of the given item
 384     virtual wxString OnGetItemText(long item, long column) const;
 385
 386     // return the icon for the given item
 387     virtual int OnGetItemImage(long item) const;
 388
 389     // return the attribute for the item (may return NULL if none)
 390     virtual wxListItemAttr *OnGetItemAttr(long item) const;
 391
 392 private:
 393     bool DoCreateControl(int x, int y, int w, int h);
 394
 395     // process NM_CUSTOMDRAW notification message
 396     WXLPARAM OnCustomDraw(WXLPARAM lParam);
 397
 398     DECLARE_DYNAMIC_CLASS(wxListCtrl)
 399     DECLARE_EVENT_TABLE()
 400 };
 401
 402 #endif // wxUSE_LISTCTRL
 403
 404 #endif
 405     // _WX_LISTCTRL_H_
 406
 407 // vi:sts=4:sw=4:et