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