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
  25 class WXDLLEXPORT wxTextCtrl;
  26 class WXDLLEXPORT wxImageList;
  27
  28 /*
  29     The wxListCtrl can show lists of items in four different modes:
  30     wxLC_LIST:   multicolumn list view, with optional small icons (icons could be
  31                  optional for some platforms). Columns are computed automatically,
  32                  i.e. you don't set columns as in wxLC_REPORT. In other words,
  33                  the list wraps, unlike a wxListBox.
  34     wxLC_REPORT: single or multicolumn report view (with optional header)
  35     wxLC_ICON:   large icon view, with optional labels
  36     wxLC_SMALL_ICON: small icon view, with optional labels
  37
  38     You can change the style dynamically, either with SetSingleStyle or
  39     SetWindowStyleFlag.
  40
  41     Further window styles:
  42
  43     wxLC_ALIGN_TOP          icons align to the top (default)
  44     wxLC_ALIGN_LEFT         icons align to the left
  45     wxLC_AUTOARRANGE        icons arrange themselves
  46     wxLC_USER_TEXT          the app provides label text on demand, except for column headers
  47     wxLC_EDIT_LABELS        labels are editable: app will be notified.
  48     wxLC_NO_HEADER          no header in report mode
  49     wxLC_NO_SORT_HEADER     can't click on header
  50     wxLC_SINGLE_SEL         single selection
  51     wxLC_SORT_ASCENDING     sort ascending (must still supply a comparison callback in SortItems)
  52     wxLC_SORT_DESCENDING    sort descending (ditto)
  53
  54     Items are referred to by their index (position in the list starting from zero).
  55
  56     Label text is supplied via insertion/setting functions and is stored by the
  57     control, unless the wxLC_USER_TEXT style has been specified, in which case
  58     the app will be notified when text is required (see sample).
  59
  60     Images are dealt with by (optionally) associating 3 image lists with the control.
  61     Zero-based indexes into these image lists indicate which image is to be used for
  62     which item. Each image in an image list can contain a mask, and can be made out
  63     of either a bitmap, two bitmaps or an icon. See ImagList.h for more details.
  64
  65     Notifications are passed via the wxWindows 2.0 event system, or using virtual
  66     functions in wxWindows 1.66.
  67
  68     See the sample wxListCtrl app for API usage.
  69
  70     TODO:
  71      - addition of further convenience functions
  72        to avoid use of wxListItem in some functions
  73      - state/overlay images: probably not needed.
  74      - in Win95, you can be called back to supply other information
  75        besides text, such as state information. This saves no memory
  76        and is probably superfluous to requirements.
  77      - testing of whole API, extending current sample.
  78
  79
  80  */
  81
  82 class WXDLLEXPORT wxListCtrl: public wxControl
  83 {
  84 public:
  85     /*
  86      * Public interface
  87      */
  88
  89     wxListCtrl() { Init(); }
  90
  91     wxListCtrl(wxWindow *parent,
  92                wxWindowID id = -1,
  93                const wxPoint& pos = wxDefaultPosition,
  94                const wxSize& size = wxDefaultSize,
  95                long style = wxLC_ICON,
  96                const wxValidator& validator = wxDefaultValidator,
  97                const wxString& name = _T("wxListCtrl"))
  98     {
  99         Init();
 100
 101         Create(parent, id, pos, size, style, validator, name);
 102     }
 103
 104     virtual ~wxListCtrl();
 105
 106     bool Create(wxWindow *parent,
 107                 wxWindowID id = -1,
 108                 const wxPoint& pos = wxDefaultPosition,
 109                 const wxSize& size = wxDefaultSize,
 110                 long style = wxLC_ICON,
 111                 const wxValidator& validator = wxDefaultValidator,
 112                 const wxString& name = _T("wxListCtrl"));
 113
 114
 115     // Attributes
 116     ////////////////////////////////////////////////////////////////////////////
 117
 118     // Set the control colours
 119     bool SetForegroundColour(const wxColour& col);
 120     bool SetBackgroundColour(const wxColour& col);
 121
 122     // Gets information about this column
 123     bool GetColumn(int col, wxListItem& item) const;
 124
 125     // Sets information about this column
 126     bool SetColumn(int col, wxListItem& item) ;
 127
 128     // Gets the column width
 129     int GetColumnWidth(int col) const;
 130
 131     // Sets the column width
 132     bool SetColumnWidth(int col, int width) ;
 133
 134     // Gets the number of items that can fit vertically in the
 135     // visible area of the list control (list or report view)
 136     // or the total number of items in the list control (icon
 137     // or small icon view)
 138     int GetCountPerPage() 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) ;
 160
 161     // Gets the item text
 162     wxString GetItemText(long item) const ;
 163
 164     // Sets the item text
 165     void SetItemText(long item, const wxString& str) ;
 166
 167     // Gets the item data
 168     long GetItemData(long item) const ;
 169
 170     // Sets the item data
 171     bool SetItemData(long item, long data) ;
 172
 173     // Gets the item rectangle
 174     bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
 175
 176     // Gets the item position
 177     bool GetItemPosition(long item, wxPoint& pos) const ;
 178
 179     // Sets the item position
 180     bool SetItemPosition(long item, const wxPoint& pos) ;
 181
 182     // Gets the number of items in the list control
 183     int GetItemCount() const;
 184
 185     // Gets the number of columns in the list control
 186     int GetColumnCount() const { return m_colCount; }
 187
 188     // Retrieves the spacing between icons in pixels.
 189     // If small is TRUE, gets the spacing for the small icon
 190     // view, otherwise the large icon view.
 191     int GetItemSpacing(bool isSmall) const;
 192
 193     // Gets the number of selected items in the list control
 194     int GetSelectedItemCount() const;
 195
 196     // Gets the text colour of the listview
 197     wxColour GetTextColour() const;
 198
 199     // Sets the text colour of the listview
 200     void SetTextColour(const wxColour& col);
 201
 202     // Gets the index of the topmost visible item when in
 203     // list or report view
 204     long GetTopItem() const ;
 205
 206     // Add or remove a single window style
 207     void SetSingleStyle(long style, bool add = TRUE) ;
 208
 209     // Set the whole window style
 210     void SetWindowStyleFlag(long style) ;
 211
 212     // Searches for an item, starting from 'item'.
 213     // item can be -1 to find the first item that matches the
 214     // specified flags.
 215     // Returns the item or -1 if unsuccessful.
 216     long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
 217
 218     // Gets one of the three image lists
 219     wxImageList *GetImageList(int which) const ;
 220
 221     // Sets the image list
 222     // N.B. There's a quirk in the Win95 list view implementation.
 223     // If in wxLC_LIST mode, it'll *still* display images by the labels if
 224     // there's a small-icon image list set for the control - even though you
 225     // haven't specified wxLIST_MASK_IMAGE when inserting.
 226     // So you have to set a NULL small-icon image list to be sure that
 227     // the wxLC_LIST mode works without icons. Of course, you may want icons...
 228     void SetImageList(wxImageList *imageList, int which) ;
 229     void AssignImageList(wxImageList *imageList, int which) ;
 230
 231     // returns true if it is a virtual list control
 232     bool IsVirtual() const { return (GetWindowStyle() & wxLC_VIRTUAL) != 0; }
 233
 234     // refresh items selectively (only useful for virtual list controls)
 235     void RefreshItem(long item);
 236     void RefreshItems(long itemFrom, long itemTo);
 237
 238     // Operations
 239     ////////////////////////////////////////////////////////////////////////////
 240
 241     // Arranges the items
 242     bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
 243
 244     // Deletes an item
 245     bool DeleteItem(long item);
 246
 247     // Deletes all items
 248     bool DeleteAllItems() ;
 249
 250     // Deletes a column
 251     bool DeleteColumn(int col);
 252
 253     // Deletes all columns
 254     bool DeleteAllColumns();
 255
 256     // Clears items, and columns if there are any.
 257     void ClearAll();
 258
 259     // Edit the label
 260     wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
 261
 262     // End label editing, optionally cancelling the edit
 263     bool EndEditLabel(bool cancel);
 264
 265     // Ensures this item is visible
 266     bool EnsureVisible(long item) ;
 267
 268     // Find an item whose label matches this string, starting from the item after 'start'
 269     // or the beginning if 'start' is -1.
 270     long FindItem(long start, const wxString& str, bool partial = FALSE);
 271
 272     // Find an item whose data matches this data, starting from the item after 'start'
 273     // or the beginning if 'start' is -1.
 274     long FindItem(long start, long data);
 275
 276     // Find an item nearest this position in the specified direction, starting from
 277     // the item after 'start' or the beginning if 'start' is -1.
 278     long FindItem(long start, const wxPoint& pt, int direction);
 279
 280     // Determines which item (if any) is at the specified point,
 281     // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
 282     long HitTest(const wxPoint& point, int& flags);
 283
 284     // Inserts an item, returning the index of the new item if successful,
 285     // -1 otherwise.
 286     long InsertItem(wxListItem& info);
 287
 288     // Insert a string item
 289     long InsertItem(long index, const wxString& label);
 290
 291     // Insert an image item
 292     long InsertItem(long index, int imageIndex);
 293
 294     // Insert an image/string item
 295     long InsertItem(long index, const wxString& label, int imageIndex);
 296
 297     // For list view mode (only), inserts a column.
 298     long InsertColumn(long col, wxListItem& info);
 299
 300     long InsertColumn(long col,
 301                       const wxString& heading,
 302                       int format = wxLIST_FORMAT_LEFT,
 303                       int width = -1);
 304
 305     // set the number of items in a virtual list control
 306     void SetItemCount(long count);
 307
 308     // Scrolls the list control. If in icon, small icon or report view mode,
 309     // x specifies the number of pixels to scroll. If in list view mode, x
 310     // specifies the number of columns to scroll.
 311     // If in icon, small icon or list view mode, y specifies the number of pixels
 312     // to scroll. If in report view mode, y specifies the number of lines to scroll.
 313     bool ScrollList(int dx, int dy);
 314
 315     // Sort items.
 316
 317     // fn is a function which takes 3 long arguments: item1, item2, data.
 318     // item1 is the long data associated with a first item (NOT the index).
 319     // item2 is the long data associated with a second item (NOT the index).
 320     // data is the same value as passed to SortItems.
 321     // The return value is a negative number if the first item should precede the second
 322     // item, a positive number of the second item should precede the first,
 323     // or zero if the two items are equivalent.
 324
 325     // data is arbitrary data to be passed to the sort function.
 326     bool SortItems(wxListCtrlCompare fn, long data);
 327
 328     // IMPLEMENTATION
 329     virtual bool MSWCommand(WXUINT param, WXWORD id);
 330     virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
 331
 332     // bring the control in sync with current m_windowStyle value
 333     void UpdateStyle();
 334
 335     // Implementation: converts wxWindows style to MSW style.
 336     // Can be a single style flag or a bit list.
 337     // oldStyle is 'normalised' so that it doesn't contain
 338     // conflicting styles.
 339     long ConvertToMSWStyle(long& oldStyle, long style) const;
 340
 341     // Event handlers
 342     ////////////////////////////////////////////////////////////////////////////
 343     // Necessary for drawing hrules and vrules, if specified
 344     void OnPaint(wxPaintEvent& event);
 345
 346 protected:
 347     // common part of all ctors
 348     void Init();
 349
 350     // free memory taken by all attributes and recreate the hash table
 351     void FreeAllAttrs(bool dontRecreate = FALSE);
 352
 353     wxTextCtrl*       m_textCtrl;        // The control used for editing a label
 354     wxImageList *     m_imageListNormal; // The image list for normal icons
 355     wxImageList *     m_imageListSmall;  // The image list for small icons
 356     wxImageList *     m_imageListState;  // The image list state icons (not implemented yet)
 357     bool              m_ownsImageListNormal,
 358                       m_ownsImageListSmall,
 359                       m_ownsImageListState;
 360
 361     long              m_baseStyle;  // Basic Windows style flags, for recreation purposes
 362     int               m_colCount;   // Windows doesn't have GetColumnCount so must
 363                                     // keep track of inserted/deleted columns
 364
 365     // the hash table we use for storing pointers to the items attributes
 366     wxHashTable m_attrs;
 367
 368     // TRUE if we have any items with custom attributes
 369     bool m_hasAnyAttr;
 370
 371     // these functions are only used for virtual list view controls, i.e. the
 372     // ones with wxLC_VIRTUAL style
 373
 374     // return the text for the given column of the given item
 375     virtual wxString OnGetItemText(long item, long column) const;
 376
 377     // return the icon for the given item
 378     virtual int OnGetItemImage(long item) const;
 379
 380     // return the attribute for the item (may return NULL if none)
 381     virtual wxListItemAttr *OnGetItemAttr(long item) const;
 382
 383 private:
 384     bool DoCreateControl(int x, int y, int w, int h);
 385
 386     // process NM_CUSTOMDRAW notification message
 387     WXLPARAM OnCustomDraw(WXLPARAM lParam);
 388
 389     DECLARE_DYNAMIC_CLASS(wxListCtrl)
 390     DECLARE_EVENT_TABLE()
 391 };
 392
 393 #endif // wxUSE_LISTCTRL
 394
 395 #endif
 396     // _WX_LISTCTRL_H_