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