]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: listctrl.h | |
e54c96f1 | 3 | // Purpose: interface of wxListCtrl |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxListCtrl | |
11 | @wxheader{listctrl.h} | |
7c913512 | 12 | |
23324ae1 FM |
13 | A list control presents lists in a number of formats: list view, report view, |
14 | icon view and small icon view. In any case, elements are numbered from zero. | |
15 | For all these modes, the items are stored in the control and must be added to | |
16 | it using wxListCtrl::InsertItem method. | |
7c913512 | 17 | |
23324ae1 FM |
18 | A special case of report view quite different from the other modes of the list |
19 | control is a virtual control in which the items data (including text, images | |
20 | and attributes) is managed by the main program and is requested by the control | |
21 | itself only when needed which allows to have controls with millions of items | |
22 | without consuming much memory. To use virtual list control you must use | |
23 | wxListCtrl::SetItemCount first and overload at least | |
24 | wxListCtrl::OnGetItemText (and optionally | |
25 | wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and | |
26 | wxListCtrl::OnGetItemAttr) to return the information | |
27 | about the items when the control requests it. Virtual list control can be used | |
28 | as a normal one except that no operations which can take time proportional to | |
29 | the number of items in the control happen -- this is required to allow having a | |
30 | practically infinite number of items. For example, in a multiple selection | |
31 | virtual list control, the selections won't be sent when many items are selected | |
32 | at once because this could mean iterating over all the items. | |
7c913512 | 33 | |
23324ae1 FM |
34 | Using many of wxListCtrl features is shown in the |
35 | @ref overview_samplelistctrl "corresponding sample". | |
7c913512 | 36 | |
23324ae1 FM |
37 | To intercept events from a list control, use the event table macros described |
38 | in wxListEvent. | |
7c913512 FM |
39 | |
40 | @b Mac Note: Starting with 2.8, wxListCtrl uses a native implementation for | |
23324ae1 FM |
41 | report mode, and uses a generic implementation for other modes. You can use the |
42 | generic implementation for report mode as well by setting the | |
e54c96f1 | 43 | mac.listctrl.always_use_generic wxSystemOption() to |
23324ae1 | 44 | 1. |
7c913512 | 45 | |
23324ae1 FM |
46 | @beginStyleTable |
47 | @style{wxLC_LIST}: | |
48 | Multicolumn list view, with optional small icons. Columns are | |
49 | computed automatically, i.e. you don't set columns as in | |
50 | wxLC_REPORT. In other words, the list wraps, unlike a wxListBox. | |
51 | @style{wxLC_REPORT}: | |
52 | Single or multicolumn report view, with optional header. | |
53 | @style{wxLC_VIRTUAL}: | |
54 | The application provides items text on demand. May only be used | |
55 | with wxLC_REPORT. | |
56 | @style{wxLC_ICON}: | |
57 | Large icon view, with optional labels. | |
58 | @style{wxLC_SMALL_ICON}: | |
59 | Small icon view, with optional labels. | |
60 | @style{wxLC_ALIGN_TOP}: | |
61 | Icons align to the top. Win32 default, Win32 only. | |
62 | @style{wxLC_ALIGN_LEFT}: | |
63 | Icons align to the left. | |
64 | @style{wxLC_AUTOARRANGE}: | |
65 | Icons arrange themselves. Win32 only. | |
66 | @style{wxLC_EDIT_LABELS}: | |
67 | Labels are editable: the application will be notified when editing | |
68 | starts. | |
69 | @style{wxLC_NO_HEADER}: | |
70 | No header in report mode. | |
71 | @style{wxLC_SINGLE_SEL}: | |
72 | Single selection (default is multiple). | |
73 | @style{wxLC_SORT_ASCENDING}: | |
74 | Sort in ascending order (must still supply a comparison callback in | |
75 | SortItems. | |
76 | @style{wxLC_SORT_DESCENDING}: | |
77 | Sort in descending order (must still supply a comparison callback | |
78 | in SortItems. | |
79 | @style{wxLC_HRULES}: | |
80 | Draws light horizontal rules between rows in report mode. | |
81 | @style{wxLC_VRULES}: | |
82 | Draws light vertical rules between columns in report mode. | |
83 | @endStyleTable | |
7c913512 | 84 | |
23324ae1 FM |
85 | @library{wxcore} |
86 | @category{ctrl} | |
87 | @appearance{listctrl.png} | |
7c913512 | 88 | |
e54c96f1 FM |
89 | @see @ref overview_wxlistctrloverview "wxListCtrl overview", wxListView, |
90 | wxListBox, wxTreeCtrl, wxImageList, wxListEvent, wxListItem | |
23324ae1 FM |
91 | */ |
92 | class wxListCtrl : public wxControl | |
93 | { | |
94 | public: | |
95 | //@{ | |
96 | /** | |
97 | Constructor, creating and showing a list control. | |
3c4f71cc | 98 | |
7c913512 | 99 | @param parent |
4cc4bfaf | 100 | Parent window. Must not be @NULL. |
7c913512 | 101 | @param id |
4cc4bfaf | 102 | Window identifier. The value wxID_ANY indicates a default value. |
7c913512 | 103 | @param pos |
4cc4bfaf | 104 | Window position. |
7c913512 | 105 | @param size |
4cc4bfaf FM |
106 | Window size. If wxDefaultSize is specified then the window is |
107 | sized | |
108 | appropriately. | |
7c913512 | 109 | @param style |
4cc4bfaf | 110 | Window style. See wxListCtrl. |
7c913512 | 111 | @param validator |
4cc4bfaf | 112 | Window validator. |
7c913512 | 113 | @param name |
4cc4bfaf | 114 | Window name. |
3c4f71cc | 115 | |
4cc4bfaf | 116 | @see Create(), wxValidator |
23324ae1 FM |
117 | */ |
118 | wxListCtrl(); | |
7c913512 FM |
119 | wxListCtrl(wxWindow* parent, wxWindowID id, |
120 | const wxPoint& pos = wxDefaultPosition, | |
121 | const wxSize& size = wxDefaultSize, | |
122 | long style = wxLC_ICON, | |
123 | const wxValidator& validator = wxDefaultValidator, | |
124 | const wxString& name = wxListCtrlNameStr); | |
23324ae1 FM |
125 | //@} |
126 | ||
127 | /** | |
128 | Destructor, destroying the list control. | |
129 | */ | |
130 | ~wxListCtrl(); | |
131 | ||
132 | /** | |
133 | Arranges the items in icon or small icon view. This only has effect on Win32. | |
4cc4bfaf | 134 | @a flag is one of: |
3c4f71cc | 135 | |
23324ae1 | 136 | wxLIST_ALIGN_DEFAULT |
3c4f71cc | 137 | |
23324ae1 | 138 | Default alignment. |
3c4f71cc | 139 | |
23324ae1 | 140 | wxLIST_ALIGN_LEFT |
3c4f71cc | 141 | |
23324ae1 | 142 | Align to the left side of the control. |
3c4f71cc | 143 | |
23324ae1 | 144 | wxLIST_ALIGN_TOP |
3c4f71cc | 145 | |
23324ae1 | 146 | Align to the top side of the control. |
3c4f71cc | 147 | |
23324ae1 | 148 | wxLIST_ALIGN_SNAP_TO_GRID |
3c4f71cc | 149 | |
23324ae1 FM |
150 | Snap to grid. |
151 | */ | |
152 | bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); | |
153 | ||
154 | /** | |
155 | Sets the image list associated with the control and | |
156 | takes ownership of it (i.e. the control will, unlike when using | |
4cc4bfaf | 157 | SetImageList, delete the list when destroyed). @a which is one of |
23324ae1 FM |
158 | wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is |
159 | unimplemented). | |
3c4f71cc | 160 | |
4cc4bfaf | 161 | @see SetImageList() |
23324ae1 FM |
162 | */ |
163 | void AssignImageList(wxImageList* imageList, int which); | |
164 | ||
165 | /** | |
166 | Deletes all items and all columns. | |
167 | */ | |
168 | void ClearAll(); | |
169 | ||
170 | /** | |
171 | Creates the list control. See wxListCtrl() for further details. | |
172 | */ | |
173 | bool Create(wxWindow* parent, wxWindowID id, | |
174 | const wxPoint& pos = wxDefaultPosition, | |
175 | const wxSize& size = wxDefaultSize, | |
176 | long style = wxLC_ICON, | |
177 | const wxValidator& validator = wxDefaultValidator, | |
178 | const wxString& name = wxListCtrlNameStr); | |
179 | ||
180 | /** | |
181 | Deletes all items in the list control. | |
23324ae1 FM |
182 | @b NB: This function does @e not send the |
183 | @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items | |
184 | from the control would be too slow then (unlike wxListCtrl::DeleteItem). | |
185 | */ | |
186 | bool DeleteAllItems(); | |
187 | ||
188 | /** | |
189 | Deletes a column. | |
190 | */ | |
191 | bool DeleteColumn(int col); | |
192 | ||
193 | /** | |
194 | Deletes the specified item. This function sends the | |
195 | @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted. | |
23324ae1 FM |
196 | See also: DeleteAllItems() |
197 | */ | |
198 | bool DeleteItem(long item); | |
199 | ||
200 | /** | |
201 | Starts editing the label of the given item. This function generates a | |
202 | EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no | |
203 | text control will appear for in-place editing. | |
23324ae1 FM |
204 | If the user changed the label (i.e. s/he does not press ESC or leave |
205 | the text control without changes, a EVT_LIST_END_LABEL_EDIT event | |
206 | will be sent which can be vetoed as well. | |
207 | */ | |
208 | void EditLabel(long item); | |
209 | ||
210 | /** | |
211 | Ensures this item is visible. | |
212 | */ | |
213 | bool EnsureVisible(long item); | |
214 | ||
215 | //@{ | |
216 | /** | |
217 | Find an item nearest this position in the specified direction, starting from | |
4cc4bfaf | 218 | @a start or the beginning if @a start is -1. |
3c4f71cc VS |
219 | |
220 | ||
23324ae1 | 221 | @b FindItem( start, str, partial = @false ) |
3c4f71cc VS |
222 | |
223 | ||
23324ae1 | 224 | @b FindItemData( start, data ) |
3c4f71cc VS |
225 | |
226 | ||
23324ae1 FM |
227 | @b FindItemAtPos( start, point, direction ) |
228 | */ | |
229 | long FindItem(long start, const wxString& str, | |
4cc4bfaf | 230 | bool partial = false); |
7c913512 FM |
231 | long FindItem(long start, long data); |
232 | long FindItem(long start, const wxPoint& pt, int direction); | |
23324ae1 FM |
233 | //@} |
234 | ||
235 | /** | |
236 | Gets information about this column. See SetItem() for more | |
237 | information. | |
238 | */ | |
328f5751 | 239 | bool GetColumn(int col, wxListItem& item) const; |
23324ae1 FM |
240 | |
241 | /** | |
242 | Returns the number of columns. | |
243 | */ | |
328f5751 | 244 | int GetColumnCount() const; |
23324ae1 FM |
245 | |
246 | /** | |
247 | Gets the column number by visual order index (report view only). | |
248 | */ | |
328f5751 | 249 | int GetColumnIndexFromOrder(int order) const; |
23324ae1 FM |
250 | |
251 | /** | |
252 | Gets the column visual order index (valid in report view only). | |
253 | */ | |
328f5751 | 254 | int GetColumnOrder(int col) const; |
23324ae1 FM |
255 | |
256 | /** | |
257 | Gets the column width (report view only). | |
258 | */ | |
328f5751 | 259 | int GetColumnWidth(int col) const; |
23324ae1 FM |
260 | |
261 | /** | |
262 | Returns the array containing the orders of all columns. On error, an empty | |
263 | array is returned. | |
264 | */ | |
328f5751 | 265 | wxArrayInt GetColumnsOrder() const; |
23324ae1 FM |
266 | |
267 | /** | |
268 | Gets the number of items that can fit vertically in the | |
269 | visible area of the list control (list or report view) | |
270 | or the total number of items in the list control (icon | |
271 | or small icon view). | |
272 | */ | |
328f5751 | 273 | int GetCountPerPage() const; |
23324ae1 FM |
274 | |
275 | /** | |
276 | Returns the edit control being currently used to edit a label. Returns @NULL | |
277 | if no label is being edited. | |
23324ae1 FM |
278 | @b NB: It is currently only implemented for wxMSW and the generic version, |
279 | not for the native Mac OS X version. | |
280 | */ | |
328f5751 | 281 | wxTextCtrl* GetEditControl() const; |
23324ae1 FM |
282 | |
283 | /** | |
4cc4bfaf | 284 | Returns the specified image list. @a which may be one of: |
3c4f71cc | 285 | |
23324ae1 | 286 | @b wxIMAGE_LIST_NORMAL |
3c4f71cc | 287 | |
23324ae1 | 288 | The normal (large icon) image list. |
3c4f71cc | 289 | |
23324ae1 | 290 | @b wxIMAGE_LIST_SMALL |
3c4f71cc | 291 | |
23324ae1 | 292 | The small icon image list. |
3c4f71cc | 293 | |
23324ae1 | 294 | @b wxIMAGE_LIST_STATE |
3c4f71cc | 295 | |
23324ae1 FM |
296 | The user-defined state image list (unimplemented). |
297 | */ | |
328f5751 | 298 | wxImageList* GetImageList(int which) const; |
23324ae1 FM |
299 | |
300 | /** | |
301 | Gets information about the item. See SetItem() for more | |
302 | information. | |
23324ae1 FM |
303 | You must call @e info.SetId() to the ID of item you're interested in |
304 | before calling this method. | |
305 | */ | |
328f5751 | 306 | bool GetItem(wxListItem& info) const; |
23324ae1 FM |
307 | |
308 | /** | |
309 | Returns the colour for this item. If the item has no specific colour, returns | |
310 | an invalid colour (and not the default background control of the control | |
311 | itself). | |
3c4f71cc | 312 | |
4cc4bfaf | 313 | @see GetItemTextColour() |
23324ae1 | 314 | */ |
328f5751 | 315 | wxColour GetItemBackgroundColour(long item) const; |
23324ae1 FM |
316 | |
317 | /** | |
318 | Returns the number of items in the list control. | |
319 | */ | |
328f5751 | 320 | int GetItemCount() const; |
23324ae1 FM |
321 | |
322 | /** | |
323 | Gets the application-defined data associated with this item. | |
324 | */ | |
328f5751 | 325 | long GetItemData(long item) const; |
23324ae1 FM |
326 | |
327 | /** | |
328 | Returns the item's font. | |
329 | */ | |
328f5751 | 330 | wxFont GetItemFont(long item) const; |
23324ae1 FM |
331 | |
332 | /** | |
333 | Returns the position of the item, in icon or small icon view. | |
334 | */ | |
328f5751 | 335 | bool GetItemPosition(long item, wxPoint& pos) const; |
23324ae1 FM |
336 | |
337 | /** | |
338 | Returns the rectangle representing the item's size and position, in physical | |
339 | coordinates. | |
4cc4bfaf | 340 | @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. |
23324ae1 FM |
341 | */ |
342 | bool GetItemRect(long item, wxRect& rect, | |
328f5751 | 343 | int code = wxLIST_RECT_BOUNDS) const; |
23324ae1 FM |
344 | |
345 | /** | |
346 | Retrieves the spacing between icons in pixels: horizontal spacing is returned | |
347 | as @c x component of the wxSize object and the vertical | |
348 | spacing as its @c y component. | |
349 | */ | |
328f5751 | 350 | wxSize GetItemSpacing() const; |
23324ae1 FM |
351 | |
352 | /** | |
353 | Gets the item state. For a list of state flags, see SetItem(). | |
23324ae1 FM |
354 | The @b stateMask indicates which state flags are of interest. |
355 | */ | |
328f5751 | 356 | int GetItemState(long item, long stateMask) const; |
23324ae1 FM |
357 | |
358 | /** | |
359 | Gets the item text for this item. | |
360 | */ | |
328f5751 | 361 | wxString GetItemText(long item) const; |
23324ae1 FM |
362 | |
363 | /** | |
364 | Returns the colour for this item. If the item has no specific colour, returns | |
365 | an invalid colour (and not the default foreground control of the control itself | |
366 | as this wouldn't allow distinguishing between items having the same colour as | |
367 | the current control foreground and items with default colour which, hence, have | |
368 | always the same colour as the control). | |
369 | */ | |
328f5751 | 370 | wxColour GetItemTextColour(long item) const; |
23324ae1 FM |
371 | |
372 | /** | |
373 | Searches for an item with the given geometry or state, starting from | |
4cc4bfaf | 374 | @a item but excluding the @a item itself. If @a item is -1, |
23324ae1 | 375 | the first item that matches the specified flags will be returned. |
4cc4bfaf | 376 | Returns the first item with given state following @a item or -1 if |
23324ae1 | 377 | no such item found. |
23324ae1 | 378 | This function may be used to find all selected items in the control like this: |
3c4f71cc | 379 | |
4cc4bfaf | 380 | @a geometry can be one of: |
3c4f71cc | 381 | |
23324ae1 | 382 | wxLIST_NEXT_ABOVE |
3c4f71cc | 383 | |
23324ae1 | 384 | Searches for an item above the specified item. |
3c4f71cc | 385 | |
23324ae1 | 386 | wxLIST_NEXT_ALL |
3c4f71cc | 387 | |
23324ae1 | 388 | Searches for subsequent item by index. |
3c4f71cc | 389 | |
23324ae1 | 390 | wxLIST_NEXT_BELOW |
3c4f71cc | 391 | |
23324ae1 | 392 | Searches for an item below the specified item. |
3c4f71cc | 393 | |
23324ae1 | 394 | wxLIST_NEXT_LEFT |
3c4f71cc | 395 | |
23324ae1 | 396 | Searches for an item to the left of the specified item. |
3c4f71cc | 397 | |
23324ae1 | 398 | wxLIST_NEXT_RIGHT |
3c4f71cc | 399 | |
23324ae1 | 400 | Searches for an item to the right of the specified item. |
3c4f71cc | 401 | |
23324ae1 FM |
402 | @b NB: this parameter is only supported by wxMSW currently and ignored on |
403 | other platforms. | |
4cc4bfaf | 404 | @a state can be a bitlist of the following: |
3c4f71cc | 405 | |
23324ae1 | 406 | wxLIST_STATE_DONTCARE |
3c4f71cc | 407 | |
23324ae1 | 408 | Don't care what the state is. |
3c4f71cc | 409 | |
23324ae1 | 410 | wxLIST_STATE_DROPHILITED |
3c4f71cc | 411 | |
23324ae1 | 412 | The item indicates it is a drop target. |
3c4f71cc | 413 | |
23324ae1 | 414 | wxLIST_STATE_FOCUSED |
3c4f71cc | 415 | |
23324ae1 | 416 | The item has the focus. |
3c4f71cc | 417 | |
23324ae1 | 418 | wxLIST_STATE_SELECTED |
3c4f71cc | 419 | |
23324ae1 | 420 | The item is selected. |
3c4f71cc | 421 | |
23324ae1 | 422 | wxLIST_STATE_CUT |
3c4f71cc | 423 | |
23324ae1 FM |
424 | The item is selected as part of a cut and paste operation. |
425 | */ | |
426 | long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, | |
328f5751 | 427 | int state = wxLIST_STATE_DONTCARE) const; |
23324ae1 FM |
428 | |
429 | /** | |
430 | Returns the number of selected items in the list control. | |
431 | */ | |
328f5751 | 432 | int GetSelectedItemCount() const; |
23324ae1 FM |
433 | |
434 | /** | |
435 | Returns the rectangle representing the size and position, in physical | |
4cc4bfaf | 436 | coordinates, of the given subitem, i.e. the part of the row @a item in the |
23324ae1 | 437 | column @e subItem. |
23324ae1 | 438 | This method is only meaningfull when the wxListCtrl is in the report mode. If |
4cc4bfaf | 439 | @a subItem parameter is equal to the special value |
23324ae1 FM |
440 | @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as |
441 | for GetItemRect(). | |
4cc4bfaf | 442 | @a code can be one of @c wxLIST_RECT_BOUNDS, |
23324ae1 | 443 | @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL. |
3c4f71cc | 444 | |
e54c96f1 | 445 | @wxsince{2.7.0} |
23324ae1 FM |
446 | */ |
447 | bool GetSubItemRect(long item, long subItem, wxRect& rect, | |
328f5751 | 448 | int code = wxLIST_RECT_BOUNDS) const; |
23324ae1 FM |
449 | |
450 | /** | |
451 | Gets the text colour of the list control. | |
452 | */ | |
328f5751 | 453 | wxColour GetTextColour() const; |
23324ae1 FM |
454 | |
455 | /** | |
456 | Gets the index of the topmost visible item when in | |
457 | list or report view. | |
458 | */ | |
328f5751 | 459 | long GetTopItem() const; |
23324ae1 FM |
460 | |
461 | /** | |
462 | Returns the rectangle taken by all items in the control. In other words, if the | |
463 | controls client size were equal to the size of this rectangle, no scrollbars | |
464 | would be needed and no free space would be left. | |
23324ae1 FM |
465 | Note that this function only works in the icon and small icon views, not in |
466 | list or report views (this is a limitation of the native Win32 control). | |
467 | */ | |
328f5751 | 468 | wxRect GetViewRect() const; |
23324ae1 FM |
469 | |
470 | /** | |
471 | Determines which item (if any) is at the specified point, | |
472 | giving details in @e flags. Returns index of the item or @c wxNOT_FOUND | |
473 | if no item is at the specified point. | |
4cc4bfaf | 474 | @a flags will be a combination of the following flags: |
3c4f71cc | 475 | |
23324ae1 | 476 | wxLIST_HITTEST_ABOVE |
3c4f71cc | 477 | |
23324ae1 | 478 | Above the client area. |
3c4f71cc | 479 | |
23324ae1 | 480 | wxLIST_HITTEST_BELOW |
3c4f71cc | 481 | |
23324ae1 | 482 | Below the client area. |
3c4f71cc | 483 | |
23324ae1 | 484 | wxLIST_HITTEST_NOWHERE |
3c4f71cc | 485 | |
23324ae1 | 486 | In the client area but below the last item. |
3c4f71cc | 487 | |
23324ae1 | 488 | wxLIST_HITTEST_ONITEMICON |
3c4f71cc | 489 | |
23324ae1 | 490 | On the bitmap associated with an item. |
3c4f71cc | 491 | |
23324ae1 | 492 | wxLIST_HITTEST_ONITEMLABEL |
3c4f71cc | 493 | |
23324ae1 | 494 | On the label (string) associated with an item. |
3c4f71cc | 495 | |
23324ae1 | 496 | wxLIST_HITTEST_ONITEMRIGHT |
3c4f71cc | 497 | |
23324ae1 | 498 | In the area to the right of an item. |
3c4f71cc | 499 | |
23324ae1 | 500 | wxLIST_HITTEST_ONITEMSTATEICON |
3c4f71cc | 501 | |
23324ae1 | 502 | On the state icon for a tree view item that is in a user-defined state. |
3c4f71cc | 503 | |
23324ae1 | 504 | wxLIST_HITTEST_TOLEFT |
3c4f71cc | 505 | |
23324ae1 | 506 | To the right of the client area. |
3c4f71cc | 507 | |
23324ae1 | 508 | wxLIST_HITTEST_TORIGHT |
3c4f71cc | 509 | |
23324ae1 | 510 | To the left of the client area. |
3c4f71cc | 511 | |
23324ae1 | 512 | wxLIST_HITTEST_ONITEM |
3c4f71cc | 513 | |
23324ae1 FM |
514 | Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL, |
515 | wxLIST_HITTEST_ONITEMSTATEICON. | |
3c4f71cc | 516 | |
4cc4bfaf | 517 | If @a ptrSubItem is not @NULL and the wxListCtrl is in the report |
7c913512 | 518 | mode the subitem (or column) number will also be provided. |
23324ae1 FM |
519 | This feature is only available in version 2.7.0 or higher and is currently only |
520 | implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on | |
4cc4bfaf | 521 | the host system or the value stored in @a ptrSubItem will be always -1. To |
23324ae1 FM |
522 | compile this feature into wxWidgets library you need to have access to |
523 | commctrl.h of version 4.70 that is provided by Microsoft. | |
524 | */ | |
525 | long HitTest(const wxPoint& point, int& flags, | |
328f5751 | 526 | long* ptrSubItem) const; |
23324ae1 FM |
527 | |
528 | //@{ | |
529 | /** | |
530 | For report view mode (only), inserts a column. For more details, see SetItem(). | |
531 | */ | |
532 | long InsertColumn(long col, wxListItem& info); | |
7c913512 FM |
533 | long InsertColumn(long col, const wxString& heading, |
534 | int format = wxLIST_FORMAT_LEFT, | |
535 | int width = -1); | |
23324ae1 FM |
536 | //@} |
537 | ||
538 | //@{ | |
539 | /** | |
540 | Insert an image/string item. | |
3c4f71cc | 541 | |
7c913512 | 542 | @param info |
4cc4bfaf | 543 | wxListItem object |
7c913512 | 544 | @param index |
4cc4bfaf | 545 | Index of the new item, supplied by the application |
7c913512 | 546 | @param label |
4cc4bfaf | 547 | String label |
7c913512 | 548 | @param imageIndex |
4cc4bfaf | 549 | index into the image list associated with this control and view style |
23324ae1 FM |
550 | */ |
551 | long InsertItem(wxListItem& info); | |
7c913512 FM |
552 | long InsertItem(long index, const wxString& label); |
553 | long InsertItem(long index, int imageIndex); | |
554 | long InsertItem(long index, const wxString& label, | |
555 | int imageIndex); | |
23324ae1 FM |
556 | //@} |
557 | ||
558 | /** | |
559 | This function may be overloaded in the derived class for a control with | |
560 | @c wxLC_VIRTUAL style. It should return the attribute for the | |
561 | for the specified @c item or @NULL to use the default appearance | |
562 | parameters. | |
7c913512 | 563 | wxListCtrl will not delete the pointer or keep a reference of it. You can |
23324ae1 | 564 | return the same wxListItemAttr pointer for every OnGetItemAttr call. |
23324ae1 | 565 | The base class version always returns @NULL. |
3c4f71cc | 566 | |
4cc4bfaf FM |
567 | @see OnGetItemImage(), OnGetItemColumnImage(), |
568 | OnGetItemText() | |
23324ae1 | 569 | */ |
328f5751 | 570 | virtual wxListItemAttr* OnGetItemAttr(long item) const; |
23324ae1 FM |
571 | |
572 | /** | |
573 | Overload this function in the derived class for a control with | |
574 | @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image | |
575 | index for the given line and column. | |
23324ae1 FM |
576 | The base class version always calls OnGetItemImage for the first column, else |
577 | it returns -1. | |
3c4f71cc | 578 | |
4cc4bfaf FM |
579 | @see OnGetItemText(), OnGetItemImage(), |
580 | OnGetItemAttr() | |
23324ae1 | 581 | */ |
328f5751 | 582 | virtual int OnGetItemColumnImage(long item, long column) const; |
23324ae1 FM |
583 | |
584 | /** | |
585 | This function must be overloaded in the derived class for a control with | |
586 | @c wxLC_VIRTUAL style having an @ref setimagelist() "image list" | |
587 | (if the control doesn't have an image list, it is not necessary to overload | |
588 | it). It should return the index of the items image in the controls image list | |
589 | or -1 for no image. | |
590 | In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for | |
591 | the first column of each line. | |
23324ae1 | 592 | The base class version always returns -1. |
3c4f71cc | 593 | |
4cc4bfaf FM |
594 | @see OnGetItemText(), OnGetItemColumnImage(), |
595 | OnGetItemAttr() | |
23324ae1 | 596 | */ |
328f5751 | 597 | virtual int OnGetItemImage(long item) const; |
23324ae1 FM |
598 | |
599 | /** | |
600 | This function @b must be overloaded in the derived class for a control with | |
601 | @c wxLC_VIRTUAL style. It should return the string containing the text of | |
4cc4bfaf | 602 | the given @a column for the specified @c item. |
3c4f71cc | 603 | |
4cc4bfaf FM |
604 | @see SetItemCount(), OnGetItemImage(), |
605 | OnGetItemColumnImage(), OnGetItemAttr() | |
23324ae1 | 606 | */ |
328f5751 | 607 | virtual wxString OnGetItemText(long item, long column) const; |
23324ae1 FM |
608 | |
609 | /** | |
610 | Redraws the given @e item. This is only useful for the virtual list controls | |
611 | as without calling this function the displayed value of the item doesn't change | |
612 | even when the underlying data does change. | |
3c4f71cc | 613 | |
4cc4bfaf | 614 | @see RefreshItems() |
23324ae1 FM |
615 | */ |
616 | void RefreshItem(long item); | |
617 | ||
618 | /** | |
4cc4bfaf | 619 | Redraws the items between @a itemFrom and @e itemTo. The starting item |
23324ae1 | 620 | must be less than or equal to the ending one. |
23324ae1 FM |
621 | Just as RefreshItem() this is only useful for |
622 | virtual list controls. | |
623 | */ | |
624 | void RefreshItems(long itemFrom, long itemTo); | |
625 | ||
626 | /** | |
627 | Scrolls the list control. If in icon, small icon or report view mode, | |
4cc4bfaf FM |
628 | @a dx specifies the number of pixels to scroll. If in list view mode, |
629 | @a dx specifies the number of columns to scroll. @a dy always specifies | |
23324ae1 | 630 | the number of pixels to scroll vertically. |
23324ae1 FM |
631 | @b NB: This method is currently only implemented in the Windows version. |
632 | */ | |
633 | bool ScrollList(int dx, int dy); | |
634 | ||
635 | /** | |
636 | Sets the background colour (GetBackgroundColour already implicit in | |
637 | wxWindow class). | |
638 | */ | |
639 | void SetBackgroundColour(const wxColour& col); | |
640 | ||
641 | /** | |
642 | Sets information about this column. See SetItem() for more | |
643 | information. | |
644 | */ | |
645 | bool SetColumn(int col, wxListItem& item); | |
646 | ||
647 | /** | |
648 | Sets the column width. | |
4cc4bfaf | 649 | @a width can be a width in pixels or wxLIST_AUTOSIZE (-1) or |
23324ae1 FM |
650 | wxLIST_AUTOSIZE_USEHEADER (-2). |
651 | wxLIST_AUTOSIZE will resize the column to the length of its longest item. | |
652 | wxLIST_AUTOSIZE_USEHEADER | |
653 | will resize the column to the length of the header (Win32) or 80 pixels (other | |
654 | platforms). | |
4cc4bfaf | 655 | In small or normal icon view, @a col must be -1, and the column width is set |
23324ae1 FM |
656 | for all columns. |
657 | */ | |
658 | bool SetColumnWidth(int col, int width); | |
659 | ||
660 | /** | |
4cc4bfaf | 661 | Sets the order of all columns at once. The @a orders array must have the |
23324ae1 FM |
662 | same number elements as the number of columns and contain each position exactly |
663 | once. | |
23324ae1 FM |
664 | This function is valid in report view only. |
665 | */ | |
328f5751 | 666 | bool SetColumnOrder(const wxArrayInt& orders) const; |
23324ae1 FM |
667 | |
668 | /** | |
4cc4bfaf | 669 | Sets the image list associated with the control. @a which is one of |
23324ae1 FM |
670 | wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is |
671 | unimplemented). | |
23324ae1 FM |
672 | This method does not take ownership of the image list, you have to |
673 | delete it yourself. | |
3c4f71cc | 674 | |
4cc4bfaf | 675 | @see AssignImageList() |
23324ae1 FM |
676 | */ |
677 | void SetImageList(wxImageList* imageList, int which); | |
678 | ||
679 | //@{ | |
680 | /** | |
681 | Sets a string field at a particular column. | |
682 | */ | |
683 | bool SetItem(wxListItem& info); | |
7c913512 FM |
684 | long SetItem(long index, int col, const wxStringamp; label, |
685 | int imageId = -1); | |
686 | m_mask m_state field is valid. | |
23324ae1 FM |
687 | |
688 | ||
689 | ||
690 | ||
691 | ||
7c913512 | 692 | wxLIST_MASK_TEXT |
23324ae1 FM |
693 | |
694 | ||
695 | ||
696 | ||
7c913512 | 697 | The m_text field is valid. |
23324ae1 FM |
698 | |
699 | ||
700 | ||
701 | ||
702 | ||
7c913512 | 703 | wxLIST_MASK_IMAGE |
23324ae1 FM |
704 | |
705 | ||
706 | ||
707 | ||
7c913512 | 708 | The m_image field is valid. |
23324ae1 FM |
709 | |
710 | ||
711 | ||
712 | ||
713 | ||
7c913512 | 714 | wxLIST_MASK_DATA |
23324ae1 FM |
715 | |
716 | ||
717 | ||
718 | ||
7c913512 | 719 | The m_data field is valid. |
23324ae1 FM |
720 | |
721 | ||
722 | ||
723 | ||
724 | ||
7c913512 | 725 | wxLIST_MASK_WIDTH |
23324ae1 FM |
726 | |
727 | ||
728 | ||
729 | ||
7c913512 | 730 | The m_width field is valid. |
23324ae1 FM |
731 | |
732 | ||
733 | ||
734 | ||
735 | ||
7c913512 | 736 | wxLIST_MASK_FORMAT |
23324ae1 FM |
737 | |
738 | ||
739 | ||
740 | ||
7c913512 | 741 | The m_format field is valid. |
23324ae1 FM |
742 | |
743 | ||
744 | ||
745 | ||
746 | ||
747 | The m_stateMask and m_state members take flags from the following: | |
748 | ||
749 | ||
750 | ||
751 | ||
752 | ||
753 | ||
754 | ||
7c913512 | 755 | wxLIST_STATE_DONTCARE |
23324ae1 FM |
756 | |
757 | ||
758 | ||
759 | ||
7c913512 | 760 | Don't care what the state is. Win32 only. |
23324ae1 FM |
761 | |
762 | ||
763 | ||
764 | ||
765 | ||
7c913512 | 766 | wxLIST_STATE_DROPHILITED |
23324ae1 FM |
767 | |
768 | ||
769 | ||
770 | ||
7c913512 | 771 | The item is highlighted to receive a drop event. Win32 only. |
23324ae1 FM |
772 | |
773 | ||
774 | ||
775 | ||
776 | ||
7c913512 | 777 | wxLIST_STATE_FOCUSED |
23324ae1 FM |
778 | |
779 | ||
780 | ||
781 | ||
7c913512 | 782 | The item has the focus. |
23324ae1 FM |
783 | |
784 | ||
785 | ||
786 | ||
787 | ||
7c913512 | 788 | wxLIST_STATE_SELECTED |
23324ae1 FM |
789 | |
790 | ||
791 | ||
792 | ||
7c913512 | 793 | The item is selected. |
23324ae1 FM |
794 | |
795 | ||
796 | ||
797 | ||
798 | ||
7c913512 | 799 | wxLIST_STATE_CUT |
23324ae1 FM |
800 | |
801 | ||
802 | ||
803 | ||
7c913512 | 804 | The item is in the cut state. Win32 only. |
23324ae1 FM |
805 | |
806 | ||
807 | ||
808 | ||
809 | ||
7c913512 FM |
810 | The wxListItem object can also contain item-specific colour and font |
811 | information: for this you need to call one of SetTextColour(), | |
812 | SetBackgroundColour() or SetFont() functions on it passing it the colour/font | |
813 | to use. If the colour/font is not specified, the default list control | |
814 | colour/font is used. | |
815 | long SetItem(long index, int col, const wxString& label, | |
816 | int imageId = -1); | |
23324ae1 FM |
817 | //@} |
818 | ||
819 | /** | |
7c913512 FM |
820 | Sets the background colour for this item. This function only works in report |
821 | view. | |
7c913512 FM |
822 | The colour can be retrieved using |
823 | GetItemBackgroundColour(). | |
23324ae1 FM |
824 | */ |
825 | void SetItemBackgroundColour(long item, const wxColour& col); | |
826 | ||
827 | /** | |
7c913512 FM |
828 | Sets the image associated with the item. In report view, you can specify the |
829 | column. | |
830 | The image is an index into the image list associated with the list control. | |
23324ae1 FM |
831 | */ |
832 | bool SetItemColumnImage(long item, long column, int image); | |
833 | ||
834 | /** | |
7c913512 FM |
835 | This method can only be used with virtual list controls. It is used to indicate |
836 | to the control the number of items it contains. After calling it, the main | |
837 | program should be ready to handle calls to various item callbacks (such as | |
838 | wxListCtrl::OnGetItemText) for all items in the range | |
839 | from 0 to @e count. | |
23324ae1 FM |
840 | */ |
841 | void SetItemCount(long count); | |
842 | ||
843 | /** | |
7c913512 | 844 | Associates application-defined data with this item. |
7c913512 FM |
845 | Notice that this function cannot be used to associate pointers with the control |
846 | items, use SetItemPtrData() instead. | |
23324ae1 FM |
847 | */ |
848 | bool SetItemData(long item, long data); | |
849 | ||
850 | /** | |
7c913512 | 851 | Sets the item's font. |
23324ae1 FM |
852 | */ |
853 | void SetItemFont(long item, const wxFont& font); | |
854 | ||
855 | //@{ | |
856 | /** | |
857 | Sets the unselected and selected images associated with the item. The images | |
858 | are indices into the | |
4cc4bfaf | 859 | image list associated with the list control. This form is deprecated: @a |
23324ae1 FM |
860 | selImage is not |
861 | used. | |
862 | */ | |
863 | bool SetItemImage(long item, int image); | |
7c913512 | 864 | bool SetItemImage(long item, int image, int selImage); |
23324ae1 FM |
865 | //@} |
866 | ||
867 | /** | |
868 | Sets the position of the item, in icon or small icon view. Windows only. | |
869 | */ | |
870 | bool SetItemPosition(long item, const wxPoint& pos); | |
871 | ||
872 | /** | |
4cc4bfaf | 873 | Associates application-defined data with this item. The @a data parameter may |
23324ae1 FM |
874 | be either an integer or a pointer cast to the @c wxUIntPtr type which is |
875 | guaranteed to be large enough to be able to contain all integer types and | |
876 | pointers. | |
3c4f71cc | 877 | |
e54c96f1 | 878 | @wxsince{2.8.4} |
23324ae1 FM |
879 | */ |
880 | bool SetItemPtrData(long item, wxUIntPtr data); | |
881 | ||
882 | /** | |
883 | Sets the item state. For a list of state flags, see SetItem(). | |
23324ae1 FM |
884 | The @b stateMask indicates which state flags are valid. |
885 | */ | |
886 | bool SetItemState(long item, long state, long stateMask); | |
887 | ||
888 | /** | |
889 | Sets the item text for this item. | |
890 | */ | |
891 | void SetItemText(long item, const wxString& text); | |
892 | ||
893 | /** | |
894 | Sets the colour for this item. This function only works in report view. | |
23324ae1 FM |
895 | The colour can be retrieved using |
896 | GetItemTextColour(). | |
897 | */ | |
898 | void SetItemTextColour(long item, const wxColour& col); | |
899 | ||
900 | /** | |
901 | Adds or removes a single window style. | |
902 | */ | |
4cc4bfaf | 903 | void SetSingleStyle(long style, bool add = true); |
23324ae1 FM |
904 | |
905 | /** | |
906 | Sets the text colour of the list control. | |
907 | */ | |
908 | void SetTextColour(const wxColour& col); | |
909 | ||
910 | /** | |
911 | Sets the whole window style, deleting all items. | |
912 | */ | |
913 | void SetWindowStyleFlag(long style); | |
914 | ||
915 | /** | |
916 | Call this function to sort the items in the list control. Sorting is done | |
4cc4bfaf | 917 | using the specified @a fnSortCallBack function. This function must have the |
23324ae1 | 918 | following prototype: |
3c4f71cc | 919 | |
23324ae1 FM |
920 | It is called each time when the two items must be compared and should return 0 |
921 | if the items are equal, negative value if the first item is less than the | |
922 | second one and positive value if the first one is greater than the second one | |
923 | (the same convention as used by @c qsort(3)). | |
3c4f71cc | 924 | |
7c913512 | 925 | @param item1 |
4cc4bfaf | 926 | client data associated with the first item (NOT the index). |
7c913512 | 927 | @param item2 |
4cc4bfaf | 928 | client data associated with the second item (NOT the index). |
7c913512 | 929 | @param data |
4cc4bfaf | 930 | the value passed to SortItems() itself. |
23324ae1 FM |
931 | */ |
932 | bool SortItems(wxListCtrlCompare fnSortCallBack, long data); | |
933 | }; | |
934 | ||
935 | ||
e54c96f1 | 936 | |
23324ae1 FM |
937 | /** |
938 | @class wxListEvent | |
939 | @wxheader{listctrl.h} | |
7c913512 | 940 | |
23324ae1 | 941 | A list event holds information about events associated with wxListCtrl objects. |
7c913512 | 942 | |
23324ae1 FM |
943 | @library{wxbase} |
944 | @category{events} | |
7c913512 | 945 | |
e54c96f1 | 946 | @see wxListCtrl |
23324ae1 FM |
947 | */ |
948 | class wxListEvent : public wxNotifyEvent | |
949 | { | |
950 | public: | |
951 | /** | |
952 | Constructor. | |
953 | */ | |
954 | wxListEvent(WXTYPE commandType = 0, int id = 0); | |
955 | ||
956 | /** | |
957 | For @c EVT_LIST_CACHE_HINT event only: return the first item which the | |
958 | list control advises us to cache. | |
959 | */ | |
328f5751 | 960 | long GetCacheFrom() const; |
23324ae1 FM |
961 | |
962 | /** | |
963 | For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive) | |
964 | which the list control advises us to cache. | |
965 | */ | |
328f5751 | 966 | long GetCacheTo() const; |
23324ae1 FM |
967 | |
968 | /** | |
969 | The column position: it is only used with @c COL events. For the column | |
970 | dragging events, it is the column to the left of the divider being dragged, for | |
971 | the column click events it may be -1 if the user clicked in the list control | |
972 | header outside any column. | |
973 | */ | |
328f5751 | 974 | int GetColumn() const; |
23324ae1 FM |
975 | |
976 | /** | |
977 | The data. | |
978 | */ | |
328f5751 | 979 | long GetData() const; |
23324ae1 FM |
980 | |
981 | /** | |
982 | The image. | |
983 | */ | |
328f5751 | 984 | int GetImage() const; |
23324ae1 FM |
985 | |
986 | /** | |
987 | The item index. | |
988 | */ | |
328f5751 | 989 | long GetIndex() const; |
23324ae1 FM |
990 | |
991 | /** | |
992 | An item object, used by some events. See also wxListCtrl::SetItem. | |
993 | */ | |
328f5751 | 994 | const wxListItem GetItem() const; |
23324ae1 FM |
995 | |
996 | /** | |
997 | Key code if the event is a keypress event. | |
998 | */ | |
328f5751 | 999 | int GetKeyCode() const; |
23324ae1 FM |
1000 | |
1001 | /** | |
1002 | The (new) item label for @c EVT_LIST_END_LABEL_EDIT event. | |
1003 | */ | |
328f5751 | 1004 | const wxString GetLabel() const; |
23324ae1 FM |
1005 | |
1006 | /** | |
1007 | The mask. | |
1008 | */ | |
328f5751 | 1009 | long GetMask() const; |
23324ae1 FM |
1010 | |
1011 | /** | |
1012 | The position of the mouse pointer if the event is a drag event. | |
1013 | */ | |
328f5751 | 1014 | wxPoint GetPoint() const; |
23324ae1 FM |
1015 | |
1016 | /** | |
1017 | The text. | |
1018 | */ | |
328f5751 | 1019 | const wxString GetText() const; |
23324ae1 FM |
1020 | |
1021 | /** | |
1022 | This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message | |
1023 | and returns @true if it the label editing has been cancelled by the user | |
1024 | (GetLabel() returns an empty string in this case | |
1025 | but it doesn't allow the application to distinguish between really cancelling | |
1026 | the edit and | |
1027 | the admittedly rare case when the user wants to rename it to an empty string). | |
1028 | */ | |
328f5751 | 1029 | bool IsEditCancelled() const; |
23324ae1 FM |
1030 | }; |
1031 | ||
1032 | ||
e54c96f1 | 1033 | |
23324ae1 FM |
1034 | /** |
1035 | @class wxListItemAttr | |
1036 | @wxheader{listctrl.h} | |
7c913512 | 1037 | |
23324ae1 FM |
1038 | Represents the attributes (color, font, ...) of a |
1039 | wxListCtrl wxListItem. | |
7c913512 | 1040 | |
23324ae1 FM |
1041 | @library{wxbase} |
1042 | @category{FIXME} | |
7c913512 | 1043 | |
e54c96f1 FM |
1044 | @see @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl, |
1045 | wxListItem | |
23324ae1 | 1046 | */ |
7c913512 | 1047 | class wxListItemAttr |
23324ae1 FM |
1048 | { |
1049 | public: | |
1050 | //@{ | |
1051 | /** | |
1052 | Construct a wxListItemAttr with the specified foreground and | |
1053 | background colors and font. | |
1054 | */ | |
1055 | wxListItemAttr(); | |
7c913512 FM |
1056 | wxListItemAttr(const wxColour colText, |
1057 | const wxColour colBack, | |
1058 | const wxFont font); | |
23324ae1 FM |
1059 | //@} |
1060 | ||
1061 | /** | |
1062 | Returns the currently set background color. | |
1063 | */ | |
328f5751 | 1064 | const wxColour GetBackgroundColour() const; |
23324ae1 FM |
1065 | |
1066 | /** | |
1067 | Returns the currently set font. | |
1068 | */ | |
328f5751 | 1069 | const wxFont GetFont() const; |
23324ae1 FM |
1070 | |
1071 | /** | |
1072 | Returns the currently set text color. | |
1073 | */ | |
328f5751 | 1074 | const wxColour GetTextColour() const; |
23324ae1 FM |
1075 | |
1076 | /** | |
1077 | Returns @true if the currently set background color is valid. | |
1078 | */ | |
328f5751 | 1079 | bool HasBackgroundColour() const; |
23324ae1 FM |
1080 | |
1081 | /** | |
1082 | Returns @true if the currently set font is valid. | |
1083 | */ | |
328f5751 | 1084 | bool HasFont() const; |
23324ae1 FM |
1085 | |
1086 | /** | |
1087 | Returns @true if the currently set text color is valid. | |
1088 | */ | |
328f5751 | 1089 | bool HasTextColour() const; |
23324ae1 FM |
1090 | |
1091 | /** | |
1092 | Sets a new background color. | |
1093 | */ | |
1094 | void SetBackgroundColour(const wxColour& colour); | |
1095 | ||
1096 | /** | |
1097 | Sets a new font. | |
1098 | */ | |
1099 | void SetFont(const wxFont& font); | |
1100 | ||
1101 | /** | |
1102 | Sets a new text color. | |
1103 | */ | |
1104 | void SetTextColour(const wxColour& colour); | |
1105 | }; | |
1106 | ||
1107 | ||
e54c96f1 | 1108 | |
23324ae1 FM |
1109 | /** |
1110 | @class wxListView | |
1111 | @wxheader{listctrl.h} | |
7c913512 FM |
1112 | |
1113 | This class currently simply presents a simpler to use interface for the | |
23324ae1 | 1114 | wxListCtrl -- it can be thought of as a @e faade |
7c913512 | 1115 | for that complicated class. Using it is preferable to using |
23324ae1 FM |
1116 | wxListCtrl directly whenever possible because in the |
1117 | future some ports might implement wxListView but not the full set of wxListCtrl | |
1118 | features. | |
7c913512 | 1119 | |
23324ae1 FM |
1120 | Other than different interface, this class is identical to wxListCtrl. In |
1121 | particular, it uses the same events, same window styles and so on. | |
7c913512 | 1122 | |
23324ae1 FM |
1123 | @library{wxcore} |
1124 | @category{ctrl} | |
1125 | @appearance{listview.png} | |
7c913512 | 1126 | |
e54c96f1 | 1127 | @see wxListView::SetColumnImage |
23324ae1 FM |
1128 | */ |
1129 | class wxListView : public wxListCtrl | |
1130 | { | |
1131 | public: | |
1132 | /** | |
1133 | Resets the column image -- after calling this function, no image will be shown. | |
3c4f71cc | 1134 | |
7c913512 | 1135 | @param col |
4cc4bfaf | 1136 | the column to clear image for |
3c4f71cc | 1137 | |
4cc4bfaf | 1138 | @see SetColumnImage() |
23324ae1 FM |
1139 | */ |
1140 | void ClearColumnImage(int col); | |
1141 | ||
1142 | /** | |
1143 | Sets focus to the item with the given @e index. | |
1144 | */ | |
1145 | void Focus(long index); | |
1146 | ||
1147 | /** | |
1148 | Returns the first selected item in a (presumably) multiple selection control. | |
1149 | Together with GetNextSelected() it can be | |
1150 | used to iterate over all selected items in the control. | |
3c4f71cc | 1151 | |
23324ae1 FM |
1152 | @returns The first selected item, if any, -1 otherwise. |
1153 | */ | |
328f5751 | 1154 | long GetFirstSelected() const; |
23324ae1 FM |
1155 | |
1156 | /** | |
1157 | Returns the currently focused item or -1 if none. | |
3c4f71cc | 1158 | |
4cc4bfaf | 1159 | @see IsSelected(), Focus() |
23324ae1 | 1160 | */ |
328f5751 | 1161 | long GetFocusedItem() const; |
23324ae1 FM |
1162 | |
1163 | /** | |
1164 | Used together with GetFirstSelected() to | |
1165 | iterate over all selected items in the control. | |
3c4f71cc | 1166 | |
23324ae1 | 1167 | @returns Returns the next selected item or -1 if there are no more of |
4cc4bfaf | 1168 | them. |
23324ae1 | 1169 | */ |
328f5751 | 1170 | long GetNextSelected(long item) const; |
23324ae1 FM |
1171 | |
1172 | /** | |
4cc4bfaf | 1173 | Returns @true if the item with the given @a index is selected, |
23324ae1 | 1174 | @false otherwise. |
3c4f71cc | 1175 | |
4cc4bfaf | 1176 | @see GetFirstSelected(), GetNextSelected() |
23324ae1 | 1177 | */ |
328f5751 | 1178 | bool IsSelected(long index) const; |
23324ae1 FM |
1179 | |
1180 | /** | |
1181 | Selects or unselects the given item. | |
3c4f71cc | 1182 | |
7c913512 | 1183 | @param n |
4cc4bfaf | 1184 | the item to select or unselect |
7c913512 | 1185 | @param on |
4cc4bfaf | 1186 | if @true (default), selects the item, otherwise unselects it |
3c4f71cc | 1187 | |
4cc4bfaf | 1188 | @see wxListCtrl::SetItemState |
23324ae1 | 1189 | */ |
4cc4bfaf | 1190 | void Select(bool on = true); |
23324ae1 FM |
1191 | |
1192 | /** | |
1193 | Sets the column image for the specified column. To use the column images, the | |
1194 | control must have a valid image list with at least one image. | |
3c4f71cc | 1195 | |
7c913512 | 1196 | @param col |
4cc4bfaf | 1197 | the column to set image for |
7c913512 | 1198 | @param image |
4cc4bfaf | 1199 | the index of the column image in the controls image list |
23324ae1 FM |
1200 | */ |
1201 | void SetColumnImage(int col, int image); | |
1202 | }; | |
1203 | ||
1204 | ||
e54c96f1 | 1205 | |
23324ae1 FM |
1206 | /** |
1207 | @class wxListItem | |
1208 | @wxheader{listctrl.h} | |
7c913512 | 1209 | |
23324ae1 | 1210 | This class stores information about a wxListCtrl item or column. |
7c913512 | 1211 | |
23324ae1 FM |
1212 | @library{wxbase} |
1213 | @category{FIXME} | |
1214 | */ | |
1215 | class wxListItem : public wxObject | |
1216 | { | |
1217 | public: | |
1218 | /** | |
1219 | Constructor. | |
1220 | */ | |
1221 | wxListItem(); | |
1222 | ||
1223 | /** | |
1224 | Resets the item state to the default. | |
1225 | */ | |
1226 | void Clear(); | |
1227 | ||
1228 | /** | |
1229 | Returns the alignment for this item. Can be one of | |
1230 | wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE. | |
1231 | */ | |
328f5751 | 1232 | wxListColumnFormat GetAlign() const; |
23324ae1 FM |
1233 | |
1234 | /** | |
1235 | Returns the background colour for this item. | |
1236 | */ | |
328f5751 | 1237 | wxColour GetBackgroundColour() const; |
23324ae1 FM |
1238 | |
1239 | /** | |
1240 | Returns the zero-based column; meaningful only in report mode. | |
1241 | */ | |
328f5751 | 1242 | int GetColumn() const; |
23324ae1 FM |
1243 | |
1244 | /** | |
1245 | Returns client data associated with the control. Please note that | |
1246 | client data is associated with the item and not with subitems. | |
1247 | */ | |
328f5751 | 1248 | long GetData() const; |
23324ae1 FM |
1249 | |
1250 | /** | |
1251 | Returns the font used to display the item. | |
1252 | */ | |
328f5751 | 1253 | wxFont GetFont() const; |
23324ae1 FM |
1254 | |
1255 | /** | |
1256 | Returns the zero-based item position. | |
1257 | */ | |
328f5751 | 1258 | long GetId() const; |
23324ae1 FM |
1259 | |
1260 | /** | |
1261 | Returns the zero-based index of the image | |
1262 | associated with the item into the image list. | |
1263 | */ | |
328f5751 | 1264 | int GetImage() const; |
23324ae1 FM |
1265 | |
1266 | /** | |
1267 | Returns a bit mask indicating which fields of the structure are valid; | |
1268 | can be any combination of the following values: | |
3c4f71cc | 1269 | |
23324ae1 | 1270 | wxLIST_MASK_STATE |
3c4f71cc | 1271 | |
23324ae1 | 1272 | @b GetState is valid. |
3c4f71cc | 1273 | |
23324ae1 | 1274 | wxLIST_MASK_TEXT |
3c4f71cc | 1275 | |
23324ae1 | 1276 | @b GetText is valid. |
3c4f71cc | 1277 | |
23324ae1 | 1278 | wxLIST_MASK_IMAGE |
3c4f71cc | 1279 | |
23324ae1 | 1280 | @b GetImage is valid. |
3c4f71cc | 1281 | |
23324ae1 | 1282 | wxLIST_MASK_DATA |
3c4f71cc | 1283 | |
23324ae1 | 1284 | @b GetData is valid. |
3c4f71cc | 1285 | |
23324ae1 | 1286 | wxLIST_MASK_WIDTH |
3c4f71cc | 1287 | |
23324ae1 | 1288 | @b GetWidth is valid. |
3c4f71cc | 1289 | |
23324ae1 | 1290 | wxLIST_MASK_FORMAT |
3c4f71cc | 1291 | |
23324ae1 FM |
1292 | @b GetFormat is valid. |
1293 | */ | |
328f5751 | 1294 | long GetMask() const; |
23324ae1 FM |
1295 | |
1296 | /** | |
1297 | Returns a bit field representing the state of the item. Can be any | |
1298 | combination of: | |
3c4f71cc | 1299 | |
23324ae1 | 1300 | wxLIST_STATE_DONTCARE |
3c4f71cc | 1301 | |
7c913512 | 1302 | Don't care what the state is. Win32 only. |
3c4f71cc | 1303 | |
23324ae1 | 1304 | wxLIST_STATE_DROPHILITED |
3c4f71cc | 1305 | |
7c913512 | 1306 | The item is highlighted to receive a drop event. Win32 only. |
3c4f71cc | 1307 | |
23324ae1 | 1308 | wxLIST_STATE_FOCUSED |
3c4f71cc | 1309 | |
23324ae1 | 1310 | The item has the focus. |
3c4f71cc | 1311 | |
23324ae1 | 1312 | wxLIST_STATE_SELECTED |
3c4f71cc | 1313 | |
23324ae1 | 1314 | The item is selected. |
3c4f71cc | 1315 | |
23324ae1 | 1316 | wxLIST_STATE_CUT |
3c4f71cc | 1317 | |
23324ae1 FM |
1318 | The item is in the cut state. Win32 only. |
1319 | */ | |
328f5751 | 1320 | long GetState() const; |
23324ae1 FM |
1321 | |
1322 | /** | |
1323 | Returns the label/header text. | |
1324 | */ | |
328f5751 | 1325 | const wxString GetText() const; |
23324ae1 FM |
1326 | |
1327 | /** | |
1328 | Returns the text colour. | |
1329 | */ | |
328f5751 | 1330 | wxColour GetTextColour() const; |
23324ae1 FM |
1331 | |
1332 | /** | |
1333 | Meaningful only for column headers in report mode. Returns the column width. | |
1334 | */ | |
328f5751 | 1335 | int GetWidth() const; |
23324ae1 FM |
1336 | |
1337 | /** | |
1338 | Sets the alignment for the item. See also | |
1339 | GetAlign() | |
1340 | */ | |
1341 | void SetAlign(wxListColumnFormat align); | |
1342 | ||
1343 | /** | |
1344 | Sets the background colour for the item. | |
1345 | */ | |
1346 | void SetBackgroundColour(const wxColour& colBack); | |
1347 | ||
1348 | /** | |
1349 | Sets the zero-based column. Meaningful only in report mode. | |
1350 | */ | |
1351 | void SetColumn(int col); | |
1352 | ||
1353 | //@{ | |
1354 | /** | |
1355 | Sets client data for the item. Please note that | |
1356 | client data is associated with the item and not with subitems. | |
1357 | */ | |
1358 | void SetData(long data); | |
7c913512 | 1359 | void SetData(void* data); |
23324ae1 FM |
1360 | //@} |
1361 | ||
1362 | /** | |
1363 | Sets the font for the item. | |
1364 | */ | |
1365 | void SetFont(const wxFont& font); | |
1366 | ||
1367 | /** | |
1368 | Sets the zero-based item position. | |
1369 | */ | |
1370 | void SetId(long id); | |
1371 | ||
1372 | /** | |
1373 | Sets the zero-based index of the image associated with the item | |
1374 | into the image list. | |
1375 | */ | |
1376 | void SetImage(int image); | |
1377 | ||
1378 | /** | |
1379 | Sets the mask of valid fields. See GetMask(). | |
1380 | */ | |
1381 | void SetMask(long mask); | |
1382 | ||
1383 | /** | |
1384 | Sets the item state flags (note that the valid state flags are influenced | |
1385 | by the value of the state mask, see | |
1386 | wxListItem::SetStateMask). | |
1387 | See GetState() for valid flag | |
1388 | values. | |
1389 | */ | |
1390 | void SetState(long state); | |
1391 | ||
1392 | /** | |
1393 | Sets the bitmask that is used to determine which of the state flags | |
1394 | are to be set. See also SetState(). | |
1395 | */ | |
1396 | void SetStateMask(long stateMask); | |
1397 | ||
1398 | /** | |
1399 | Sets the text label for the item. | |
1400 | */ | |
1401 | void SetText(const wxString& text); | |
1402 | ||
1403 | /** | |
1404 | Sets the text colour for the item. | |
1405 | */ | |
1406 | void SetTextColour(const wxColour& colText); | |
1407 | ||
1408 | /** | |
1409 | Meaningful only for column headers in report mode. Sets the column width. | |
1410 | */ | |
1411 | void SetWidth(int width); | |
1412 | }; | |
e54c96f1 | 1413 |