]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: treectrl.h | |
3 | // Purpose: interface of wxTreeItemData | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxTreeItemData | |
11 | @wxheader{treectrl.h} | |
12 | ||
13 | wxTreeItemData is some (arbitrary) user class associated with some item. The | |
14 | main advantage of having this class is that wxTreeItemData objects are | |
15 | destroyed automatically by the tree and, as this class has virtual destructor, | |
16 | it means that the memory and any other resources associated with a tree item | |
17 | will be automatically freed when it is deleted. Note that we don't use wxObject | |
18 | as the base class for wxTreeItemData because the size of this class is | |
19 | critical: in many applications, each tree leaf will have wxTreeItemData | |
20 | associated with it and the number of leaves may be quite big. | |
21 | ||
22 | Also please note that because the objects of this class are deleted by the tree | |
23 | using the operator @c delete, they must always be allocated on the heap | |
24 | using @c new. | |
25 | ||
26 | @library{wxcore} | |
27 | @category{FIXME} | |
28 | ||
29 | @see wxTreeCtrl | |
30 | */ | |
31 | class wxTreeItemData : public wxClientData | |
32 | { | |
33 | public: | |
34 | /** | |
35 | Default constructor. | |
36 | ||
37 | In addition, the following methods are added in wxPython for accessing | |
38 | the object: | |
39 | ||
40 | @b GetData() | |
41 | ||
42 | Returns a reference to the Python Object | |
43 | ||
44 | @b SetData(obj) | |
45 | ||
46 | Associates a new Python Object with the | |
47 | wxTreeItemData | |
48 | */ | |
49 | wxTreeItemData(); | |
50 | ||
51 | /** | |
52 | Virtual destructor. | |
53 | */ | |
54 | ~wxTreeItemData(); | |
55 | ||
56 | /** | |
57 | Returns the item associated with this node. | |
58 | */ | |
59 | const wxTreeItemId GetId(); | |
60 | ||
61 | /** | |
62 | Sets the item associated with this node. | |
63 | */ | |
64 | void SetId(const wxTreeItemId& id); | |
65 | }; | |
66 | ||
67 | ||
68 | ||
69 | /** | |
70 | @class wxTreeCtrl | |
71 | @wxheader{treectrl.h} | |
72 | ||
73 | A tree control presents information as a hierarchy, with items that may be | |
74 | expanded | |
75 | to show further items. Items in a tree control are referenced by wxTreeItemId | |
76 | handles, | |
77 | which may be tested for validity by calling wxTreeItemId::IsOk. | |
78 | ||
79 | To intercept events from a tree control, use the event table macros described | |
80 | in wxTreeEvent. | |
81 | ||
82 | @beginStyleTable | |
83 | @style{wxTR_EDIT_LABELS} | |
84 | Use this style if you wish the user to be able to edit labels in | |
85 | the tree control. | |
86 | @style{wxTR_NO_BUTTONS} | |
87 | For convenience to document that no buttons are to be drawn. | |
88 | @style{wxTR_HAS_BUTTONS} | |
89 | Use this style to show + and - buttons to the left of parent items. | |
90 | @style{wxTR_NO_LINES} | |
91 | Use this style to hide vertical level connectors. | |
92 | @style{wxTR_FULL_ROW_HIGHLIGHT} | |
93 | Use this style to have the background colour and the selection | |
94 | highlight extend over the entire horizontal row of the tree control | |
95 | window. (This flag is ignored under Windows unless you specify | |
96 | wxTR_NO_LINES as well.) | |
97 | @style{wxTR_LINES_AT_ROOT} | |
98 | Use this style to show lines between root nodes. Only applicable if | |
99 | wxTR_HIDE_ROOT is set and wxTR_NO_LINES is not set. | |
100 | @style{wxTR_HIDE_ROOT} | |
101 | Use this style to suppress the display of the root node, | |
102 | effectively causing the first-level nodes to appear as a series of | |
103 | root nodes. | |
104 | @style{wxTR_ROW_LINES} | |
105 | Use this style to draw a contrasting border between displayed rows. | |
106 | @style{wxTR_HAS_VARIABLE_ROW_HEIGHT} | |
107 | Use this style to cause row heights to be just big enough to fit | |
108 | the content. If not set, all rows use the largest row height. The | |
109 | default is that this flag is unset. Generic only. | |
110 | @style{wxTR_SINGLE} | |
111 | For convenience to document that only one item may be selected at a | |
112 | time. Selecting another item causes the current selection, if any, | |
113 | to be deselected. This is the default. | |
114 | @style{wxTR_MULTIPLE} | |
115 | Use this style to allow a range of items to be selected. If a | |
116 | second range is selected, the current range, if any, is deselected. | |
117 | @style{wxTR_DEFAULT_STYLE} | |
118 | The set of flags that are closest to the defaults for the native | |
119 | control for a particular toolkit. | |
120 | @endStyleTable | |
121 | ||
122 | @library{wxcore} | |
123 | @category{ctrl} | |
124 | @appearance{treectrl.png} | |
125 | ||
126 | @see wxTreeItemData, @ref overview_wxtreectrloverview "wxTreeCtrl overview", | |
127 | wxListBox, wxListCtrl, wxImageList, wxTreeEvent | |
128 | */ | |
129 | class wxTreeCtrl : public wxControl | |
130 | { | |
131 | public: | |
132 | //@{ | |
133 | /** | |
134 | Constructor, creating and showing a tree control. | |
135 | ||
136 | @param parent | |
137 | Parent window. Must not be @NULL. | |
138 | @param id | |
139 | Window identifier. The value wxID_ANY indicates a default value. | |
140 | @param pos | |
141 | Window position. | |
142 | @param size | |
143 | Window size. If wxDefaultSize is specified then the window is | |
144 | sized | |
145 | appropriately. | |
146 | @param style | |
147 | Window style. See wxTreeCtrl. | |
148 | @param validator | |
149 | Window validator. | |
150 | @param name | |
151 | Window name. | |
152 | ||
153 | @see Create(), wxValidator | |
154 | */ | |
155 | wxTreeCtrl(); | |
156 | wxTreeCtrl(wxWindow* parent, wxWindowID id, | |
157 | const wxPoint& pos = wxDefaultPosition, | |
158 | const wxSize& size = wxDefaultSize, | |
159 | long style = wxTR_HAS_BUTTONS, | |
160 | const wxValidator& validator = wxDefaultValidator, | |
161 | const wxString& name = "treeCtrl"); | |
162 | //@} | |
163 | ||
164 | /** | |
165 | Destructor, destroying the tree control. | |
166 | */ | |
167 | ~wxTreeCtrl(); | |
168 | ||
169 | /** | |
170 | Adds the root node to the tree, returning the new item. | |
171 | The @a image and @a selImage parameters are an index within | |
172 | the normal image list specifying the image to use for unselected and | |
173 | selected items, respectively. | |
174 | If @a image -1 and @a selImage is -1, the same image is used for | |
175 | both selected and unselected items. | |
176 | */ | |
177 | wxTreeItemId AddRoot(const wxString& text, int image = -1, | |
178 | int selImage = -1, | |
179 | wxTreeItemData* data = NULL); | |
180 | ||
181 | /** | |
182 | Appends an item to the end of the branch identified by @e parent, return a new | |
183 | item id. | |
184 | The @a image and @a selImage parameters are an index within | |
185 | the normal image list specifying the image to use for unselected and | |
186 | selected items, respectively. | |
187 | If @a image -1 and @a selImage is -1, the same image is used for | |
188 | both selected and unselected items. | |
189 | */ | |
190 | wxTreeItemId AppendItem(const wxTreeItemId& parent, | |
191 | const wxString& text, | |
192 | int image = -1, | |
193 | int selImage = -1, | |
194 | wxTreeItemData* data = NULL); | |
195 | ||
196 | /** | |
197 | Sets the buttons image list. The button images assigned with this method will | |
198 | be automatically deleted by wxTreeCtrl as appropriate | |
199 | (i.e. it takes ownership of the list). | |
200 | Setting or assigning the button image list enables the display of image buttons. | |
201 | Once enabled, the only way to disable the display of button images is to set | |
202 | the button image list to @NULL. | |
203 | This function is only available in the generic version. | |
204 | See also SetButtonsImageList(). | |
205 | */ | |
206 | void AssignButtonsImageList(wxImageList* imageList); | |
207 | ||
208 | /** | |
209 | Sets the normal image list. Image list assigned with this method will | |
210 | be automatically deleted by wxTreeCtrl as appropriate | |
211 | (i.e. it takes ownership of the list). | |
212 | See also SetImageList(). | |
213 | */ | |
214 | void AssignImageList(wxImageList* imageList); | |
215 | ||
216 | /** | |
217 | Sets the state image list. Image list assigned with this method will | |
218 | be automatically deleted by wxTreeCtrl as appropriate | |
219 | (i.e. it takes ownership of the list). | |
220 | See also SetStateImageList(). | |
221 | */ | |
222 | void AssignStateImageList(wxImageList* imageList); | |
223 | ||
224 | /** | |
225 | Collapses the given item. | |
226 | */ | |
227 | void Collapse(const wxTreeItemId& item); | |
228 | ||
229 | /** | |
230 | Collapses the root item. | |
231 | ||
232 | @see ExpandAll() | |
233 | */ | |
234 | void CollapseAll(); | |
235 | ||
236 | /** | |
237 | Collapses this item and all of its children, recursively. | |
238 | ||
239 | @see ExpandAllChildren() | |
240 | */ | |
241 | void CollapseAllChildren(const wxTreeItemId& item); | |
242 | ||
243 | /** | |
244 | Collapses the given item and removes all children. | |
245 | */ | |
246 | void CollapseAndReset(const wxTreeItemId& item); | |
247 | ||
248 | /** | |
249 | Creates the tree control. See wxTreeCtrl() for further details. | |
250 | */ | |
251 | bool wxTreeCtrl(wxWindow* parent, wxWindowID id, | |
252 | const wxPoint& pos = wxDefaultPosition, | |
253 | const wxSize& size = wxDefaultSize, | |
254 | long style = wxTR_HAS_BUTTONS, | |
255 | const wxValidator& validator = wxDefaultValidator, | |
256 | const wxString& name = "treeCtrl"); | |
257 | ||
258 | /** | |
259 | Deletes the specified item. A @c EVT_TREE_DELETE_ITEM event will be | |
260 | generated. | |
261 | This function may cause a subsequent call to GetNextChild to fail. | |
262 | */ | |
263 | void Delete(const wxTreeItemId& item); | |
264 | ||
265 | /** | |
266 | Deletes all items in the control. Note that this may not generate | |
267 | @c EVT_TREE_DELETE_ITEM events under some Windows versions although | |
268 | normally such event is generated for each removed item. | |
269 | */ | |
270 | void DeleteAllItems(); | |
271 | ||
272 | /** | |
273 | Deletes all children of the given item (but not the item itself). Note that | |
274 | this will @b not generate any events unlike | |
275 | Delete() method. | |
276 | If you have called SetItemHasChildren(), you | |
277 | may need to call it again since @e DeleteChildren does not automatically | |
278 | clear the setting. | |
279 | */ | |
280 | void DeleteChildren(const wxTreeItemId& item); | |
281 | ||
282 | /** | |
283 | Starts editing the label of the given item. This function generates a | |
284 | EVT_TREE_BEGIN_LABEL_EDIT event which can be vetoed so that no | |
285 | text control will appear for in-place editing. | |
286 | If the user changed the label (i.e. s/he does not press ESC or leave | |
287 | the text control without changes, a EVT_TREE_END_LABEL_EDIT event | |
288 | will be sent which can be vetoed as well. | |
289 | ||
290 | @see EndEditLabel(), wxTreeEvent | |
291 | */ | |
292 | void EditLabel(const wxTreeItemId& item); | |
293 | ||
294 | /** | |
295 | Ends label editing. If @a cancelEdit is @true, the edit will be cancelled. | |
296 | This function is currently supported under Windows only. | |
297 | ||
298 | @see EditLabel() | |
299 | */ | |
300 | void EndEditLabel(bool cancelEdit); | |
301 | ||
302 | /** | |
303 | Scrolls and/or expands items to ensure that the given item is visible. | |
304 | */ | |
305 | void EnsureVisible(const wxTreeItemId& item); | |
306 | ||
307 | /** | |
308 | Expands the given item. | |
309 | */ | |
310 | void Expand(const wxTreeItemId& item); | |
311 | ||
312 | /** | |
313 | Expands all items in the tree. | |
314 | */ | |
315 | void ExpandAll(); | |
316 | ||
317 | /** | |
318 | Expands the given item and all its children recursively. | |
319 | */ | |
320 | void ExpandAllChildren(const wxTreeItemId& item); | |
321 | ||
322 | /** | |
323 | Retrieves the rectangle bounding the @e item. If @a textOnly is @true, | |
324 | only the rectangle around the item's label will be returned, otherwise the | |
325 | item's image is also taken into account. | |
326 | The return value is @true if the rectangle was successfully retrieved or @c | |
327 | @false | |
328 | if it was not (in this case @a rect is not changed) -- for example, if the | |
329 | item is currently invisible. | |
330 | Notice that the rectangle coordinates are logical, not physical ones. So, for | |
331 | example, the x coordinate may be negative if the tree has a horizontal | |
332 | scrollbar and its position is not 0. | |
333 | */ | |
334 | bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, | |
335 | bool textOnly = false) const; | |
336 | ||
337 | /** | |
338 | Returns the buttons image list (from which application-defined button images | |
339 | are taken). | |
340 | This function is only available in the generic version. | |
341 | */ | |
342 | wxImageList* GetButtonsImageList() const; | |
343 | ||
344 | /** | |
345 | Returns the number of items in the branch. If @a recursively is @true, | |
346 | returns the total number | |
347 | of descendants, otherwise only one level of children is counted. | |
348 | */ | |
349 | unsigned int GetChildrenCount(const wxTreeItemId& item, | |
350 | bool recursively = true) const; | |
351 | ||
352 | /** | |
353 | Returns the number of items in the control. | |
354 | */ | |
355 | unsigned int GetCount() const; | |
356 | ||
357 | /** | |
358 | Returns the edit control being currently used to edit a label. Returns @NULL | |
359 | if no label is being edited. | |
360 | @note It is currently only implemented for wxMSW. | |
361 | */ | |
362 | wxTextCtrl* GetEditControl() const; | |
363 | ||
364 | /** | |
365 | Returns the first child; call GetNextChild() for the next child. | |
366 | For this enumeration function you must pass in a 'cookie' parameter | |
367 | which is opaque for the application but is necessary for the library | |
368 | to make these functions reentrant (i.e. allow more than one | |
369 | enumeration on one and the same object simultaneously). The cookie passed to | |
370 | GetFirstChild and GetNextChild should be the same variable. | |
371 | Returns an invalid tree item (i.e. IsOk() returns @false) if there are no | |
372 | further children. | |
373 | ||
374 | @see GetNextChild(), GetNextSibling() | |
375 | */ | |
376 | wxTreeItemId GetFirstChild(const wxTreeItemId& item, | |
377 | wxTreeItemIdValue& cookie) const; | |
378 | ||
379 | /** | |
380 | Returns the first visible item. | |
381 | */ | |
382 | wxTreeItemId GetFirstVisibleItem() const; | |
383 | ||
384 | /** | |
385 | Returns the normal image list. | |
386 | */ | |
387 | wxImageList* GetImageList() const; | |
388 | ||
389 | /** | |
390 | Returns the current tree control indentation. | |
391 | */ | |
392 | int GetIndent() const; | |
393 | ||
394 | /** | |
395 | Returns the background colour of the item. | |
396 | */ | |
397 | wxColour GetItemBackgroundColour(const wxTreeItemId& item) const; | |
398 | ||
399 | //@{ | |
400 | /** | |
401 | Returns the font of the item label. | |
402 | ||
403 | @see wxTreeItemData | |
404 | ||
405 | @beginWxPythonOnly | |
406 | wxPython provides the following shortcut method: | |
407 | @li GetPyData(item): Returns the Python Object associated with the | |
408 | wxTreeItemData for the given item Id. | |
409 | @endWxPythonOnly | |
410 | */ | |
411 | wxTreeItemData* GetItemData(const wxTreeItemId& item) const; | |
412 | wxFont GetItemFont(const wxTreeItemId& item) const; | |
413 | //@} | |
414 | ||
415 | /** | |
416 | Gets the specified item image. The value of @a which may be: | |
417 | wxTreeItemIcon_Normal to get the normal item image | |
418 | wxTreeItemIcon_Selected to get the selected item image (i.e. the image | |
419 | which is shown when the item is currently selected) | |
420 | wxTreeItemIcon_Expanded to get the expanded image (this only | |
421 | makes sense for items which have children - then this image is shown when the | |
422 | item is expanded and the normal image is shown when it is collapsed) | |
423 | wxTreeItemIcon_SelectedExpanded to get the selected expanded image | |
424 | (which is shown when an expanded item is currently selected) | |
425 | */ | |
426 | int GetItemImage(const wxTreeItemId& item, | |
427 | wxTreeItemIcon which = wxTreeItemIcon_Normal) const; | |
428 | ||
429 | /** | |
430 | Returns the item's parent. | |
431 | */ | |
432 | wxTreeItemId GetItemParent(const wxTreeItemId& item) const; | |
433 | ||
434 | /** | |
435 | Gets the selected item image (this function is obsolete, use | |
436 | @c GetItemImage(item, wxTreeItemIcon_Selected) instead). | |
437 | */ | |
438 | int GetItemSelectedImage(const wxTreeItemId& item) const; | |
439 | ||
440 | /** | |
441 | Returns the item label. | |
442 | */ | |
443 | wxString GetItemText(const wxTreeItemId& item) const; | |
444 | ||
445 | /** | |
446 | Returns the colour of the item label. | |
447 | */ | |
448 | wxColour GetItemTextColour(const wxTreeItemId& item) const; | |
449 | ||
450 | /** | |
451 | Returns the last child of the item (or an invalid tree item if this item has no | |
452 | children). | |
453 | ||
454 | @see GetFirstChild(), GetNextSibling(), | |
455 | GetLastChild() | |
456 | */ | |
457 | wxTreeItemId GetLastChild(const wxTreeItemId& item) const; | |
458 | ||
459 | /** | |
460 | Returns the next child; call GetFirstChild() for the first child. | |
461 | For this enumeration function you must pass in a 'cookie' parameter | |
462 | which is opaque for the application but is necessary for the library | |
463 | to make these functions reentrant (i.e. allow more than one | |
464 | enumeration on one and the same object simultaneously). The cookie passed to | |
465 | GetFirstChild and GetNextChild should be the same. | |
466 | Returns an invalid tree item if there are no further children. | |
467 | ||
468 | @see GetFirstChild() | |
469 | */ | |
470 | wxTreeItemId GetNextChild(const wxTreeItemId& item, | |
471 | wxTreeItemIdValue& cookie) const; | |
472 | ||
473 | /** | |
474 | Returns the next sibling of the specified item; call GetPrevSibling() for the | |
475 | previous sibling. | |
476 | Returns an invalid tree item if there are no further siblings. | |
477 | ||
478 | @see GetPrevSibling() | |
479 | */ | |
480 | wxTreeItemId GetNextSibling(const wxTreeItemId& item) const; | |
481 | ||
482 | /** | |
483 | Returns the next visible item or an invalid item if this item is the last | |
484 | visible one. | |
485 | Notice that the @a item itself must be visible. | |
486 | */ | |
487 | wxTreeItemId GetNextVisible(const wxTreeItemId& item) const; | |
488 | ||
489 | /** | |
490 | Returns the previous sibling of the specified item; call GetNextSibling() for | |
491 | the next sibling. | |
492 | Returns an invalid tree item if there are no further children. | |
493 | ||
494 | @see GetNextSibling() | |
495 | */ | |
496 | wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const; | |
497 | ||
498 | /** | |
499 | Returns the previous visible item or an invalid item if this item is the first | |
500 | visible one. | |
501 | Notice that the @a item itself must be visible. | |
502 | */ | |
503 | wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const; | |
504 | ||
505 | /** | |
506 | Returns @true if the control will use a quick calculation for the best size, | |
507 | looking only at the first and last items. The default is @false. | |
508 | ||
509 | @see SetQuickBestSize() | |
510 | */ | |
511 | bool GetQuickBestSize() const; | |
512 | ||
513 | /** | |
514 | Returns the root item for the tree control. | |
515 | */ | |
516 | wxTreeItemId GetRootItem() const; | |
517 | ||
518 | /** | |
519 | Returns the selection, or an invalid item if there is no selection. | |
520 | This function only works with the controls without wxTR_MULTIPLE style, use | |
521 | GetSelections() for the controls which do have | |
522 | this style. | |
523 | */ | |
524 | wxTreeItemId GetSelection() const; | |
525 | ||
526 | /** | |
527 | Fills the array of tree items passed in with the currently selected items. This | |
528 | function can be called only if the control has the wxTR_MULTIPLE style. | |
529 | Returns the number of selected items. | |
530 | */ | |
531 | unsigned int GetSelections(wxArrayTreeItemIds& selection) const; | |
532 | ||
533 | /** | |
534 | Returns the state image list (from which application-defined state images are | |
535 | taken). | |
536 | */ | |
537 | wxImageList* GetStateImageList() const; | |
538 | ||
539 | /** | |
540 | Calculates which (if any) item is under the given point, returning the tree item | |
541 | id at this point plus extra information @e flags. @a flags is a bitlist of the | |
542 | following: | |
543 | ||
544 | wxTREE_HITTEST_ABOVE | |
545 | ||
546 | Above the client area. | |
547 | ||
548 | wxTREE_HITTEST_BELOW | |
549 | ||
550 | Below the client area. | |
551 | ||
552 | wxTREE_HITTEST_NOWHERE | |
553 | ||
554 | In the client area but below the last item. | |
555 | ||
556 | wxTREE_HITTEST_ONITEMBUTTON | |
557 | ||
558 | On the button associated with an item. | |
559 | ||
560 | wxTREE_HITTEST_ONITEMICON | |
561 | ||
562 | On the bitmap associated with an item. | |
563 | ||
564 | wxTREE_HITTEST_ONITEMINDENT | |
565 | ||
566 | In the indentation associated with an item. | |
567 | ||
568 | wxTREE_HITTEST_ONITEMLABEL | |
569 | ||
570 | On the label (string) associated with an item. | |
571 | ||
572 | wxTREE_HITTEST_ONITEMRIGHT | |
573 | ||
574 | In the area to the right of an item. | |
575 | ||
576 | wxTREE_HITTEST_ONITEMSTATEICON | |
577 | ||
578 | On the state icon for a tree view item that is in a user-defined state. | |
579 | ||
580 | wxTREE_HITTEST_TOLEFT | |
581 | ||
582 | To the right of the client area. | |
583 | ||
584 | wxTREE_HITTEST_TORIGHT | |
585 | ||
586 | To the left of the client area. | |
587 | */ | |
588 | wxTreeItemId HitTest(const wxPoint& point, int& flags) const; | |
589 | ||
590 | //@{ | |
591 | /** | |
592 | Inserts an item after a given one (@e previous) or before one identified by its | |
593 | position (@e before). | |
594 | @a before must be less than the number of children. | |
595 | The @a image and @a selImage parameters are an index within | |
596 | the normal image list specifying the image to use for unselected and | |
597 | selected items, respectively. | |
598 | If @a image -1 and @a selImage is -1, the same image is used for | |
599 | both selected and unselected items. | |
600 | */ | |
601 | wxTreeItemId InsertItem(const wxTreeItemId& parent, | |
602 | const wxTreeItemId& previous, | |
603 | const wxString& text, | |
604 | int image = -1, | |
605 | int selImage = -1, | |
606 | wxTreeItemData* data = NULL); | |
607 | wxTreeItemId InsertItem(const wxTreeItemId& parent, | |
608 | size_t before, | |
609 | const wxString& text, | |
610 | int image = -1, | |
611 | int selImage = -1, | |
612 | wxTreeItemData* data = NULL); | |
613 | //@} | |
614 | ||
615 | /** | |
616 | Returns @true if the given item is in bold state. | |
617 | See also: SetItemBold() | |
618 | */ | |
619 | bool IsBold(const wxTreeItemId& item) const; | |
620 | ||
621 | /** | |
622 | Returns @true if the control is empty (i.e. has no items, even no root one). | |
623 | */ | |
624 | bool IsEmpty() const; | |
625 | ||
626 | /** | |
627 | Returns @true if the item is expanded (only makes sense if it has children). | |
628 | */ | |
629 | bool IsExpanded(const wxTreeItemId& item) const; | |
630 | ||
631 | /** | |
632 | Returns @true if the item is selected. | |
633 | */ | |
634 | bool IsSelected(const wxTreeItemId& item) const; | |
635 | ||
636 | /** | |
637 | Returns @true if the item is visible on the screen. | |
638 | */ | |
639 | bool IsVisible(const wxTreeItemId& item) const; | |
640 | ||
641 | /** | |
642 | Returns @true if the item has children. | |
643 | */ | |
644 | bool ItemHasChildren(const wxTreeItemId& item) const; | |
645 | ||
646 | /** | |
647 | Override this function in the derived class to change the sort order of the | |
648 | items in the tree control. The function should return a negative, zero or | |
649 | positive value if the first item is less than, equal to or greater than the | |
650 | second one. | |
651 | Please note that you @b must use wxRTTI macros | |
652 | DECLARE_DYNAMIC_CLASS() and | |
653 | IMPLEMENT_DYNAMIC_CLASS() if you override this | |
654 | function because otherwise the base class considers that it is not overridden | |
655 | and uses the default comparison, i.e. sorts the items alphabetically, which | |
656 | allows it optimize away the calls to the virtual function completely. | |
657 | See also: SortChildren() | |
658 | */ | |
659 | int OnCompareItems(const wxTreeItemId& item1, | |
660 | const wxTreeItemId& item2); | |
661 | ||
662 | /** | |
663 | Appends an item as the first child of @e parent, return a new item id. | |
664 | The @a image and @a selImage parameters are an index within | |
665 | the normal image list specifying the image to use for unselected and | |
666 | selected items, respectively. | |
667 | If @a image -1 and @a selImage is -1, the same image is used for | |
668 | both selected and unselected items. | |
669 | */ | |
670 | wxTreeItemId PrependItem(const wxTreeItemId& parent, | |
671 | const wxString& text, | |
672 | int image = -1, | |
673 | int selImage = -1, | |
674 | wxTreeItemData* data = NULL); | |
675 | ||
676 | /** | |
677 | Scrolls the specified item into view. | |
678 | */ | |
679 | void ScrollTo(const wxTreeItemId& item); | |
680 | ||
681 | /** | |
682 | Selects the given item. In multiple selection controls, can be also used to | |
683 | deselect a currently selected item if the value of @a select is @false. | |
684 | */ | |
685 | void SelectItem(const wxTreeItemId& item, bool select = true); | |
686 | ||
687 | /** | |
688 | Sets the buttons image list (from which application-defined button images are | |
689 | taken). | |
690 | The button images assigned with this method will | |
691 | @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. | |
692 | Setting or assigning the button image list enables the display of image buttons. | |
693 | Once enabled, the only way to disable the display of button images is to set | |
694 | the button image list to @NULL. | |
695 | This function is only available in the generic version. | |
696 | See also AssignButtonsImageList(). | |
697 | */ | |
698 | void SetButtonsImageList(wxImageList* imageList); | |
699 | ||
700 | /** | |
701 | Sets the normal image list. Image list assigned with this method will | |
702 | @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. | |
703 | See also AssignImageList(). | |
704 | */ | |
705 | void SetImageList(wxImageList* imageList); | |
706 | ||
707 | /** | |
708 | Sets the indentation for the tree control. | |
709 | */ | |
710 | void SetIndent(int indent); | |
711 | ||
712 | /** | |
713 | Sets the colour of the item's background. | |
714 | */ | |
715 | void SetItemBackgroundColour(const wxTreeItemId& item, | |
716 | const wxColour& col); | |
717 | ||
718 | /** | |
719 | Makes item appear in bold font if @a bold parameter is @true or resets it to | |
720 | the normal state. | |
721 | See also: IsBold() | |
722 | */ | |
723 | void SetItemBold(const wxTreeItemId& item, bool bold = true); | |
724 | ||
725 | //@{ | |
726 | /** | |
727 | Gives the item the visual feedback for Drag'n'Drop actions, which is | |
728 | useful if something is dragged from the outside onto the tree control | |
729 | (as opposed to a DnD operation within the tree control, which already | |
730 | is implemented internally). | |
731 | */ | |
732 | void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); | |
733 | wxPython note: | |
734 | SetPyData(item, obj) | |
735 | ||
736 | ||
737 | ||
738 | ||
739 | Associate the given Python | |
740 | Object with the wxTreeItemData for the given item Id. | |
741 | ||
742 | ||
743 | ||
744 | ||
745 | ||
746 | ||
747 | ||
748 | void SetItemDropHighlight(const wxTreeItemId& item, | |
749 | bool highlight = true); | |
750 | //@} | |
751 | ||
752 | /** | |
753 | Sets the item's font. All items in the tree should have the same height to avoid | |
754 | text clipping, so the fonts height should be the same for all of them, | |
755 | although font attributes may vary. | |
756 | ||
757 | @see SetItemBold() | |
758 | */ | |
759 | void SetItemFont(const wxTreeItemId& item, const wxFont& font); | |
760 | ||
761 | /** | |
762 | Force appearance of the button next to the item. This is useful to | |
763 | allow the user to expand the items which don't have any children now, | |
764 | but instead adding them only when needed, thus minimizing memory | |
765 | usage and loading time. | |
766 | */ | |
767 | void SetItemHasChildren(const wxTreeItemId& item, | |
768 | bool hasChildren = true); | |
769 | ||
770 | /** | |
771 | Sets the specified item image. See GetItemImage() | |
772 | for the description of the @a which parameter. | |
773 | */ | |
774 | void SetItemImage(const wxTreeItemId& item, int image, | |
775 | wxTreeItemIcon which = wxTreeItemIcon_Normal); | |
776 | ||
777 | /** | |
778 | Sets the selected item image (this function is obsolete, use | |
779 | @c SetItemImage(item, wxTreeItemIcon_Selected) instead). | |
780 | */ | |
781 | void SetItemSelectedImage(const wxTreeItemId& item, int selImage); | |
782 | ||
783 | /** | |
784 | Sets the item label. | |
785 | */ | |
786 | void SetItemText(const wxTreeItemId& item, const wxString& text); | |
787 | ||
788 | /** | |
789 | Sets the colour of the item's text. | |
790 | */ | |
791 | void SetItemTextColour(const wxTreeItemId& item, | |
792 | const wxColour& col); | |
793 | ||
794 | /** | |
795 | If @true is passed, specifies that the control will use a quick calculation for | |
796 | the best size, | |
797 | looking only at the first and last items. Otherwise, it will look at all items. | |
798 | The default is @false. | |
799 | ||
800 | @see GetQuickBestSize() | |
801 | */ | |
802 | void SetQuickBestSize(bool quickBestSize); | |
803 | ||
804 | /** | |
805 | Sets the state image list (from which application-defined state images are | |
806 | taken). | |
807 | Image list assigned with this method will | |
808 | @b not be deleted by wxTreeCtrl's destructor, you must delete it yourself. | |
809 | See also AssignStateImageList(). | |
810 | */ | |
811 | void SetStateImageList(wxImageList* imageList); | |
812 | ||
813 | /** | |
814 | Sets the mode flags associated with the display of the tree control. | |
815 | The new mode takes effect immediately. | |
816 | (Generic only; MSW ignores changes.) | |
817 | */ | |
818 | void SetWindowStyle(long styles); | |
819 | ||
820 | /** | |
821 | Sorts the children of the given item using | |
822 | OnCompareItems() method of wxTreeCtrl. You | |
823 | should override that method to change the sort order (the default is ascending | |
824 | case-sensitive alphabetical order). | |
825 | ||
826 | @see wxTreeItemData, OnCompareItems() | |
827 | */ | |
828 | void SortChildren(const wxTreeItemId& item); | |
829 | ||
830 | /** | |
831 | Toggles the given item between collapsed and expanded states. | |
832 | */ | |
833 | void Toggle(const wxTreeItemId& item); | |
834 | ||
835 | /** | |
836 | Toggles the given item between selected and unselected states. For | |
837 | multiselection controls only. | |
838 | */ | |
839 | void ToggleItemSelection(const wxTreeItemId& item); | |
840 | ||
841 | /** | |
842 | Removes the selection from the currently selected item (if any). | |
843 | */ | |
844 | void Unselect(); | |
845 | ||
846 | /** | |
847 | This function either behaves the same as Unselect() | |
848 | if the control doesn't have wxTR_MULTIPLE style, or removes the selection from | |
849 | all items if it does have this style. | |
850 | */ | |
851 | void UnselectAll(); | |
852 | ||
853 | /** | |
854 | Unselects the given item. This works in multiselection controls only. | |
855 | */ | |
856 | void UnselectItem(const wxTreeItemId& item); | |
857 | }; | |
858 | ||
859 | ||
860 | ||
861 | /** | |
862 | @class wxTreeEvent | |
863 | @wxheader{treectrl.h} | |
864 | ||
865 | A tree event holds information about events associated with wxTreeCtrl objects. | |
866 | ||
867 | @library{wxbase} | |
868 | @category{events} | |
869 | ||
870 | @see wxTreeCtrl | |
871 | */ | |
872 | class wxTreeEvent : public wxNotifyEvent | |
873 | { | |
874 | public: | |
875 | /** | |
876 | ) | |
877 | Constructor, used by wxWidgets itself only. | |
878 | */ | |
879 | wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree); | |
880 | ||
881 | /** | |
882 | Returns the item (valid for all events). | |
883 | */ | |
884 | wxTreeItemId GetItem() const; | |
885 | ||
886 | /** | |
887 | Returns the key code if the event is a key event. Use | |
888 | GetKeyEvent() to get the values of the | |
889 | modifier keys for this event (i.e. Shift or Ctrl). | |
890 | */ | |
891 | int GetKeyCode() const; | |
892 | ||
893 | /** | |
894 | Returns the key event for @c EVT_TREE_KEY_DOWN events. | |
895 | */ | |
896 | const wxKeyEvent GetKeyEvent() const; | |
897 | ||
898 | /** | |
899 | Returns the label if the event is a begin or end edit label event. | |
900 | */ | |
901 | const wxString GetLabel() const; | |
902 | ||
903 | /** | |
904 | Returns the old item index (valid for EVT_TREE_ITEM_CHANGING and CHANGED events) | |
905 | */ | |
906 | wxTreeItemId GetOldItem() const; | |
907 | ||
908 | /** | |
909 | Returns the position of the mouse pointer if the event is a drag or | |
910 | menu-context event. | |
911 | In both cases the position is in client coordinates - i.e. relative to the | |
912 | wxTreeCtrl | |
913 | window (so that you can pass it directly to e.g. wxWindow::PopupMenu). | |
914 | */ | |
915 | wxPoint GetPoint() const; | |
916 | ||
917 | /** | |
918 | Returns @true if the label edit was cancelled. This should be | |
919 | called from within an EVT_TREE_END_LABEL_EDIT handler. | |
920 | */ | |
921 | bool IsEditCancelled() const; | |
922 | ||
923 | /** | |
924 | Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP events). | |
925 | Windows only. | |
926 | */ | |
927 | void SetToolTip(const wxString& tooltip); | |
928 | }; | |
929 |