]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/dataview.h
no changes, just use CPPUNIT_ASSERT_EQUAL instead of CPPUNIT_ASSERT
[wxWidgets.git] / interface / wx / dataview.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: dataview.h
3 // Purpose: interface of wxDataViewIconText
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxDataViewIconText
11
12 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
13 This class can be converted to and from a wxVariant.
14
15 @library{wxadv}
16 @category{dvc}
17 */
18 class wxDataViewIconText : public wxObject
19 {
20 public:
21 //@{
22 /**
23 Constructor.
24 */
25 wxDataViewIconText(const wxString& text = wxEmptyString,
26 const wxIcon& icon = wxNullIcon);
27 wxDataViewIconText(const wxDataViewIconText& other);
28 //@}
29
30 /**
31 Gets the icon.
32 */
33 const wxIcon& GetIcon() const;
34
35 /**
36 Gets the text.
37 */
38 wxString GetText() const;
39
40 /**
41 Set the icon.
42 */
43 void SetIcon(const wxIcon& icon);
44
45 /**
46 Set the text.
47 */
48 void SetText(const wxString& text);
49 };
50
51
52
53 /**
54 @class wxDataViewEvent
55
56 This is the event class for the wxDataViewCtrl notifications.
57
58 @library{wxadv}
59 @category{events,dvc}
60 */
61 class wxDataViewEvent : public wxNotifyEvent
62 {
63 public:
64 //@{
65 /**
66 Constructor. Typically used by wxWidgets internals only.
67 */
68 wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
69 int winid = 0);
70 wxDataViewEvent(const wxDataViewEvent& event);
71 //@}
72
73 /**
74 Used to clone the event.
75 */
76 wxEvent* Clone() const;
77
78 /**
79 Returns the position of the column in the control or -1
80 if no column field was set by the event emitter.
81 */
82 int GetColumn() const;
83
84 /**
85 Returns a pointer to the wxDataViewColumn from which
86 the event was emitted or @NULL.
87 */
88 wxDataViewColumn* GetDataViewColumn() const;
89
90 /**
91 Returns the wxDataViewModel associated with the event.
92 */
93 wxDataViewModel* GetModel() const;
94
95 /**
96 Returns a the position of a context menu event in screen coordinates.
97 */
98 wxPoint GetPosition() const;
99
100 /**
101 Returns a reference to a value.
102 */
103 const wxVariant& GetValue() const;
104
105 /**
106 Sets the column index associated with this event.
107 */
108 void SetColumn(int col);
109
110 /**
111 For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
112 */
113 void SetDataViewColumn(wxDataViewColumn* col);
114
115 /**
116 Sets the dataview model associated with this event.
117 */
118 void SetModel(wxDataViewModel* model);
119
120 /**
121 Sets the value associated with this event.
122 */
123 void SetValue(const wxVariant& value);
124 };
125
126
127
128 /**
129 @class wxDataViewModel
130
131 wxDataViewModel is the base class for all data model to be displayed by a
132 wxDataViewCtrl.
133
134 All other models derive from it and must implement its pure virtual functions
135 in order to define a complete data model. In detail, you need to override
136 wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren,
137 wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and
138 wxDataViewModel::GetValue in order to define the data model which acts as an
139 interface between your actual data and the wxDataViewCtrl.
140
141 Since you will usually also allow the wxDataViewCtrl to change your data
142 through its graphical interface, you will also have to override
143 wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
144 to some data has been commited.
145
146 wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
147 to store data and its type in a generic way. wxVariant can be extended to contain
148 almost any data without changes to the original class.
149
150 The data that is presented through this data model is expected to change at
151 run-time. You need to inform the data model when a change happened.
152 Depending on what happened you need to call one of the following methods:
153 - wxDataViewModel::ValueChanged,
154 - wxDataViewModel::ItemAdded,
155 - wxDataViewModel::ItemDeleted,
156 - wxDataViewModel::ItemChanged,
157 - wxDataViewModel::Cleared.
158
159 There are plural forms for notification of addition, change or removal of
160 several item at once. See:
161 - wxDataViewModel::ItemsAdded,
162 - wxDataViewModel::ItemsDeleted,
163 - wxDataViewModel::ItemsChanged.
164
165 Note that wxDataViewModel does not define the position or index of any item
166 in the control because different controls might display the same data differently.
167 wxDataViewModel does provide a wxDataViewModel::Compare method which the
168 wxDataViewCtrl may use to sort the data either in conjunction with a column
169 header or without (see wxDataViewModel::HasDefaultCompare).
170
171 This class maintains a list of wxDataViewModelNotifier which link this class
172 to the specific implementations on the supported platforms so that e.g. calling
173 wxDataViewModel::ValueChanged on this model will just call
174 wxDataViewModelNotifier::ValueChanged for each notifier that has been added.
175 You can also add your own notifier in order to get informed about any changes
176 to the data in the list model.
177
178 Currently wxWidgets provides the following models apart from the base model:
179 wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore.
180
181 Note that wxDataViewModel is reference counted, derives from wxObjectRefData
182 and cannot be deleted directly as it can be shared by several wxDataViewCtrls.
183 This implies that you need to decrease the reference count after
184 associating the model with a control like this:
185
186 @code
187 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
188 wxDataViewModel *musicModel = new MyMusicModel;
189 m_musicCtrl-AssociateModel( musicModel );
190 musicModel-DecRef(); // avoid memory leak !!
191 // add columns now
192 @endcode
193
194
195 @library{wxadv}
196 @category{dvc}
197 */
198 class wxDataViewModel : public wxObjectRefData
199 {
200 public:
201 /**
202 Constructor.
203 */
204 wxDataViewModel();
205
206 /**
207 Destructor. This should not be called directly. Use DecRef() instead.
208 */
209 virtual ~wxDataViewModel();
210
211 /**
212 Adds a wxDataViewModelNotifier to the model.
213 */
214 void AddNotifier(wxDataViewModelNotifier* notifier);
215
216 /**
217 Called to inform the model that all data has been cleared.
218 The control will reread the data from the model again.
219 */
220 virtual bool Cleared();
221
222 /**
223 The compare function to be used by control. The default compare function
224 sorts by container and other items separately and in ascending order.
225 Override this for a different sorting behaviour.
226
227 @see HasDefaultCompare().
228 */
229 virtual int Compare(const wxDataViewItem& item1,
230 const wxDataViewItem& item2,
231 unsigned int column,
232 bool ascending);
233
234 /**
235 Oberride this to indicate that the item has special font attributes.
236 This only affects the wxDataViewTextRendererText renderer.
237
238 @see wxDataViewItemAttr.
239 */
240 virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
241 wxDataViewItemAttr& attr);
242
243 /**
244 Override this so the control can query the child items of an item.
245 Returns the number of items.
246 */
247 virtual unsigned int GetChildren(const wxDataViewItem& item,
248 wxDataViewItemArray& children) const = 0;
249
250 /**
251 Override this to indicate the number of columns in the model.
252 */
253 virtual unsigned int GetColumnCount() const = 0;
254
255 /**
256 Override this to indicate what type of data is stored in the
257 column specified by @a col.
258
259 This should return a string indicating the type of data as reported by wxVariant.
260 */
261 virtual wxString GetColumnType(unsigned int col) const = 0;
262
263 /**
264 Override this to indicate which wxDataViewItem representing the parent
265 of @a item or an invalid wxDataViewItem if the the root item is
266 the parent item.
267 */
268 virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0;
269
270 /**
271 Override this to indicate the value of @a item.
272 A wxVariant is used to store the data.
273 */
274 virtual void GetValue(wxVariant& variant, const wxDataViewItem& item,
275 unsigned int col) const = 0;
276
277 /**
278 Override this method to indicate if a container item merely acts as a
279 headline (or for categorisation) or if it also acts a normal item with
280 entries for futher columns. By default returns @false.
281 */
282 virtual bool HasContainerColumns(const wxDataViewItem& item) const;
283
284 /**
285 Override this to indicate that the model provides a default compare
286 function that the control should use if no wxDataViewColumn has been
287 chosen for sorting. Usually, the user clicks on a column header for
288 sorting, the data will be sorted alphanumerically.
289
290 If any other order (e.g. by index or order of appearance) is required,
291 then this should be used.
292 See wxDataViewIndexListModel for a model which makes use of this.
293 */
294 virtual bool HasDefaultCompare() const;
295
296 /**
297 Override this to indicate of @a item is a container, i.e. if
298 it can have child items.
299 */
300 virtual bool IsContainer(const wxDataViewItem& item) const = 0;
301
302 /**
303 Call this to inform the model that an item has been added to the data.
304 */
305 virtual bool ItemAdded(const wxDataViewItem& parent,
306 const wxDataViewItem& item);
307
308 /**
309 Call this to inform the model that an item has changed.
310
311 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
312 event (in which the column fields will not be set) to the user.
313 */
314 virtual bool ItemChanged(const wxDataViewItem& item);
315
316 /**
317 Call this to inform the model that an item has been deleted from the data.
318 */
319 virtual bool ItemDeleted(const wxDataViewItem& parent,
320 const wxDataViewItem& item);
321
322 /**
323 Call this to inform the model that several items have been added to the data.
324 */
325 virtual bool ItemsAdded(const wxDataViewItem& parent,
326 const wxDataViewItemArray& items);
327
328 /**
329 Call this to inform the model that several items have changed.
330
331 This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
332 events (in which the column fields will not be set) to the user.
333 */
334 virtual bool ItemsChanged(const wxDataViewItemArray& items);
335
336 /**
337 Call this to inform the model that several items have been deleted.
338 */
339 virtual bool ItemsDeleted(const wxDataViewItem& parent,
340 const wxDataViewItemArray& items);
341
342 /**
343 Remove the @a notifier from the list of notifiers.
344 */
345 void RemoveNotifier(wxDataViewModelNotifier* notifier);
346
347 /**
348 Call this to initiate a resort after the sort function has been changed.
349 */
350 virtual void Resort();
351
352 /**
353 This gets called in order to set a value in the data model.
354 The most common scenario is that the wxDataViewCtrl calls this method
355 after the user changed some data in the view.
356
357 Afterwards ValueChanged() has to be called!
358 */
359 virtual bool SetValue(const wxVariant& variant, const wxDataViewItem& item,
360 unsigned int col) = 0;
361
362 /**
363 Call this to inform this model that a value in the model has been changed.
364 This is also called from wxDataViewCtrl's internal editing code, e.g. when
365 editing a text field in the control.
366
367 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
368 event to the user.
369 */
370 virtual bool ValueChanged(const wxDataViewItem& item,
371 unsigned int col);
372 };
373
374
375
376 /**
377 @class wxDataViewIndexListModel
378
379 wxDataViewIndexListModel is a specialized data model which lets you address
380 an item by its position (row) rather than its wxDataViewItem (which you can
381 obtain from this class).
382 This model also provides its own wxDataViewIndexListModel::Compare
383 method which sorts the model's data by the index.
384
385 This model is not a virtual model since the control stores each wxDataViewItem.
386 Use wxDataViewVirtualListModel if you need to display millions of items or
387 have other reason to use a virtual control.
388
389 @library{wxadv}
390 @category{dvc}
391 */
392 class wxDataViewIndexListModel : public wxDataViewModel
393 {
394 public:
395 /**
396 Constructor.
397 */
398 wxDataViewIndexListModel(unsigned int initial_size = 0);
399
400 /**
401 Destructor.
402 */
403 virtual ~wxDataViewIndexListModel();
404
405 /**
406 Compare method that sorts the items by their index.
407 */
408 int Compare(const wxDataViewItem& item1,
409 const wxDataViewItem& item2,
410 unsigned int column, bool ascending);
411
412 /**
413 Oberride this to indicate that the row has special font attributes.
414 This only affects the wxDataViewTextRendererText() renderer.
415
416 @see wxDataViewItemAttr.
417 */
418 virtual bool GetAttr(unsigned int row, unsigned int col,
419 wxDataViewItemAttr& attr);
420
421 /**
422 Returns the wxDataViewItem at the given @e row.
423 */
424 wxDataViewItem GetItem(unsigned int row) const;
425
426 /**
427 Returns the position of given @e item.
428 */
429 unsigned int GetRow(const wxDataViewItem& item) const;
430
431 /**
432 Override this to allow getting values from the model.
433 */
434 virtual void GetValue(wxVariant& variant, unsigned int row,
435 unsigned int col) const = 0;
436
437 /**
438 Call this after if the data has to be read again from the model.
439 This is useful after major changes when calling the methods below
440 (possibly thousands of times) doesn't make sense.
441 */
442 void Reset(unsigned int new_size);
443
444 /**
445 Call this after a row has been appended to the model.
446 */
447 void RowAppended();
448
449 /**
450 Call this after a row has been changed.
451 */
452 void RowChanged(unsigned int row);
453
454 /**
455 Call this after a row has been deleted.
456 */
457 void RowDeleted(unsigned int row);
458
459 /**
460 Call this after a row has been inserted at the given position.
461 */
462 void RowInserted(unsigned int before);
463
464 /**
465 Call this after a row has been prepended to the model.
466 */
467 void RowPrepended();
468
469 /**
470 Call this after a value has been changed.
471 */
472 void RowValueChanged(unsigned int row, unsigned int col);
473
474 /**
475 Call this after rows have been deleted.
476 The array will internally get copied and sorted in descending order so
477 that the rows with the highest position will be deleted first.
478 */
479 void RowsDeleted(const wxArrayInt& rows);
480
481 /**
482 Called in order to set a value in the model.
483 */
484 virtual bool SetValue(const wxVariant& variant, unsigned int row,
485 unsigned int col) = 0;
486 };
487
488
489
490 /**
491 @class wxDataViewVirtualListModel
492
493 wxDataViewVirtualListModel is a specialized data model which lets you address
494 an item by its position (row) rather than its wxDataViewItem and as such offers
495 the exact same interface as wxDataViewIndexListModel.
496 The important difference is that under platforms other than OS X, using this
497 model will result in a truly virtual control able to handle millions of items
498 as the control doesn't store any item (a feature not supported by the
499 Carbon API under OS X).
500
501 @see wxDataViewIndexListModel for the API.
502
503 @library{wxadv}
504 @category{dvc}
505 */
506 class wxDataViewVirtualListModel : public wxDataViewModel
507 {
508 public:
509 /**
510 Constructor.
511 */
512 wxDataViewVirtualListModel(unsigned int initial_size = 0);
513 };
514
515
516
517 /**
518 @class wxDataViewItemAttr
519
520 This class is used to indicate to a wxDataViewCtrl that a certain item
521 (see wxDataViewItem) has extra font attributes for its renderer.
522 For this, it is required to override wxDataViewModel::GetAttr.
523
524 Attributes are currently only supported by wxDataViewTextRendererText.
525
526 @library{wxadv}
527 @category{dvc}
528 */
529 class wxDataViewItemAttr
530 {
531 public:
532 /**
533 Constructor.
534 */
535 wxDataViewItemAttr();
536
537 /**
538 Call this to indicate that the item shall be displayed in bold text.
539 */
540 void SetBold(bool set);
541
542 /**
543 Call this to indicate that the item shall be displayed with that colour.
544 */
545 void SetColour(const wxColour& colour);
546
547 /**
548 Call this to indicate that the item shall be displayed in italic text.
549 */
550 void SetItalic(bool set);
551 };
552
553
554
555 /**
556 @class wxDataViewItem
557
558 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
559 in a persistent way, i.e. indepent of the position of the item in the control
560 or changes to its contents.
561
562 It must hold a unique ID of type @e void* in its only field and can be converted
563 to and from it.
564
565 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
566 return @false which used in many places in the API of wxDataViewCtrl to
567 indicate that e.g. no item was found. An ID of @NULL is also used to indicate
568 the invisible root. Examples for this are wxDataViewModel::GetParent and
569 wxDataViewModel::GetChildren.
570
571 @library{wxadv}
572 @category{dvc}
573 */
574 class wxDataViewItem
575 {
576 public:
577 //@{
578 /**
579 Constructor.
580 */
581 wxDataViewItem(void* id = NULL);
582 wxDataViewItem(const wxDataViewItem& item);
583 //@}
584
585 /**
586 Returns the ID.
587 */
588 void* GetID() const;
589
590 /**
591 Returns @true if the ID is not @NULL.
592 */
593 bool IsOk() const;
594 };
595
596
597
598 /**
599 @class wxDataViewCtrl
600
601 wxDataViewCtrl is a control to display data either in a tree like fashion or
602 in a tabular form or both.
603 If you only need to display a simple tree structure with an API more like the
604 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
605
606 A wxDataViewItem is used to represent a (visible) item in the control.
607
608 Unlike wxListCtrl wxDataViewCtrl doesn't get its data from the user through
609 virtual functions or by setting it directly. Instead you need to write your own
610 wxDataViewModel and associate it with this control.
611 Then you need to add a number of wxDataViewColumn to this control to define
612 what each column shall display. Each wxDataViewColumn in turn owns 1 instance
613 of a wxDataViewRenderer to render its cells.
614
615 A number of standard renderers for rendering text, dates, images, toggle,
616 a progress bar etc. are provided. Additionally, the user can write custom
617 renderes deriving from wxDataViewCustomRenderer for displaying anything.
618
619 All data transfer from the control to the model and the user code is done
620 through wxVariant which can be extended to support more data formats as necessary.
621 Accordingly, all type information uses the strings returned from wxVariant::GetType.
622
623 @beginStyleTable
624 @style{wxDV_SINGLE}
625 Single selection mode. This is the default.
626 @style{wxDV_MULTIPLE}
627 Multiple selection mode.
628 @style{wxDV_ROW_LINES}
629 Use alternating colours for rows if supported by platform and theme.
630 @style{wxDV_HORIZ_RULES}
631 Display fine rules between row if supported.
632 @style{wxDV_VERT_RULES}
633 Display fine rules between columns is supported.
634 @style{wxDV_VARIABLE_LINE_HEIGHT}
635 Allow variable line heights.
636 This can be inefficient when displaying large number of items.
637 @endStyleTable
638
639 @beginEventTable{wxDataViewEvent}
640 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
641 Process a wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
642 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
643 Process a wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
644 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
645 Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
646 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
647 Process a wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
648 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
649 Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
650 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
651 Process a wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
652 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
653 Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
654 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
655 Process a wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
656 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
657 Process a wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
658 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
659 Process a wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
660 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
661 Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
662 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
663 Process a wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
664 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
665 Process a wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
666 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
667 Process a wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
668 @endEventTable
669
670 @library{wxadv}
671 @category{ctrl,dvc}
672 @appearance{dataviewctrl.png}
673 */
674 class wxDataViewCtrl : public wxControl
675 {
676 public:
677 /**
678 Default Constructor.
679 */
680 wxDataViewCtrl();
681
682 /**
683 Constructor. Calls Create().
684 */
685 wxDataViewCtrl(wxWindow* parent, wxWindowID id,
686 const wxPoint& pos = wxDefaultPosition,
687 const wxSize& size = wxDefaultSize,
688 long style = 0,
689 const wxValidator& validator = wxDefaultValidator);
690
691 /**
692 Destructor.
693 */
694 virtual ~wxDataViewCtrl();
695
696 /**
697 Appends a wxDataViewColumn to the control. Returns @true on success.
698
699 Note that there is a number of short cut methods which implicitly create
700 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
701 */
702 virtual bool AppendColumn(wxDataViewColumn* col);
703
704 /**
705 Prepends a wxDataViewColumn to the control. Returns @true on success.
706
707 Note that there is a number of short cut methods which implicitly create
708 a wxDataViewColumn and a wxDataViewRenderer for it.
709 */
710 virtual bool PrependColumn(wxDataViewColumn* col);
711
712 /**
713 Inserts a wxDataViewColumn to the control. Returns @true on success.
714 */
715 virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col);
716
717 //@{
718 /**
719 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
720 created in the function or @NULL on failure.
721 */
722 wxDataViewColumn* AppendBitmapColumn(const wxString& label,
723 unsigned int model_column,
724 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
725 int width = -1,
726 wxAlignment align = wxALIGN_CENTER,
727 int flags = wxDATAVIEW_COL_RESIZABLE);
728 wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label,
729 unsigned int model_column,
730 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
731 int width = -1,
732 wxAlignment align = wxALIGN_CENTER,
733 int flags = wxDATAVIEW_COL_RESIZABLE);
734 //@}
735
736 //@{
737 /**
738 Appends a column for rendering a date. Returns the wxDataViewColumn
739 created in the function or @NULL on failure.
740
741 @note The @a align parameter is applied to both the column header and
742 the column renderer.
743 */
744 wxDataViewColumn* AppendDateColumn(const wxString& label,
745 unsigned int model_column,
746 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
747 int width = -1,
748 wxAlignment align = wxALIGN_CENTER,
749 int flags = wxDATAVIEW_COL_RESIZABLE);
750 wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
751 unsigned int model_column,
752 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
753 int width = -1,
754 wxAlignment align = wxALIGN_CENTER,
755 int flags = wxDATAVIEW_COL_RESIZABLE);
756 //@}
757
758 //@{
759 /**
760 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
761 created in the function or @NULL on failure.
762 This method uses the wxDataViewIconTextRenderer class.
763
764 @note The @a align parameter is applied to both the column header and
765 the column renderer.
766 */
767 wxDataViewColumn* AppendIconTextColumn(const wxString& label,
768 unsigned int model_column,
769 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
770 int width = -1,
771 wxAlignment align = wxALIGN_LEFT,
772 int flags = wxDATAVIEW_COL_RESIZABLE);
773 wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
774 unsigned int model_column,
775 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
776 int width = -1,
777 wxAlignment align = wxALIGN_LEFT,
778 int flags = wxDATAVIEW_COL_RESIZABLE);
779 //@}
780
781 //@{
782 /**
783 Appends a column for rendering a progress indicator. Returns the
784 wxDataViewColumn created in the function or @NULL on failure.
785
786 @note The @a align parameter is applied to both the column header and
787 the column renderer.
788 */
789 wxDataViewColumn* AppendProgressColumn(const wxString& label,
790 unsigned int model_column,
791 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
792 int width = 80,
793 wxAlignment align = wxALIGN_CENTER,
794 int flags = wxDATAVIEW_COL_RESIZABLE);
795 wxDataViewColumn* AppendProgressColumn(const wxBitmap& label,
796 unsigned int model_column,
797 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
798 int width = 80,
799 wxAlignment align = wxALIGN_CENTER,
800 int flags = wxDATAVIEW_COL_RESIZABLE);
801 //@}
802
803 //@{
804 /**
805 Appends a column for rendering text. Returns the wxDataViewColumn
806 created in the function or @NULL on failure.
807
808 @note The @a align parameter is applied to both the column header and
809 the column renderer.
810 */
811 wxDataViewColumn* AppendTextColumn(const wxString& label,
812 unsigned int model_column,
813 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
814 int width = -1,
815 wxAlignment align = wxALIGN_LEFT,
816 int flags = wxDATAVIEW_COL_RESIZABLE);
817 wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
818 unsigned int model_column,
819 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
820 int width = -1,
821 wxAlignment align = wxALIGN_LEFT,
822 int flags = wxDATAVIEW_COL_RESIZABLE);
823 //@}
824
825 //@{
826 /**
827 Appends a column for rendering a toggle. Returns the wxDataViewColumn
828 created in the function or @NULL on failure.
829
830 @note The @a align parameter is applied to both the column header and
831 the column renderer.
832 */
833 wxDataViewColumn* AppendToggleColumn(const wxString& label,
834 unsigned int model_column,
835 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
836 int width = 30,
837 wxAlignment align = wxALIGN_CENTER,
838 int flags = wxDATAVIEW_COL_RESIZABLE);
839 wxDataViewColumn* AppendToggleColumn(const wxBitmap& label,
840 unsigned int model_column,
841 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
842 int width = 30,
843 wxAlignment align = wxALIGN_CENTER,
844 int flags = wxDATAVIEW_COL_RESIZABLE);
845 //@}
846
847 /**
848 Associates a wxDataViewModel with the control.
849 This increases the reference count of the model by 1.
850 */
851 virtual bool AssociateModel(wxDataViewModel* model);
852
853 /**
854 Removes all columns.
855 */
856 virtual bool ClearColumns();
857
858 /**
859 Unselects all rows.
860 */
861 void ClearSelection();
862
863 /**
864 Collapses the item.
865 */
866 virtual void Collapse(const wxDataViewItem& item);
867
868 /**
869 Create the control. Useful for two step creation.
870 */
871 bool Create(wxWindow* parent, wxWindowID id,
872 const wxPoint& pos = wxDefaultPosition,
873 const wxSize& size = wxDefaultSize,
874 long style = 0,
875 const wxValidator& validator = wxDefaultValidator);
876
877 /**
878 Deletes given column.
879 */
880 virtual bool DeleteColumn(wxDataViewColumn* column);
881
882 /**
883 Call this to ensure that the given item is visible.
884 */
885 virtual void EnsureVisible(const wxDataViewItem& item,
886 const wxDataViewColumn* column = NULL);
887
888 /**
889 Expands the item.
890 */
891 virtual void Expand(const wxDataViewItem& item);
892
893 /**
894 Returns pointer to the column. @a pos refers to the position in the
895 control which may change after reordering columns by the user.
896 */
897 virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
898
899 /**
900 Returns the number of columns.
901 */
902 virtual unsigned int GetColumnCount() const;
903
904 /**
905 Returns the position of the column or -1 if not found in the control.
906 */
907 virtual int GetColumnPosition(const wxDataViewColumn* column) const;
908
909 /**
910 Returns column containing the expanders.
911 */
912 wxDataViewColumn* GetExpanderColumn() const;
913
914 /**
915 Returns indentation.
916 */
917 int GetIndent() const;
918
919 /**
920 Returns item rect.
921 */
922 virtual wxRect GetItemRect(const wxDataViewItem& item,
923 const wxDataViewColumn* col = NULL) const;
924
925 /**
926 Returns pointer to the data model associated with the control (if any).
927 */
928 wxDataViewModel* GetModel();
929
930 /**
931 Returns first selected item or an invalid item if none is selected.
932 */
933 virtual wxDataViewItem GetSelection() const;
934
935 /**
936 Fills @a sel with currently selected items and returns their number.
937 */
938 virtual int GetSelections(wxDataViewItemArray& sel) const;
939
940 /**
941 Returns the wxDataViewColumn currently responsible for sorting
942 or @NULL if none has been selected.
943 */
944 virtual wxDataViewColumn* GetSortingColumn() const;
945
946 /**
947 Hittest.
948 */
949 virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
950 wxDataViewColumn*& col) const;
951
952 /**
953 Return @true if the item is selected.
954 */
955 virtual bool IsSelected(const wxDataViewItem& item) const;
956
957 /**
958 Select the given item.
959 */
960 virtual void Select(const wxDataViewItem& item);
961
962 /**
963 Select all items.
964 */
965 virtual void SelectAll();
966
967 /**
968 Set which column shall contain the tree-like expanders.
969 */
970 void SetExpanderColumn(wxDataViewColumn* col);
971
972 /**
973 Sets the indendation.
974 */
975 void SetIndent(int indent);
976
977 /**
978 Sets the selection to the array of wxDataViewItems.
979 */
980 virtual void SetSelections(const wxDataViewItemArray& sel);
981
982 /**
983 Unselect the given item.
984 */
985 virtual void Unselect(const wxDataViewItem& item);
986
987 /**
988 Unselect all item.
989 This method only has effect if multiple selections are allowed.
990 */
991 virtual void UnselectAll();
992 };
993
994
995
996 /**
997 @class wxDataViewModelNotifier
998
999 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1000 its notification interface.
1001 See the documentation of that class for further information.
1002
1003 @library{wxadv}
1004 @category{dvc}
1005 */
1006 class wxDataViewModelNotifier
1007 {
1008 public:
1009 /**
1010 Constructor.
1011 */
1012 wxDataViewModelNotifier();
1013
1014 /**
1015 Destructor.
1016 */
1017 virtual ~wxDataViewModelNotifier();
1018
1019 /**
1020 Called by owning model.
1021 */
1022 virtual bool Cleared() = 0;
1023
1024 /**
1025 Get owning wxDataViewModel.
1026 */
1027 wxDataViewModel* GetOwner() const;
1028
1029 /**
1030 Called by owning model.
1031 */
1032 virtual bool ItemAdded(const wxDataViewItem& parent,
1033 const wxDataViewItem& item) = 0;
1034
1035 /**
1036 Called by owning model.
1037 */
1038 virtual bool ItemChanged(const wxDataViewItem& item) = 0;
1039
1040 /**
1041 Called by owning model.
1042 */
1043 virtual bool ItemDeleted(const wxDataViewItem& parent,
1044 const wxDataViewItem& item) = 0;
1045
1046 /**
1047 Called by owning model.
1048 */
1049 virtual bool ItemsAdded(const wxDataViewItem& parent,
1050 const wxDataViewItemArray& items);
1051
1052 /**
1053 Called by owning model.
1054 */
1055 virtual bool ItemsChanged(const wxDataViewItemArray& items);
1056
1057 /**
1058 Called by owning model.
1059 */
1060 virtual bool ItemsDeleted(const wxDataViewItem& parent,
1061 const wxDataViewItemArray& items);
1062
1063 /**
1064 Called by owning model.
1065 */
1066 virtual void Resort() = 0;
1067
1068 /**
1069 Set owner of this notifier. Used internally.
1070 */
1071 void SetOwner(wxDataViewModel* owner);
1072
1073 /**
1074 Called by owning model.
1075 */
1076 virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
1077 };
1078
1079
1080 /**
1081 The mode of a data-view cell; see wxDataViewRenderer for more info.
1082 */
1083 enum wxDataViewCellMode
1084 {
1085 wxDATAVIEW_CELL_INERT,
1086
1087 /**
1088 Indicates that the user can double click the cell and something will
1089 happen (e.g. a window for editing a date will pop up).
1090 */
1091 wxDATAVIEW_CELL_ACTIVATABLE,
1092
1093 /**
1094 Indicates that the user can edit the data in-place, i.e. an control
1095 will show up after a slow click on the cell. This behaviour is best
1096 known from changing the filename in most file managers etc.
1097 */
1098 wxDATAVIEW_CELL_EDITABLE
1099 };
1100
1101 /**
1102 The values of this enum controls how a wxDataViewRenderer should display
1103 its contents in a cell.
1104 */
1105 enum wxDataViewCellRenderState
1106 {
1107 wxDATAVIEW_CELL_SELECTED = 1,
1108 wxDATAVIEW_CELL_PRELIT = 2,
1109 wxDATAVIEW_CELL_INSENSITIVE = 4,
1110 wxDATAVIEW_CELL_FOCUSED = 8
1111 };
1112
1113 /**
1114 @class wxDataViewRenderer
1115
1116 This class is used by wxDataViewCtrl to render the individual cells.
1117 One instance of a renderer class is owned by a wxDataViewColumn.
1118 There is a number of ready-to-use renderers provided:
1119 - wxDataViewTextRenderer,
1120 - wxDataViewTextRendererAttr,
1121 - wxDataViewIconTextRenderer,
1122 - wxDataViewToggleRenderer,
1123 - wxDataViewProgressRenderer,
1124 - wxDataViewBitmapRenderer,
1125 - wxDataViewDateRenderer,
1126 - wxDataViewSpinRenderer.
1127
1128 Additionally, the user can write own renderers by deriving from
1129 wxDataViewCustomRenderer.
1130
1131 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1132 by the constructors respectively controls what actions the cell data allows
1133 and how the renderer should display its contents in a cell.
1134
1135 @library{wxadv}
1136 @category{dvc}
1137 */
1138 class wxDataViewRenderer : public wxObject
1139 {
1140 public:
1141 /**
1142 Constructor.
1143 */
1144 wxDataViewRenderer(const wxString& varianttype,
1145 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1146 int align = wxDVR_DEFAULT_ALIGNMENT );
1147
1148 /**
1149 Returns the alignment. See SetAlignment()
1150 */
1151 virtual int GetAlignment() const;
1152
1153 /**
1154 Returns the cell mode.
1155 */
1156 virtual wxDataViewCellMode GetMode() const;
1157
1158 /**
1159 Returns pointer to the owning wxDataViewColumn.
1160 */
1161 wxDataViewColumn* GetOwner() const;
1162
1163 /**
1164 This methods retrieves the value from the renderer in order to
1165 transfer the value back to the data model.
1166
1167 Returns @false on failure.
1168 */
1169 virtual bool GetValue(wxVariant& value) const = 0;
1170
1171 /**
1172 Returns a string with the type of the wxVariant supported by this renderer.
1173 */
1174 wxString GetVariantType() const;
1175
1176 /**
1177 Sets the alignment of the renderer's content.
1178 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1179 should have the same alignment as the column header.
1180
1181 The method is not implemented under OS X and the renderer always aligns
1182 its contents as the column header on that platform. The other platforms
1183 support both vertical and horizontal alignment.
1184 */
1185 virtual void SetAlignment( int align );
1186 /**
1187 Sets the owning wxDataViewColumn.
1188 This is usually called from within wxDataViewColumn.
1189 */
1190 void SetOwner(wxDataViewColumn* owner);
1191
1192 /**
1193 Set the value of the renderer (and thus its cell) to @a value.
1194 The internal code will then render this cell with this data.
1195 */
1196 virtual bool SetValue(const wxVariant& value) = 0;
1197
1198 /**
1199 Before data is committed to the data model, it is passed to this
1200 method where it can be checked for validity. This can also be
1201 used for checking a valid range or limiting the user input in
1202 a certain aspect (e.g. max number of characters or only alphanumeric
1203 input, ASCII only etc.). Return @false if the value is not valid.
1204
1205 Please note that due to implementation limitations, this validation
1206 is done after the editing control already is destroyed and the
1207 editing process finished.
1208 */
1209 virtual bool Validate(wxVariant& value);
1210 };
1211
1212
1213
1214 /**
1215 @class wxDataViewTextRenderer
1216
1217 wxDataViewTextRenderer is used for rendering text.
1218 It supports in-place editing if desired.
1219
1220 @library{wxadv}
1221 @category{dvc}
1222 */
1223 class wxDataViewTextRenderer : public wxDataViewRenderer
1224 {
1225 public:
1226 /**
1227 The ctor.
1228 */
1229 wxDataViewTextRenderer(const wxString& varianttype = "string",
1230 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1231 int align = wxDVR_DEFAULT_ALIGNMENT );
1232 };
1233
1234
1235
1236 /**
1237 @class wxDataViewIconTextRenderer
1238
1239 The wxDataViewIconTextRenderer class is used to display text with
1240 a small icon next to it as it is typically done in a file manager.
1241
1242 This classes uses the wxDataViewIconText helper class to store its data.
1243 wxDataViewIonText can be converted to and from a wxVariant using the left shift
1244 operator.
1245
1246 @library{wxadv}
1247 @category{dvc}
1248 */
1249 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1250 {
1251 public:
1252 /**
1253 The ctor.
1254 */
1255 wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1256 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1257 int align = wxDVR_DEFAULT_ALIGNMENT );
1258 };
1259
1260
1261
1262 /**
1263 @class wxDataViewProgressRenderer
1264
1265 This class is used by wxDataViewCtrl to render progress bars.
1266
1267 @library{wxadv}
1268 @category{dvc}
1269 */
1270 class wxDataViewProgressRenderer : public wxDataViewRenderer
1271 {
1272 public:
1273 /**
1274 The ctor.
1275 */
1276 wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1277 const wxString& varianttype = "long",
1278 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1279 int align = wxDVR_DEFAULT_ALIGNMENT );
1280 };
1281
1282
1283
1284 /**
1285 @class wxDataViewSpinRenderer
1286
1287 This is a specialized renderer for rendering integer values.
1288 It supports modifying the values in-place by using a wxSpinCtrl.
1289 The renderer only support variants of type @e long.
1290
1291 @library{wxadv}
1292 @category{dvc}
1293 */
1294 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1295 {
1296 public:
1297 /**
1298 Constructor.
1299 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1300 */
1301 wxDataViewSpinRenderer(int min, int max,
1302 wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1303 int align = wxDVR_DEFAULT_ALIGNMENT);
1304 };
1305
1306
1307
1308 /**
1309 @class wxDataViewToggleRenderer
1310
1311 This class is used by wxDataViewCtrl to render toggle controls.
1312
1313 @library{wxadv}
1314 @category{dvc}
1315 */
1316 class wxDataViewToggleRenderer : public wxDataViewRenderer
1317 {
1318 public:
1319 /**
1320 The ctor.
1321 */
1322 wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1323 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1324 int align = wxDVR_DEFAULT_ALIGNMENT);
1325 };
1326
1327
1328
1329 /**
1330 @class wxDataViewDateRenderer
1331
1332 This class is used by wxDataViewCtrl to render calendar controls.
1333
1334 @library{wxadv}
1335 @category{dvc}
1336 */
1337 class wxDataViewDateRenderer : public wxDataViewRenderer
1338 {
1339 public:
1340 /**
1341 The ctor.
1342 */
1343 wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1344 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1345 int align = wxDVR_DEFAULT_ALIGNMENT);
1346 };
1347
1348
1349
1350 /**
1351 @class wxDataViewTextRendererAttr
1352
1353 The same as wxDataViewTextRenderer but with support for font attributes.
1354 Font attributes are currently only supported under GTK+ and MSW.
1355
1356 @see wxDataViewModel::GetAttr and wxDataViewItemAttr.
1357
1358 @library{wxadv}
1359 @category{dvc}
1360 */
1361 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1362 {
1363 public:
1364 /**
1365 The ctor.
1366 */
1367 wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1368 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1369 int align = wxDVR_DEFAULT_ALIGNMENT);
1370 };
1371
1372
1373
1374 /**
1375 @class wxDataViewCustomRenderer
1376
1377 You need to derive a new class from wxDataViewCustomRenderer in
1378 order to write a new renderer.
1379
1380 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1381 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1382
1383 If you want your renderer to support in-place editing then you also need to override
1384 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1385 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1386
1387 Note that a special event handler will be pushed onto that editor control
1388 which handles @e \<ENTER\> and focus out events in order to end the editing.
1389
1390 @library{wxadv}
1391 @category{dvc}
1392 */
1393 class wxDataViewCustomRenderer : public wxDataViewRenderer
1394 {
1395 public:
1396 /**
1397 Constructor.
1398 */
1399 wxDataViewCustomRenderer(const wxString& varianttype = "string",
1400 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1401 int align = -1, bool no_init = false);
1402
1403 /**
1404 Destructor.
1405 */
1406 virtual ~wxDataViewCustomRenderer();
1407
1408 /**
1409 Override this to react to double clicks or ENTER.
1410 This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1411 */
1412 virtual bool Activate( wxRect cell,
1413 wxDataViewModel* model,
1414 const wxDataViewItem & item,
1415 unsigned int col );
1416
1417 /**
1418 Override this to create the actual editor control once editing
1419 is about to start.
1420
1421 @a parent is the parent of the editor control, @a labelRect indicates the
1422 position and size of the editor control and @a value is its initial value:
1423 @code
1424 {
1425 long l = value;
1426 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1427 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1428 }
1429 @endcode
1430 */
1431 virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1432 wxRect labelRect,
1433 const wxVariant& value);
1434
1435 /**
1436 Create DC on request. Internal.
1437 */
1438 virtual wxDC* GetDC();
1439
1440 /**
1441 Return size required to show content.
1442 */
1443 virtual wxSize GetSize() const = 0;
1444
1445 /**
1446 Overrride this so that the renderer can get the value from the editor
1447 control (pointed to by @a editor):
1448 @code
1449 {
1450 wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1451 long l = sc->GetValue();
1452 value = l;
1453 return true;
1454 }
1455 @endcode
1456 */
1457 virtual bool GetValueFromEditorCtrl(wxControl* editor,
1458 wxVariant& value);
1459
1460 /**
1461 Override this and make it return @true in order to
1462 indicate that this renderer supports in-place editing.
1463 */
1464 virtual bool HasEditorCtrl();
1465
1466 /**
1467 Overrride this to react to a left click.
1468 This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1469 */
1470 virtual bool LeftClick( wxPoint cursor,
1471 wxRect cell,
1472 wxDataViewModel * model,
1473 const wxDataViewItem & item,
1474 unsigned int col );
1475
1476 /**
1477 Override this to render the cell.
1478 Before this is called, wxDataViewRenderer::SetValue was called
1479 so that this instance knows what to render.
1480 */
1481 virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1482
1483 /**
1484 This method should be called from within Render() whenever you need to
1485 render simple text.
1486 This will ensure that the correct colour, font and vertical alignment will
1487 be chosen so the text will look the same as text drawn by native renderers.
1488 */
1489 void RenderText(const wxString& text, int xoffset, wxRect cell,
1490 wxDC* dc, int state);
1491
1492 /**
1493 Overrride this to start a drag operation. Not yet supported.
1494 */
1495 virtual bool StartDrag(wxPoint cursor, wxRect cell,
1496 wxDataViewModel* model,
1497 const wxDataViewItem & item,
1498 unsigned int col);
1499 };
1500
1501
1502
1503 /**
1504 @class wxDataViewBitmapRenderer
1505
1506 This class is used by wxDataViewCtrl to render bitmap controls.
1507
1508 @library{wxadv}
1509 @category{dvc}
1510 */
1511 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1512 {
1513 public:
1514 /**
1515 The ctor.
1516 */
1517 wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1518 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1519 int align = wxDVR_DEFAULT_ALIGNMENT,
1520 };
1521
1522
1523 /**
1524 The flags used by wxDataViewColumn.
1525 */
1526 enum wxDataViewColumnFlags
1527 {
1528 wxDATAVIEW_COL_RESIZABLE = 1,
1529 wxDATAVIEW_COL_SORTABLE = 2,
1530 wxDATAVIEW_COL_REORDERABLE = 4,
1531 wxDATAVIEW_COL_HIDDEN = 8
1532 };
1533
1534 /**
1535 @class wxDataViewColumn
1536
1537 This class represents a column in a wxDataViewCtrl.
1538 One wxDataViewColumn is bound to one column in the data model, to which the
1539 wxDataViewCtrl has been associated.
1540
1541 An instance of wxDataViewRenderer is used by this class to render its data.
1542
1543 @library{wxadv}
1544 @category{dvc}
1545 */
1546 class wxDataViewColumn : public wxObject
1547 {
1548 public:
1549 //@{
1550 /**
1551 Constructors.
1552 */
1553 wxDataViewColumn(const wxString& title,
1554 wxDataViewRenderer* renderer,
1555 unsigned int model_column,
1556 int width = wxDVC_DEFAULT_WIDTH,
1557 wxAlignment align = wxALIGN_CENTRE,
1558 int flags = wxDATAVIEW_COL_RESIZABLE);
1559 wxDataViewColumn(const wxBitmap& bitmap,
1560 wxDataViewRenderer* renderer,
1561 unsigned int model_column,
1562 int width = wxDVC_DEFAULT_WIDTH,
1563 wxAlignment align = wxALIGN_CENTRE,
1564 int flags = wxDATAVIEW_COL_RESIZABLE);
1565 //@}
1566
1567 /**
1568 Destructor.
1569 */
1570 virtual ~wxDataViewColumn();
1571
1572 /**
1573 Returns the bitmap in the header of the column, if any.
1574 */
1575 const wxBitmap& GetBitmap() const;
1576
1577 /**
1578 Returns the index of the column of the model, which this
1579 wxDataViewColumn is displaying.
1580 */
1581 unsigned int GetModelColumn() const;
1582
1583 /**
1584 Returns the owning wxDataViewCtrl.
1585 */
1586 wxDataViewCtrl* GetOwner() const;
1587
1588 /**
1589 Returns the renderer of this wxDataViewColumn.
1590
1591 @see wxDataViewRenderer.
1592 */
1593 wxDataViewRenderer* GetRenderer() const;
1594
1595 /**
1596 Returns @true if the column is reorderable.
1597 */
1598 bool GetReorderable();
1599
1600 /**
1601 Returns @true if the column is sortable.
1602
1603 @see SetSortable()
1604 */
1605 bool GetSortable();
1606
1607 /**
1608 Returns the width of the column.
1609 */
1610 virtual int GetWidth() const;
1611
1612 /**
1613 Returns @true, if the sort order is ascending.
1614
1615 @see SetSortOrder()
1616 */
1617 virtual bool IsSortOrderAscending() const;
1618
1619 /**
1620 Set the alignment of the column header.
1621 */
1622 virtual void SetAlignment(wxAlignment align);
1623
1624 /**
1625 Set the bitmap of the column header.
1626 */
1627 virtual void SetBitmap(const wxBitmap& bitmap);
1628
1629 /**
1630 Indicate wether the column can be reordered by the user using the mouse.
1631 This is typically implemented visually by dragging the header button around.
1632 */
1633 virtual void SetReorderable(bool reorderable);
1634
1635 /**
1636 Indicate the sort order if the implementation of the wxDataViewCtrl supports
1637 it, most commonly by showing a little arrow.
1638 */
1639 virtual void SetSortOrder(bool ascending);
1640
1641 /**
1642 Indicate that the column is sortable.
1643 This does not show any sorting indicate yet, but it does make the column
1644 header clickable. Call SetSortOrder() afterwards to actually make the sort
1645 indicator appear.
1646
1647 If @a sortable is @false, the column header is no longer clickable and
1648 the sort indicator (little arrow) will disappear.
1649 */
1650 virtual void SetSortable(bool sortable);
1651
1652 /**
1653 Set the title of the column header to @a title.
1654 */
1655 virtual void SetTitle(const wxString& title);
1656 };
1657
1658
1659
1660 /**
1661 @class wxDataViewTreeCtrl
1662
1663 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1664 and forwards most of its API to that class.
1665 Additionally, it uses a wxImageList to store a list of icons.
1666
1667 The main purpose of this class is to look like a wxTreeCtrl to make a transition
1668 from it to the wxDataViewCtrl class simpler.
1669
1670 @library{wxadv}
1671 @category{ctrl,dvc}
1672 @appearance{dataviewtreectrl.png}
1673 */
1674 class wxDataViewTreeCtrl : public wxDataViewCtrl
1675 {
1676 public:
1677 /**
1678 Default ctor.
1679 */
1680 wxDataViewTreeCtrl();
1681
1682 /**
1683 Constructor. Calls Create().
1684 */
1685 wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1686 const wxPoint& pos = wxDefaultPosition,
1687 const wxSize& size = wxDefaultSize,
1688 long style = wxDV_NO_HEADER,
1689 const wxValidator& validator = wxDefaultValidator);
1690
1691 /**
1692 Destructor. Deletes the image list if any.
1693 */
1694 virtual ~wxDataViewTreeCtrl();
1695
1696 /**
1697 @todo docme
1698 */
1699 wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1700 const wxString& text,
1701 int icon = -1,
1702 int expanded = -1,
1703 wxClientData* data = NULL);
1704
1705 /**
1706 @todo docme
1707 */
1708 wxDataViewItem AppendItem(const wxDataViewItem& parent,
1709 const wxString& text,
1710 int icon = -1,
1711 wxClientData* data = NULL);
1712
1713 /**
1714 Creates the control and a wxDataViewTreeStore as its internal model.
1715 */
1716 bool Create(wxWindow* parent, wxWindowID id,
1717 const wxPoint& pos = wxDefaultPosition,
1718 const wxSize& size = wxDefaultSize,
1719 long style = wxDV_NO_HEADER,
1720 const wxValidator& validator = wxDefaultValidator);
1721
1722 /**
1723 Calls the identical method from wxDataViewTreeStore.
1724 */
1725 void DeleteAllItems();
1726
1727 /**
1728 Calls the identical method from wxDataViewTreeStore.
1729 */
1730 void DeleteChildren(const wxDataViewItem& item);
1731
1732 /**
1733 Calls the identical method from wxDataViewTreeStore.
1734 */
1735 void DeleteItem(const wxDataViewItem& item);
1736
1737 /**
1738 Calls the identical method from wxDataViewTreeStore.
1739 */
1740 int GetChildCount(const wxDataViewItem& parent) const;
1741
1742 /**
1743 Returns the image list.
1744 */
1745 wxImageList* GetImageList();
1746
1747 /**
1748 Calls the identical method from wxDataViewTreeStore.
1749 */
1750 wxClientData* GetItemData(const wxDataViewItem& item) const;
1751
1752 /**
1753 Calls the identical method from wxDataViewTreeStore.
1754 */
1755 const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1756
1757 /**
1758 Calls the identical method from wxDataViewTreeStore.
1759 */
1760 const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1761
1762 /**
1763 Calls the identical method from wxDataViewTreeStore.
1764 */
1765 wxString GetItemText(const wxDataViewItem& item) const;
1766
1767 /**
1768 Calls the identical method from wxDataViewTreeStore.
1769 */
1770 wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1771 unsigned int pos) const;
1772
1773 //@{
1774 /**
1775 Returns the store.
1776 */
1777 wxDataViewTreeStore* GetStore() const;
1778 const wxDataViewTreeStore* GetStore() const;
1779 //@}
1780
1781 /**
1782 Calls the same method from wxDataViewTreeStore but uses
1783 an index position in the image list instead of a wxIcon.
1784 */
1785 wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1786 const wxDataViewItem& previous,
1787 const wxString& text,
1788 int icon = -1,
1789 int expanded = -1,
1790 wxClientData* data = NULL);
1791
1792 /**
1793 Calls the same method from wxDataViewTreeStore but uses
1794 an index position in the image list instead of a wxIcon.
1795 */
1796 wxDataViewItem InsertItem(const wxDataViewItem& parent,
1797 const wxDataViewItem& previous,
1798 const wxString& text,
1799 int icon = -1,
1800 wxClientData* data = NULL);
1801
1802 /**
1803 Calls the same method from wxDataViewTreeStore but uses
1804 an index position in the image list instead of a wxIcon.
1805 */
1806 wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1807 const wxString& text,
1808 int icon = -1,
1809 int expanded = -1,
1810 wxClientData* data = NULL);
1811
1812 /**
1813 Calls the same method from wxDataViewTreeStore but uses
1814 an index position in the image list instead of a wxIcon.
1815 */
1816 wxDataViewItem PrependItem(const wxDataViewItem& parent,
1817 const wxString& text,
1818 int icon = -1,
1819 wxClientData* data = NULL);
1820
1821 /**
1822 Sets the image list.
1823 */
1824 void SetImageList(wxImageList* imagelist);
1825
1826 /**
1827 Calls the identical method from wxDataViewTreeStore.
1828 */
1829 void SetItemData(const wxDataViewItem& item, wxClientData* data);
1830
1831 /**
1832 Calls the identical method from wxDataViewTreeStore.
1833 */
1834 void SetItemExpandedIcon(const wxDataViewItem& item,
1835 const wxIcon& icon);
1836
1837 /**
1838 Calls the identical method from wxDataViewTreeStore.
1839 */
1840 void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1841
1842 /**
1843 Calls the identical method from wxDataViewTreeStore.
1844 */
1845 void SetItemText(const wxDataViewItem& item,
1846 const wxString& text);
1847 };
1848
1849
1850
1851 /**
1852 @class wxDataViewTreeStore
1853
1854 wxDataViewTreeStore is a specialised wxDataViewModel for displaying simple
1855 trees very much like wxTreeCtrl does and it offers a similar API.
1856
1857 This class actually stores the entire tree (therefore its name) and implements
1858 all virtual methods from the base class so it can be used directly without
1859 having to derive any class from it.
1860 This comes at the price of much reduced flexibility.
1861
1862 @library{wxadv}
1863 @category{dvc}
1864 */
1865 class wxDataViewTreeStore : public wxDataViewModel
1866 {
1867 public:
1868 /**
1869 Constructor. Creates the invisible root node internally.
1870 */
1871 wxDataViewTreeStore();
1872
1873 /**
1874 Destructor.
1875 */
1876 virtual ~wxDataViewTreeStore();
1877
1878 /**
1879 Append a container.
1880 */
1881 wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1882 const wxString& text,
1883 const wxIcon& icon = wxNullIcon,
1884 const wxIcon& expanded = wxNullIcon,
1885 wxClientData* data = NULL);
1886
1887 /**
1888 Append an item.
1889 */
1890 wxDataViewItem AppendItem(const wxDataViewItem& parent,
1891 const wxString& text,
1892 const wxIcon& icon = wxNullIcon,
1893 wxClientData* data = NULL);
1894
1895 /**
1896 Delete all item in the model.
1897 */
1898 void DeleteAllItems();
1899
1900 /**
1901 Delete all children of the item, but not the item itself.
1902 */
1903 void DeleteChildren(const wxDataViewItem& item);
1904
1905 /**
1906 Delete this item.
1907 */
1908 void DeleteItem(const wxDataViewItem& item);
1909
1910 /**
1911 Return the number of children of item.
1912 */
1913 int GetChildCount(const wxDataViewItem& parent) const;
1914
1915 /**
1916 Returns the client data asoociated with the item.
1917 */
1918 wxClientData* GetItemData(const wxDataViewItem& item) const;
1919
1920 /**
1921 Returns the icon to display in expanded containers.
1922 */
1923 const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1924
1925 /**
1926 Returns the icon of the item.
1927 */
1928 const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1929
1930 /**
1931 Returns the text of the item.
1932 */
1933 wxString GetItemText(const wxDataViewItem& item) const;
1934
1935 /**
1936 Returns the nth child item of item.
1937 */
1938 wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1939 unsigned int pos) const;
1940
1941 /**
1942 Inserts a container after @a previous.
1943 */
1944 wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1945 const wxDataViewItem& previous,
1946 const wxString& text,
1947 const wxIcon& icon = wxNullIcon,
1948 const wxIcon& expanded = wxNullIcon,
1949 wxClientData* data = NULL);
1950
1951 /**
1952 Inserts an item after @a previous.
1953 */
1954 wxDataViewItem InsertItem(const wxDataViewItem& parent,
1955 const wxDataViewItem& previous,
1956 const wxString& text,
1957 const wxIcon& icon = wxNullIcon,
1958 wxClientData* data = NULL);
1959
1960 /**
1961 Inserts a container before the first child item or @a parent.
1962 */
1963 wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1964 const wxString& text,
1965 const wxIcon& icon = wxNullIcon,
1966 const wxIcon& expanded = wxNullIcon,
1967 wxClientData* data = NULL);
1968
1969 /**
1970 Inserts an item before the first child item or @a parent.
1971 */
1972 wxDataViewItem PrependItem(const wxDataViewItem& parent,
1973 const wxString& text,
1974 const wxIcon& icon = wxNullIcon,
1975 wxClientData* data = NULL);
1976
1977 /**
1978 Sets the client data associated with the item.
1979 */
1980 void SetItemData(const wxDataViewItem& item, wxClientData* data);
1981
1982 /**
1983 Sets the expanded icon for the item.
1984 */
1985 void SetItemExpandedIcon(const wxDataViewItem& item,
1986 const wxIcon& icon);
1987
1988 /**
1989 Sets the icon for the item.
1990 */
1991 void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1992 };
1993