]> git.saurik.com Git - wxWidgets.git/blame - include/wx/msw/listctrl.h
build fix
[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
1e6feb95
VZ
15#if wxUSE_LISTCTRL
16
2bda0e17
KB
17#include "wx/control.h"
18#include "wx/event.h"
d62228a6 19#include "wx/hash.h"
5541d1fd
RL
20#include "wx/textctrl.h"
21
2bda0e17 22
9f303149
VZ
23class WXDLLEXPORT wxImageList;
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
bdc72a22 79class WXDLLEXPORT wxListCtrl: public wxControl
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
fbfb8bcc 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
VZ
128 // Sets the column width
129 bool SetColumnWidth(int col, int width) ;
2bda0e17 130
bdc72a22
VZ
131 // Gets the number of items that can fit vertically in the
132 // visible area of the list control (list or report view)
133 // or the total number of items in the list control (icon
134 // or small icon view)
135 int GetCountPerPage() const;
2bda0e17 136
11ebea16
VZ
137 // return the total area occupied by all the items (icon/small icon only)
138 wxRect GetViewRect() const;
139
bdc72a22
VZ
140 // Gets the edit control for editing labels.
141 wxTextCtrl* GetEditControl() const;
2bda0e17 142
bdc72a22
VZ
143 // Gets information about the item
144 bool GetItem(wxListItem& info) const ;
2bda0e17 145
bdc72a22
VZ
146 // Sets information about the item
147 bool SetItem(wxListItem& info) ;
2bda0e17 148
bdc72a22
VZ
149 // Sets a string field at a particular column
150 long SetItem(long index, int col, const wxString& label, int imageId = -1);
2bda0e17 151
bdc72a22
VZ
152 // Gets the item state
153 int GetItemState(long item, long stateMask) const ;
2bda0e17 154
bdc72a22
VZ
155 // Sets the item state
156 bool SetItemState(long item, long state, long stateMask) ;
2bda0e17 157
bdc72a22 158 // Sets the item image
aba3d35e 159 bool SetItemImage(long item, int image, int selImage = -1) ;
06db67bc 160 bool SetItemColumnImage(long item, long column, int image);
2bda0e17 161
bdc72a22
VZ
162 // Gets the item text
163 wxString GetItemText(long item) const ;
2bda0e17 164
bdc72a22
VZ
165 // Sets the item text
166 void SetItemText(long item, const wxString& str) ;
2bda0e17 167
bdc72a22 168 // Gets the item data
81ce36aa 169 wxUIntPtr GetItemData(long item) const ;
2bda0e17 170
bdc72a22
VZ
171 // Sets the item data
172 bool SetItemData(long item, long data) ;
2bda0e17 173
bdc72a22
VZ
174 // Gets the item rectangle
175 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
2bda0e17 176
164a7972
VZ
177 // Gets the subitem rectangle in report mode
178 bool GetSubItemRect(long item, long subItem, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const ;
179
bdc72a22
VZ
180 // Gets the item position
181 bool GetItemPosition(long item, wxPoint& pos) const ;
2bda0e17 182
bdc72a22
VZ
183 // Sets the item position
184 bool SetItemPosition(long item, const wxPoint& pos) ;
2bda0e17 185
bdc72a22
VZ
186 // Gets the number of items in the list control
187 int GetItemCount() const;
2bda0e17 188
bdc72a22
VZ
189 // Gets the number of columns in the list control
190 int GetColumnCount() const { return m_colCount; }
2bda0e17 191
5db8d758
VZ
192 // get the horizontal and vertical components of the item spacing
193 wxSize GetItemSpacing() const;
2bda0e17 194
5b98eb2f
RL
195 // Foreground colour of an item.
196 void SetItemTextColour( long item, const wxColour& col);
197 wxColour GetItemTextColour( long item ) const;
198
199 // Background colour of an item.
200 void SetItemBackgroundColour( long item, const wxColour &col);
201 wxColour GetItemBackgroundColour( long item ) const;
202
35c2acd4
MW
203 // Font of an item.
204 void SetItemFont( long item, const wxFont &f);
205 wxFont GetItemFont( long item ) const;
35c2acd4 206
bdc72a22
VZ
207 // Gets the number of selected items in the list control
208 int GetSelectedItemCount() const;
2bda0e17 209
bdc72a22
VZ
210 // Gets the text colour of the listview
211 wxColour GetTextColour() const;
2bda0e17 212
bdc72a22
VZ
213 // Sets the text colour of the listview
214 void SetTextColour(const wxColour& col);
2bda0e17 215
bdc72a22
VZ
216 // Gets the index of the topmost visible item when in
217 // list or report view
218 long GetTopItem() const ;
2bda0e17 219
bdc72a22 220 // Add or remove a single window style
598ddd96 221 void SetSingleStyle(long style, bool add = true) ;
2bda0e17 222
bdc72a22
VZ
223 // Set the whole window style
224 void SetWindowStyleFlag(long style) ;
2bda0e17 225
bdc72a22
VZ
226 // Searches for an item, starting from 'item'.
227 // item can be -1 to find the first item that matches the
228 // specified flags.
229 // Returns the item or -1 if unsuccessful.
230 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const ;
2bda0e17 231
bdc72a22
VZ
232 // Gets one of the three image lists
233 wxImageList *GetImageList(int which) const ;
2bda0e17 234
bdc72a22
VZ
235 // Sets the image list
236 // N.B. There's a quirk in the Win95 list view implementation.
237 // If in wxLC_LIST mode, it'll *still* display images by the labels if
238 // there's a small-icon image list set for the control - even though you
239 // haven't specified wxLIST_MASK_IMAGE when inserting.
240 // So you have to set a NULL small-icon image list to be sure that
241 // the wxLC_LIST mode works without icons. Of course, you may want icons...
242 void SetImageList(wxImageList *imageList, int which) ;
2e12c11a 243 void AssignImageList(wxImageList *imageList, int which) ;
2bda0e17 244
b5d43d1d
VZ
245 // are we in report mode?
246 bool InReportView() const { return HasFlag(wxLC_REPORT); }
247
248 // are we in virtual report mode?
249 bool IsVirtual() const { return HasFlag(wxLC_VIRTUAL); }
98ec9dbe 250
a7f560a2
VZ
251 // refresh items selectively (only useful for virtual list controls)
252 void RefreshItem(long item);
253 void RefreshItems(long itemFrom, long itemTo);
254
bdc72a22
VZ
255 // Operations
256 ////////////////////////////////////////////////////////////////////////////
2bda0e17 257
bdc72a22
VZ
258 // Arranges the items
259 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
2bda0e17 260
bdc72a22
VZ
261 // Deletes an item
262 bool DeleteItem(long item);
2bda0e17 263
bdc72a22
VZ
264 // Deletes all items
265 bool DeleteAllItems() ;
2bda0e17 266
bdc72a22
VZ
267 // Deletes a column
268 bool DeleteColumn(int col);
2bda0e17 269
bdc72a22
VZ
270 // Deletes all columns
271 bool DeleteAllColumns();
2bda0e17 272
bdc72a22
VZ
273 // Clears items, and columns if there are any.
274 void ClearAll();
2bda0e17 275
bdc72a22
VZ
276 // Edit the label
277 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
bbcdf8bc 278
bdc72a22
VZ
279 // End label editing, optionally cancelling the edit
280 bool EndEditLabel(bool cancel);
2bda0e17 281
bdc72a22
VZ
282 // Ensures this item is visible
283 bool EnsureVisible(long item) ;
2bda0e17 284
bdc72a22
VZ
285 // Find an item whose label matches this string, starting from the item after 'start'
286 // or the beginning if 'start' is -1.
598ddd96 287 long FindItem(long start, const wxString& str, bool partial = false);
2bda0e17 288
bdc72a22
VZ
289 // Find an item whose data matches this data, starting from the item after 'start'
290 // or the beginning if 'start' is -1.
81ce36aa 291 long FindItem(long start, wxUIntPtr data);
2bda0e17 292
bdc72a22
VZ
293 // Find an item nearest this position in the specified direction, starting from
294 // the item after 'start' or the beginning if 'start' is -1.
295 long FindItem(long start, const wxPoint& pt, int direction);
2bda0e17 296
bdc72a22
VZ
297 // Determines which item (if any) is at the specified point,
298 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
164a7972
VZ
299 // Request the subitem number as well at the given coordinate.
300 long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL);
2bda0e17 301
bdc72a22
VZ
302 // Inserts an item, returning the index of the new item if successful,
303 // -1 otherwise.
fbfb8bcc 304 long InsertItem(const wxListItem& info);
2bda0e17 305
bdc72a22
VZ
306 // Insert a string item
307 long InsertItem(long index, const wxString& label);
2bda0e17 308
bdc72a22
VZ
309 // Insert an image item
310 long InsertItem(long index, int imageIndex);
2bda0e17 311
bdc72a22
VZ
312 // Insert an image/string item
313 long InsertItem(long index, const wxString& label, int imageIndex);
2bda0e17 314
bdc72a22 315 // For list view mode (only), inserts a column.
fbfb8bcc 316 long InsertColumn(long col, const wxListItem& info);
2bda0e17 317
bdc72a22
VZ
318 long InsertColumn(long col,
319 const wxString& heading,
320 int format = wxLIST_FORMAT_LEFT,
321 int width = -1);
2bda0e17 322
98ec9dbe
VZ
323 // set the number of items in a virtual list control
324 void SetItemCount(long count);
325
bdc72a22
VZ
326 // Scrolls the list control. If in icon, small icon or report view mode,
327 // x specifies the number of pixels to scroll. If in list view mode, x
328 // specifies the number of columns to scroll.
329 // If in icon, small icon or list view mode, y specifies the number of pixels
330 // to scroll. If in report view mode, y specifies the number of lines to scroll.
331 bool ScrollList(int dx, int dy);
2bda0e17 332
bdc72a22 333 // Sort items.
2bda0e17 334
bdc72a22
VZ
335 // fn is a function which takes 3 long arguments: item1, item2, data.
336 // item1 is the long data associated with a first item (NOT the index).
337 // item2 is the long data associated with a second item (NOT the index).
338 // data is the same value as passed to SortItems.
339 // The return value is a negative number if the first item should precede the second
340 // item, a positive number of the second item should precede the first,
341 // or zero if the two items are equivalent.
2bda0e17 342
bdc72a22
VZ
343 // data is arbitrary data to be passed to the sort function.
344 bool SortItems(wxListCtrlCompare fn, long data);
2bda0e17 345
bdc72a22
VZ
346 // IMPLEMENTATION
347 virtual bool MSWCommand(WXUINT param, WXWORD id);
348 virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
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
387 // free memory taken by all internal data
388 void FreeAllInternalData();
a6c81161 389
e6b1317b
VZ
390 // get the item attribute, either by quering it for virtual control, or by
391 // returning the one previously set using setter methods for a normal one
392 wxListItemAttr *DoGetItemAttr(long item) const;
393
394
bdc72a22
VZ
395 wxTextCtrl* m_textCtrl; // The control used for editing a label
396 wxImageList * m_imageListNormal; // The image list for normal icons
397 wxImageList * m_imageListSmall; // The image list for small icons
398 wxImageList * m_imageListState; // The image list state icons (not implemented yet)
2e12c11a
VS
399 bool m_ownsImageListNormal,
400 m_ownsImageListSmall,
401 m_ownsImageListState;
2bda0e17 402
bdc72a22
VZ
403 int m_colCount; // Windows doesn't have GetColumnCount so must
404 // keep track of inserted/deleted columns
68c124a1
RD
405 long m_count; // Keep track of item count to save calls to
406 // ListView_GetItemCount
407 bool m_ignoreChangeMessages;
bdc72a22 408
598ddd96 409 // true if we have any internal data (user data & attributes)
7cf46fdb 410 bool m_AnyInternalData;
d62228a6 411
598ddd96 412 // true if we have any items with custom attributes
bdc72a22 413 bool m_hasAnyAttr;
2bda0e17 414
98ec9dbe
VZ
415 // these functions are only used for virtual list view controls, i.e. the
416 // ones with wxLC_VIRTUAL style
417
418 // return the text for the given column of the given item
419 virtual wxString OnGetItemText(long item, long column) const;
420
208458a7 421 // return the icon for the given item. In report view, OnGetItemImage will
40ff126a 422 // only be called for the first column. See OnGetItemColumnImage for
208458a7 423 // details.
98ec9dbe
VZ
424 virtual int OnGetItemImage(long item) const;
425
208458a7
RD
426 // return the icon for the given item and column.
427 virtual int OnGetItemColumnImage(long item, long column) const;
428
6c02c329
VZ
429 // return the attribute for the item (may return NULL if none)
430 virtual wxListItemAttr *OnGetItemAttr(long item) const;
431
edccf428 432private:
63166611
VZ
433 // process NM_CUSTOMDRAW notification message
434 WXLPARAM OnCustomDraw(WXLPARAM lParam);
435
bdc72a22 436 DECLARE_DYNAMIC_CLASS(wxListCtrl)
2702ed5a 437 DECLARE_EVENT_TABLE()
22f3361e 438 DECLARE_NO_COPY_CLASS(wxListCtrl)
2bda0e17
KB
439};
440
1e6feb95
VZ
441#endif // wxUSE_LISTCTRL
442
1944ad76 443#endif // _WX_LISTCTRL_H_