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