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