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