]> git.saurik.com Git - wxWidgets.git/blob - include/wx/msw/listctrl.h
Reuse wxMessageOutputStderr for wxLogStderr implementation.
[wxWidgets.git] / 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 #include "wx/vector.h"
18
19 class wxMSWListItemData;
20
21 // define this symbol to indicate the availability of SetColumnsOrder() and
22 // related functions
23 #define wxHAS_LISTCTRL_COLUMN_ORDER
24
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
62 Notifications are passed via the wxWidgets 2.0 event system, or using virtual
63 functions in wxWidgets 1.66.
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.
74 - testing of whole API, extending current sample.
75
76
77 */
78
79 class WXDLLIMPEXP_CORE wxListCtrl: public wxListCtrlBase
80 {
81 public:
82 /*
83 * Public interface
84 */
85
86 wxListCtrl() { Init(); }
87
88 wxListCtrl(wxWindow *parent,
89 wxWindowID id = wxID_ANY,
90 const wxPoint& pos = wxDefaultPosition,
91 const wxSize& size = wxDefaultSize,
92 long style = wxLC_ICON,
93 const wxValidator& validator = wxDefaultValidator,
94 const wxString& name = wxListCtrlNameStr)
95 {
96 Init();
97
98 Create(parent, id, pos, size, style, validator, name);
99 }
100
101 virtual ~wxListCtrl();
102
103 bool Create(wxWindow *parent,
104 wxWindowID id = wxID_ANY,
105 const wxPoint& pos = wxDefaultPosition,
106 const wxSize& size = wxDefaultSize,
107 long style = wxLC_ICON,
108 const wxValidator& validator = wxDefaultValidator,
109 const wxString& name = wxListCtrlNameStr);
110
111
112 // Attributes
113 ////////////////////////////////////////////////////////////////////////////
114
115 // Set the control colours
116 bool SetForegroundColour(const wxColour& col);
117 bool SetBackgroundColour(const wxColour& col);
118
119 // Gets information about this column
120 bool GetColumn(int col, wxListItem& item) const;
121
122 // Sets information about this column
123 bool SetColumn(int col, const wxListItem& item);
124
125 // Gets the column width
126 int GetColumnWidth(int col) const;
127
128 // Sets the column width
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
142
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;
148
149 // return the total area occupied by all the items (icon/small icon only)
150 wxRect GetViewRect() const;
151
152 // Gets the edit control for editing labels.
153 wxTextCtrl* GetEditControl() const;
154
155 // Gets information about the item
156 bool GetItem(wxListItem& info) const;
157
158 // Sets information about the item
159 bool SetItem(wxListItem& info);
160
161 // Sets a string field at a particular column
162 long SetItem(long index, int col, const wxString& label, int imageId = -1);
163
164 // Gets the item state
165 int GetItemState(long item, long stateMask) const;
166
167 // Sets the item state
168 bool SetItemState(long item, long state, long stateMask);
169
170 // Sets the item image
171 bool SetItemImage(long item, int image, int selImage = -1);
172 bool SetItemColumnImage(long item, long column, int image);
173
174 // Gets the item text
175 wxString GetItemText(long item, int col = 0) const;
176
177 // Sets the item text
178 void SetItemText(long item, const wxString& str);
179
180 // Gets the item data
181 wxUIntPtr GetItemData(long item) const;
182
183 // Sets the item data
184 bool SetItemPtrData(long item, wxUIntPtr data);
185 bool SetItemData(long item, long data) { return SetItemPtrData(item, data); }
186
187 // Gets the item rectangle
188 bool GetItemRect(long item, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const;
189
190 // Gets the subitem rectangle in report mode
191 bool GetSubItemRect(long item, long subItem, wxRect& rect, int code = wxLIST_RECT_BOUNDS) const;
192
193 // Gets the item position
194 bool GetItemPosition(long item, wxPoint& pos) const;
195
196 // Sets the item position
197 bool SetItemPosition(long item, const wxPoint& pos);
198
199 // Gets the number of items in the list control
200 int GetItemCount() const;
201
202 // Gets the number of columns in the list control
203 int GetColumnCount() const { return m_colCount; }
204
205 // get the horizontal and vertical components of the item spacing
206 wxSize GetItemSpacing() const;
207
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
216 // Font of an item.
217 void SetItemFont( long item, const wxFont &f);
218 wxFont GetItemFont( long item ) const;
219
220 // Gets the number of selected items in the list control
221 int GetSelectedItemCount() const;
222
223 // Gets the text colour of the listview
224 wxColour GetTextColour() const;
225
226 // Sets the text colour of the listview
227 void SetTextColour(const wxColour& col);
228
229 // Gets the index of the topmost visible item when in
230 // list or report view
231 long GetTopItem() const;
232
233 // Add or remove a single window style
234 void SetSingleStyle(long style, bool add = true);
235
236 // Set the whole window style
237 void SetWindowStyleFlag(long style);
238
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.
243 long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, int state = wxLIST_STATE_DONTCARE) const;
244
245 // Gets one of the three image lists
246 wxImageList *GetImageList(int which) const;
247
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...
255 void SetImageList(wxImageList *imageList, int which);
256 void AssignImageList(wxImageList *imageList, int which);
257
258 // refresh items selectively (only useful for virtual list controls)
259 void RefreshItem(long item);
260 void RefreshItems(long itemFrom, long itemTo);
261
262 // Operations
263 ////////////////////////////////////////////////////////////////////////////
264
265 // Arranges the items
266 bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
267
268 // Deletes an item
269 bool DeleteItem(long item);
270
271 // Deletes all items
272 bool DeleteAllItems();
273
274 // Deletes a column
275 bool DeleteColumn(int col);
276
277 // Deletes all columns
278 bool DeleteAllColumns();
279
280 // Clears items, and columns if there are any.
281 void ClearAll();
282
283 // Edit the label
284 wxTextCtrl* EditLabel(long item, wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
285
286 // End label editing, optionally cancelling the edit
287 bool EndEditLabel(bool cancel);
288
289 // Ensures this item is visible
290 bool EnsureVisible(long item);
291
292 // Find an item whose label matches this string, starting from the item after 'start'
293 // or the beginning if 'start' is -1.
294 long FindItem(long start, const wxString& str, bool partial = false);
295
296 // Find an item whose data matches this data, starting from the item after 'start'
297 // or the beginning if 'start' is -1.
298 long FindItem(long start, wxUIntPtr data);
299
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);
303
304 // Determines which item (if any) is at the specified point,
305 // giving details in 'flags' (see wxLIST_HITTEST_... flags above)
306 // Request the subitem number as well at the given coordinate.
307 long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
308
309 // Inserts an item, returning the index of the new item if successful,
310 // -1 otherwise.
311 long InsertItem(const wxListItem& info);
312
313 // Insert a string item
314 long InsertItem(long index, const wxString& label);
315
316 // Insert an image item
317 long InsertItem(long index, int imageIndex);
318
319 // Insert an image/string item
320 long InsertItem(long index, const wxString& label, int imageIndex);
321
322 // set the number of items in a virtual list control
323 void SetItemCount(long count);
324
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);
331
332 // Sort items.
333
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.
341
342 // data is arbitrary data to be passed to the sort function.
343 bool SortItems(wxListCtrlCompare fn, wxIntPtr data);
344
345 // IMPLEMENTATION
346 virtual bool MSWCommand(WXUINT param, WXWORD id);
347 virtual bool MSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
348 virtual bool MSWShouldPreProcessMessage(WXMSG* msg);
349
350 // bring the control in sync with current m_windowStyle value
351 void UpdateStyle();
352
353 // Event handlers
354 ////////////////////////////////////////////////////////////////////////////
355 // Necessary for drawing hrules and vrules, if specified
356 void OnPaint(wxPaintEvent& event);
357
358
359 virtual bool ShouldInheritColours() const { return false; }
360
361 virtual wxVisualAttributes GetDefaultAttributes() const
362 {
363 return GetClassDefaultAttributes(GetWindowVariant());
364 }
365
366 static wxVisualAttributes
367 GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL);
368
369
370 #if WXWIN_COMPATIBILITY_2_6
371 // obsolete stuff, for compatibility only -- don't use
372 wxDEPRECATED( int GetItemSpacing(bool isSmall) const);
373 #endif // WXWIN_COMPATIBILITY_2_6
374
375 // convert our styles to Windows
376 virtual WXDWORD MSWGetStyle(long style, WXDWORD *exstyle) const;
377
378 // special Windows message handling
379 virtual WXLRESULT MSWWindowProc(WXUINT nMsg,
380 WXWPARAM wParam,
381 WXLPARAM lParam);
382
383 protected:
384 // common part of all ctors
385 void Init();
386
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
395 // Implement base class pure virtual methods.
396 long DoInsertColumn(long col, const wxListItem& info);
397
398 // free memory taken by all internal data
399 void FreeAllInternalData();
400
401 // get the internal data object for this item (may return NULL)
402 wxMSWListItemData *MSWGetItemData(long item) const;
403
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
406 wxListItemAttr *DoGetItemColumnAttr(long item, long column) const;
407
408
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)
413 bool m_ownsImageListNormal,
414 m_ownsImageListSmall,
415 m_ownsImageListState;
416
417 int m_colCount; // Windows doesn't have GetColumnCount so must
418 // keep track of inserted/deleted columns
419 long m_count; // Keep track of item count to save calls to
420 // ListView_GetItemCount
421
422 // all wxMSWListItemData objects we use
423 wxVector<wxMSWListItemData *> m_internalData;
424
425 // true if we have any items with custom attributes
426 bool m_hasAnyAttr;
427
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
434 // return the icon for the given item. In report view, OnGetItemImage will
435 // only be called for the first column. See OnGetItemColumnImage for
436 // details.
437 virtual int OnGetItemImage(long item) const;
438
439 // return the icon for the given item and column.
440 virtual int OnGetItemColumnImage(long item, long column) const;
441
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
448 private:
449 // process NM_CUSTOMDRAW notification message
450 WXLPARAM OnCustomDraw(WXLPARAM lParam);
451
452 // set the extended styles for the control (used by Create() and
453 // UpdateStyle()), only should be called if InReportView()
454 void MSWSetExListStyles();
455
456 // initialize the (already created) m_textCtrl with the associated HWND
457 void InitEditControl(WXHWND hWnd);
458
459 // destroy m_textCtrl if it's currently valid and reset it to NULL
460 void DeleteEditControl();
461
462 // Intercept Escape and Enter keys to avoid them being stolen from our
463 // in-place editor control.
464 void OnCharHook(wxKeyEvent& event);
465
466
467 DECLARE_DYNAMIC_CLASS(wxListCtrl)
468 DECLARE_EVENT_TABLE()
469 wxDECLARE_NO_COPY_CLASS(wxListCtrl);
470 };
471
472 #endif // _WX_LISTCTRL_H_