]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/grid.h
many improvements and corrections from Charles (see #10276)
[wxWidgets.git] / interface / wx / grid.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: grid.h
3 // Purpose: interface of wxGrid and related classes
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxGridCellRenderer
11
12 This class is responsible for actually drawing the cell in the grid. You
13 may pass it to the wxGridCellAttr (below) to change the format of one given
14 cell or to wxGrid::SetDefaultRenderer() to change the view of all cells.
15 This is an abstract class, and you will normally use one of the predefined
16 derived classes or derive your own class from it.
17
18 @library{wxadv}
19 @category{grid}
20
21 @see wxGridCellBoolRenderer, wxGridCellFloatRenderer,
22 wxGridCellNumberRenderer, wxGridCellStringRenderer
23 */
24 class wxGridCellRenderer
25 {
26 public:
27 /**
28 This function must be implemented in derived classes to return a copy
29 of itself.
30 */
31 virtual wxGridCellRenderer* Clone() const = 0;
32
33 /**
34 Draw the given cell on the provided DC inside the given rectangle using
35 the style specified by the attribute and the default or selected state
36 corresponding to the isSelected value.
37
38 This pure virtual function has a default implementation which will
39 prepare the DC using the given attribute: it will draw the rectangle
40 with the background colour from attr and set the text colour and font.
41 */
42 virtual void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
43 const wxRect& rect, int row, int col,
44 bool isSelected) = 0;
45
46 /**
47 Get the preferred size of the cell for its contents.
48 */
49 virtual wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
50 int row, int col) = 0;
51 };
52
53 /**
54 @class wxGridCellBoolRenderer
55
56 This class may be used to format boolean data in a cell.
57
58 @library{wxadv}
59 @category{grid}
60
61 @see wxGridCellRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer,
62 wxGridCellStringRenderer
63 */
64 class wxGridCellBoolRenderer : public wxGridCellRenderer
65 {
66 public:
67 /**
68 Default constructor.
69 */
70 wxGridCellBoolRenderer();
71 };
72
73 /**
74 @class wxGridCellFloatRenderer
75
76 This class may be used to format floating point data in a cell.
77
78 @library{wxadv}
79 @category{grid}
80
81 @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellNumberRenderer,
82 wxGridCellStringRenderer
83 */
84 class wxGridCellFloatRenderer : public wxGridCellStringRenderer
85 {
86 public:
87 /**
88 @param width
89 Minimum number of characters to be shown.
90 @param precision
91 Number of digits after the decimal dot.
92 */
93 wxGridCellFloatRenderer(int width = -1, int precision = -1);
94
95 /**
96 Returns the precision.
97 */
98 int GetPrecision() const;
99
100 /**
101 Returns the width.
102 */
103 int GetWidth() const;
104
105 /**
106 Parameters string format is "width[,precision]".
107 */
108 virtual void SetParameters(const wxString& params);
109
110 /**
111 Sets the precision.
112 */
113 void SetPrecision(int precision);
114
115 /**
116 Sets the width.
117 */
118 void SetWidth(int width);
119 };
120
121 /**
122 @class wxGridCellNumberRenderer
123
124 This class may be used to format integer data in a cell.
125
126 @library{wxadv}
127 @category{grid}
128
129 @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
130 wxGridCellStringRenderer
131 */
132 class wxGridCellNumberRenderer : public wxGridCellStringRenderer
133 {
134 public:
135 /**
136 Default constructor.
137 */
138 wxGridCellNumberRenderer();
139 };
140
141 /**
142 @class wxGridCellStringRenderer
143
144 This class may be used to format string data in a cell; it is the default
145 for string cells.
146
147 @library{wxadv}
148 @category{grid}
149
150 @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
151 wxGridCellNumberRenderer
152 */
153 class wxGridCellStringRenderer : public wxGridCellRenderer
154 {
155 public:
156 /**
157 Default constructor.
158 */
159 wxGridCellStringRenderer();
160 };
161
162
163
164 /**
165 @class wxGridCellEditor
166
167 This class is responsible for providing and manipulating the in-place edit
168 controls for the grid. Instances of wxGridCellEditor (actually, instances
169 of derived classes since it is an abstract class) can be associated with
170 the cell attributes for individual cells, rows, columns, or even for the
171 entire grid.
172
173 @library{wxadv}
174 @category{grid}
175
176 @see wxGridCellBoolEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor,
177 wxGridCellNumberEditor, wxGridCellTextEditor
178 */
179 class wxGridCellEditor
180 {
181 public:
182 /**
183 Default constructor.
184 */
185 wxGridCellEditor();
186
187 /**
188 Fetch the value from the table and prepare the edit control to begin
189 editing. Sets the focus to the edit control.
190 */
191 virtual void BeginEdit(int row, int col, wxGrid* grid) = 0;
192
193 /**
194 Create a new object which is the copy of this one.
195 */
196 virtual wxGridCellEditor* Clone() const = 0;
197
198 /**
199 Creates the actual edit control.
200 */
201 virtual void Create(wxWindow* parent, wxWindowID id,
202 wxEvtHandler* evtHandler) = 0;
203
204 /**
205 Final cleanup.
206 */
207 virtual void Destroy();
208
209 /**
210 Complete the editing of the current cell. If necessary, the control may
211 be destroyed.
212
213 @return @true if the value has changed.
214 */
215 virtual bool EndEdit(int row, int col, wxGrid* grid) = 0;
216
217 /**
218 Some types of controls on some platforms may need some help with the
219 Return key.
220 */
221 virtual void HandleReturn(wxKeyEvent& event);
222
223 /**
224 Returns @true if the edit control has been created.
225 */
226 bool IsCreated();
227
228 /**
229 Draws the part of the cell not occupied by the control: the base class
230 version just fills it with background colour from the attribute.
231 */
232 virtual void PaintBackground(const wxRect& rectCell, wxGridCellAttr* attr);
233
234 /**
235 Reset the value in the control back to its starting value.
236 */
237 virtual void Reset() = 0;
238
239 /**
240 Size and position the edit control.
241 */
242 virtual void SetSize(const wxRect& rect);
243
244 /**
245 Show or hide the edit control, use the specified attributes to set
246 colours/fonts for it.
247 */
248 virtual void Show(bool show, wxGridCellAttr* attr = NULL);
249
250 /**
251 If the editor is enabled by clicking on the cell, this method will be
252 called.
253 */
254 virtual void StartingClick();
255
256 /**
257 If the editor is enabled by pressing keys on the grid, this will be
258 called to let the editor do something about that first key if desired.
259 */
260 virtual void StartingKey(wxKeyEvent& event);
261
262 protected:
263
264 /**
265 The destructor is private because only DecRef() can delete us.
266 */
267 virtual ~wxGridCellEditor();
268 };
269
270 /**
271 @class wxGridCellBoolEditor
272
273 Grid cell editor for boolean data.
274
275 @library{wxadv}
276 @category{grid}
277
278 @see wxGridCellEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor,
279 wxGridCellNumberEditor, wxGridCellTextEditor
280 */
281 class wxGridCellBoolEditor : public wxGridCellEditor
282 {
283 public:
284 /**
285 Default constructor.
286 */
287 wxGridCellBoolEditor();
288
289 /**
290 Returns @true if the given @a value is equal to the string
291 representation of the truth value we currently use (see
292 UseStringValues()).
293 */
294 static bool IsTrueValue(const wxString& value);
295
296 /**
297 This method allows you to customize the values returned by GetValue()
298 for the cell using this editor. By default, the default values of the
299 arguments are used, i.e. @c "1" is returned if the cell is checked and
300 an empty string otherwise.
301 */
302 static void UseStringValues(const wxString& valueTrue = "1",
303 const wxString& valueFalse = wxEmptyString) const;
304 };
305
306 /**
307 @class wxGridCellChoiceEditor
308
309 Grid cell editor for string data providing the user a choice from a list of
310 strings.
311
312 @library{wxadv}
313 @category{grid}
314
315 @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellFloatEditor,
316 wxGridCellNumberEditor, wxGridCellTextEditor
317 */
318 class wxGridCellChoiceEditor : public wxGridCellEditor
319 {
320 public:
321 /**
322 @param count
323 Number of strings from which the user can choose.
324 @param choices
325 An array of strings from which the user can choose.
326 @param allowOthers
327 If allowOthers is @true, the user can type a string not in choices
328 array.
329 */
330 wxGridCellChoiceEditor(size_t count = 0,
331 const wxString choices[] = NULL,
332 bool allowOthers = false);
333 /**
334 @param choices
335 An array of strings from which the user can choose.
336 @param allowOthers
337 If allowOthers is @true, the user can type a string not in choices
338 array.
339 */
340 wxGridCellChoiceEditor(const wxArrayString& choices,
341 bool allowOthers = false);
342
343 /**
344 Parameters string format is "item1[,item2[...,itemN]]"
345 */
346 virtual void SetParameters(const wxString& params);
347 };
348
349 /**
350 @class wxGridCellTextEditor
351
352 Grid cell editor for string/text data.
353
354 @library{wxadv}
355 @category{grid}
356
357 @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
358 wxGridCellFloatEditor, wxGridCellNumberEditor
359 */
360 class wxGridCellTextEditor : public wxGridCellEditor
361 {
362 public:
363 /**
364 Default constructor.
365 */
366 wxGridCellTextEditor();
367
368 /**
369 The parameters string format is "n" where n is a number representing
370 the maximum width.
371 */
372 virtual void SetParameters(const wxString& params);
373 };
374
375 /**
376 @class wxGridCellFloatEditor
377
378 The editor for floating point numbers data.
379
380 @library{wxadv}
381 @category{grid}
382
383 @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor,
384 wxGridCellTextEditor, wxGridCellChoiceEditor
385 */
386 class wxGridCellFloatEditor : public wxGridCellTextEditor
387 {
388 public:
389 /**
390 @param width
391 Minimum number of characters to be shown.
392 @param precision
393 Number of digits after the decimal dot.
394 */
395 wxGridCellFloatEditor(int width = -1, int precision = -1);
396
397 /**
398 Parameters string format is "width,precision"
399 */
400 virtual void SetParameters(const wxString& params);
401 };
402
403 /**
404 @class wxGridCellNumberEditor
405
406 Grid cell editor for numeric integer data.
407
408 @library{wxadv}
409 @category{grid}
410
411 @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
412 wxGridCellFloatEditor, wxGridCellTextEditor
413 */
414 class wxGridCellNumberEditor : public wxGridCellTextEditor
415 {
416 public:
417 /**
418 Allows you to specify the range for acceptable data. Values equal to
419 -1 for both @a min and @a max indicate that no range checking should be
420 done.
421 */
422 wxGridCellNumberEditor(int min = -1, int max = -1);
423
424
425 /**
426 Parameters string format is "min,max".
427 */
428 virtual void SetParameters(const wxString& params);
429
430 protected:
431
432 /**
433 If the return value is @true, the editor uses a wxSpinCtrl to get user
434 input, otherwise it uses a wxTextCtrl.
435 */
436 bool HasRange() const;
437
438 /**
439 String representation of the value.
440 */
441 wxString GetString() const;
442 };
443
444
445
446 /**
447 @class wxGridCellAttr
448
449 This class can be used to alter the cells' appearance in the grid by
450 changing their attributes from the defaults. An object of this class may be
451 returned by wxGridTableBase::GetAttr().
452
453 @library{wxadv}
454 @category{grid}
455 */
456 class wxGridCellAttr
457 {
458 public:
459 /**
460 Default constructor.
461 */
462 wxGridCellAttr();
463 /**
464 Constructor specifying some of the often used attributes.
465 */
466 wxGridCellAttr(const wxColour& colText, const wxColour& colBack,
467 const wxFont& font, int hAlign, int vAlign);
468
469 /**
470 Creates a new copy of this object.
471 */
472 wxGridCellAttr* Clone() const;
473
474 /**
475 This class is reference counted: it is created with ref count of 1, so
476 calling DecRef() once will delete it. Calling IncRef() allows to lock
477 it until the matching DecRef() is called.
478 */
479 void DecRef();
480
481 /**
482 See SetAlignment() for the returned values.
483 */
484 void GetAlignment(int* hAlign, int* vAlign) const;
485
486 /**
487 Returns the background colour.
488 */
489 const wxColour& GetBackgroundColour() const;
490
491 /**
492 Returns the cell editor.
493 */
494 wxGridCellEditor* GetEditor(const wxGrid* grid, int row, int col) const;
495
496 /**
497 Returns the font.
498 */
499 const wxFont& GetFont() const;
500
501 /**
502 Returns the cell renderer.
503 */
504 wxGridCellRenderer* GetRenderer(const wxGrid* grid, int row, int col) const;
505
506 /**
507 Returns the text colour.
508 */
509 const wxColour& GetTextColour() const;
510
511 /**
512 Returns @true if this attribute has a valid alignment set.
513 */
514 bool HasAlignment() const;
515
516 /**
517 Returns @true if this attribute has a valid background colour set.
518 */
519 bool HasBackgroundColour() const;
520
521 /**
522 Returns @true if this attribute has a valid cell editor set.
523 */
524 bool HasEditor() const;
525
526 /**
527 Returns @true if this attribute has a valid font set.
528 */
529 bool HasFont() const;
530
531 /**
532 Returns @true if this attribute has a valid cell renderer set.
533 */
534 bool HasRenderer() const;
535
536 /**
537 Returns @true if this attribute has a valid text colour set.
538 */
539 bool HasTextColour() const;
540
541 /**
542 This class is reference counted: it is created with ref count of 1, so
543 calling DecRef() once will delete it. Calling IncRef() allows to lock
544 it until the matching DecRef() is called.
545 */
546 void IncRef();
547
548 /**
549 Returns @true if this cell is set as read-only.
550 */
551 bool IsReadOnly() const;
552
553 /**
554 Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT,
555 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of
556 @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
557 */
558 void SetAlignment(int hAlign, int vAlign);
559
560 /**
561 Sets the background colour.
562 */
563 void SetBackgroundColour(const wxColour& colBack);
564
565 /**
566 @todo Needs documentation.
567 */
568 void SetDefAttr(wxGridCellAttr* defAttr);
569
570 /**
571 Sets the editor to be used with the cells with this attribute.
572 */
573 void SetEditor(wxGridCellEditor* editor);
574
575 /**
576 Sets the font.
577 */
578 void SetFont(const wxFont& font);
579
580 /**
581 Sets the cell as read-only.
582 */
583 void SetReadOnly(bool isReadOnly = true);
584
585 /**
586 Sets the renderer to be used for cells with this attribute. Takes
587 ownership of the pointer.
588 */
589 void SetRenderer(wxGridCellRenderer* renderer);
590
591 /**
592 Sets the text colour.
593 */
594 void SetTextColour(const wxColour& colText);
595 };
596
597
598
599 /**
600 @class wxGridTableBase
601
602 The almost abstract base class for grid tables.
603
604 A grid table is responsible for storing the grid data and, indirectly, grid
605 cell attributes. The data can be stored in the way most convenient for the
606 application but has to be provided in string form to wxGrid. It is also
607 possible to provide cells values in other formats if appropriate, e.g. as
608 numbers.
609
610 This base class is not quite abstract as it implements a trivial strategy
611 for storing the attributes by forwarding it to wxGridCellAttrProvider and
612 also provides stubs for some other functions. However it does have a number
613 of pure virtual methods which must be implemented in the derived classes.
614
615 @see wxGridStringTable
616
617 @library{wxadv}
618 @category{grid}
619 */
620 class wxGridTableBase : public wxObject
621 {
622 public:
623 /**
624 Default constructor.
625 */
626 wxGridTableBase();
627
628 /**
629 Destructor frees the attribute provider if it was created.
630 */
631 virtual ~wxGridTableBase();
632
633 /**
634 Must be overridden to return the number of rows in the table.
635
636 For backwards compatibility reasons, this method is not const.
637 Use GetRowsCount() instead of it in const methods of derived table
638 classes.
639 */
640 virtual int GetNumberRows() = 0;
641
642 /**
643 Must be overridden to return the number of columns in the table.
644
645 For backwards compatibility reasons, this method is not const.
646 Use GetColsCount() instead of it in const methods of derived table
647 classes,
648 */
649 virtual int GetNumberCols() = 0;
650
651 /**
652 Return the number of rows in the table.
653
654 This method is not virtual and is only provided as a convenience for
655 the derived classes which can't call GetNumberRows() without a
656 @c const_cast from their const methods.
657 */
658 int GetRowsCount() const;
659
660 /**
661 Return the number of columns in the table.
662
663 This method is not virtual and is only provided as a convenience for
664 the derived classes which can't call GetNumberCols() without a
665 @c const_cast from their const methods.
666 */
667 int GetColsCount() const;
668
669
670 /**
671 @name Table Cell Accessors
672 */
673 //@{
674
675 /**
676 May be overridden to implement testing for empty cells.
677
678 This method is used by the grid to test if the given cell is not used
679 and so whether a neighbouring cell may overflow into it. By default it
680 only returns true if the value of the given cell, as returned by
681 GetValue(), is empty.
682 */
683 virtual bool IsEmptyCell(int row, int col);
684
685 /**
686 Same as IsEmptyCell() but taking wxGridCellCoords.
687
688 Notice that this method is not virtual, only IsEmptyCell() should be
689 overridden.
690 */
691 bool IsEmpty(const wxGridCellCoords& coords);
692
693 /**
694 Must be overridden to implement accessing the table values as text.
695 */
696 virtual wxString GetValue(int row, int col) = 0;
697
698 /**
699 Must be overridden to implement setting the table values as text.
700 */
701 virtual void SetValue(int row, int col, const wxString& value) = 0;
702
703 /**
704 Returns the type of the value in the given cell.
705
706 By default all cells are strings and this method returns
707 @c wxGRID_VALUE_STRING.
708 */
709 virtual wxString GetTypeName(int row, int col);
710
711 /**
712 Returns true if the value of the given cell can be accessed as if it
713 were of the specified type.
714
715 By default the cells can only be accessed as strings. Note that a cell
716 could be accessible in different ways, e.g. a numeric cell may return
717 @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
718 indicating that the value can be coerced to a string form.
719 */
720 virtual bool CanGetValueAs(int row, int col, const wxString& typeName);
721
722 /**
723 Returns true if the value of the given cell can be set as if it were of
724 the specified type.
725
726 @see CanGetValueAs()
727 */
728 virtual bool CanSetValueAs(int row, int col, const wxString& typeName);
729
730 /**
731 Returns the value of the given cell as a long.
732
733 This should only be called if CanGetValueAs() returns @true when called
734 with @c wxGRID_VALUE_NUMBER argument. Default implementation always
735 return 0.
736 */
737 virtual long GetValueAsLong(int row, int col);
738
739 /**
740 Returns the value of the given cell as a double.
741
742 This should only be called if CanGetValueAs() returns @true when called
743 with @c wxGRID_VALUE_FLOAT argument. Default implementation always
744 return 0.0.
745 */
746 virtual double GetValueAsDouble(int row, int col);
747
748 /**
749 Returns the value of the given cell as a boolean.
750
751 This should only be called if CanGetValueAs() returns @true when called
752 with @c wxGRID_VALUE_BOOL argument. Default implementation always
753 return false.
754 */
755 virtual bool GetValueAsBool(int row, int col);
756
757 /**
758 Returns the value of the given cell as a user-defined type.
759
760 This should only be called if CanGetValueAs() returns @true when called
761 with @a typeName. Default implementation always return @NULL.
762 */
763 virtual void *GetValueAsCustom(int row, int col, const wxString& typeName);
764
765 /**
766 Sets the value of the given cell as a long.
767
768 This should only be called if CanSetValueAs() returns @true when called
769 with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
770 anything.
771 */
772 virtual void SetValueAsLong(int row, int col, long value);
773
774 /**
775 Sets the value of the given cell as a double.
776
777 This should only be called if CanSetValueAs() returns @true when called
778 with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
779 anything.
780 */
781 virtual void SetValueAsDouble(int row, int col, double value);
782
783 /**
784 Sets the value of the given cell as a boolean.
785
786 This should only be called if CanSetValueAs() returns @true when called
787 with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
788 anything.
789 */
790 virtual void SetValueAsBool( int row, int col, bool value );
791
792 /**
793 Sets the value of the given cell as a user-defined type.
794
795 This should only be called if CanSetValueAs() returns @true when called
796 with @a typeName. Default implementation doesn't do anything.
797 */
798 virtual void SetValueAsCustom(int row, int col, const wxString& typeName,
799 void *value);
800
801 //@}
802
803
804 /**
805 Called by the grid when the table is associated with it.
806
807 The default implementation stores the pointer and returns it from its
808 GetView() and so only makes sense if the table cannot be associated
809 with more than one grid at a time.
810 */
811 virtual void SetView(wxGrid *grid);
812
813 /**
814 Returns the last grid passed to SetView().
815 */
816 virtual wxGrid *GetView() const;
817
818
819 /**
820 @name Table Structure Modifiers
821
822 Notice that none of these functions are pure virtual as they don't have
823 to be implemented if the table structure is never modified after
824 creation, i.e. neither rows nor columns are never added or deleted but
825 that you do need to implement them if they are called, i.e. if your
826 code either calls them directly or uses the matching wxGrid methods, as
827 by default they simply do nothing which is definitely inappropriate.
828 */
829 //@{
830
831 /**
832 Clear the table contents.
833
834 This method is used by wxGrid::ClearGrid().
835 */
836 virtual void Clear();
837
838 /**
839 Insert additional rows into the table.
840
841 @param pos
842 The position of the first new row.
843 @param numRows
844 The number of rows to insert.
845 */
846 virtual bool InsertRows(size_t pos = 0, size_t numRows = 1);
847
848 /**
849 Append additional rows at the end of the table.
850
851 This method is provided in addition to InsertRows() as some data models
852 may only support appending rows to them but not inserting them at
853 arbitrary locations. In such case you may implement this method only
854 and leave InsertRows() unimplemented.
855
856 @param numRows
857 The number of rows to add.
858 */
859 virtual bool AppendRows(size_t numRows = 1);
860
861 /**
862 Delete rows from the table.
863
864 @param pos
865 The first row to delete.
866 @param numRows
867 The number of rows to delete.
868 */
869 virtual bool DeleteRows(size_t pos = 0, size_t numRows = 1);
870
871 /**
872 Exactly the same as InsertRows() but for columns.
873 */
874 virtual bool InsertCols(size_t pos = 0, size_t numCols = 1);
875
876 /**
877 Exactly the same as AppendRows() but for columns.
878 */
879 virtual bool AppendCols(size_t numCols = 1);
880
881 /**
882 Exactly the same as DeleteRows() but for columns.
883 */
884 virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1);
885
886 //@}
887
888 /**
889 @name Table Row and Column Labels
890
891 By default the numbers are used for labeling rows and Latin letters for
892 labeling columns. If the table has more than 26 columns, the pairs of
893 letters are used starting from the 27-th one and so on, i.e. the
894 sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
895 AAA, ...
896 */
897 //@{
898
899 /**
900 Return the label of the specified row.
901 */
902 virtual wxString GetRowLabelValue(int row);
903
904 /**
905 Return the label of the specified column.
906 */
907 virtual wxString GetColLabelValue(int col);
908
909 /**
910 Set the given label for the specified row.
911
912 The default version does nothing, i.e. the label is not stored. You
913 must override this method in your derived class if you wish
914 wxGrid::SetRowLabelValue() to work.
915 */
916 virtual void SetRowLabelValue(int row, const wxString& label);
917
918 /**
919 Exactly the same as SetRowLabelValue() but for columns.
920 */
921 virtual void SetColLabelValue(int col, const wxString& label);
922
923 //@}
924
925
926 /**
927 @name Attributes Management
928
929 By default the attributes management is delegated to
930 wxGridCellAttrProvider class. You may override the methods in this
931 section to handle the attributes directly if, for example, they can be
932 computed from the cell values.
933 */
934 //@{
935
936 /**
937 Associate this attributes provider with the table.
938
939 The table takes ownership of @a attrProvider pointer and will delete it
940 when it doesn't need it any more. The pointer can be @NULL, however
941 this won't disable attributes management in the table but will just
942 result in a default attributes being recreated the next time any of the
943 other functions in this section is called. To completely disable the
944 attributes support, should this be needed, you need to override
945 CanHaveAttributes() to return @false.
946 */
947 void SetAttrProvider(wxGridCellAttrProvider *attrProvider);
948
949 /**
950 Returns the attribute provider currently being used.
951
952 This function may return @NULL if the attribute provider hasn't been
953 neither associated with this table by SetAttrProvider() nor created on
954 demand by any other methods.
955 */
956 wxGridCellAttrProvider *GetAttrProvider() const;
957
958 /**
959 Return the attribute for the given cell.
960
961 By default this function is simply forwarded to
962 wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
963 attributes directly in the table.
964 */
965 virtual wxGridCellAttr *GetAttr(int row, int col,
966 wxGridCellAttr::wxAttrKind kind);
967
968 /**
969 Set attribute of the specified cell.
970
971 By default this function is simply forwarded to
972 wxGridCellAttrProvider::SetAttr().
973
974 The table takes ownership of @a attr, i.e. will call DecRef() on it.
975 */
976 virtual void SetAttr(wxGridCellAttr* attr, int row, int col);
977
978 /**
979 Set attribute of the specified row.
980
981 By default this function is simply forwarded to
982 wxGridCellAttrProvider::SetRowAttr().
983
984 The table takes ownership of @a attr, i.e. will call DecRef() on it.
985 */
986 virtual void SetRowAttr(wxGridCellAttr *attr, int row);
987
988 /**
989 Set attribute of the specified column.
990
991 By default this function is simply forwarded to
992 wxGridCellAttrProvider::SetColAttr().
993
994 The table takes ownership of @a attr, i.e. will call DecRef() on it.
995 */
996 virtual void SetColAttr(wxGridCellAttr *attr, int col);
997
998 //@}
999
1000 /**
1001 Returns true if this table supports attributes or false otherwise.
1002
1003 By default, the table automatically creates a wxGridCellAttrProvider
1004 when this function is called if it had no attribute provider before and
1005 returns @true.
1006 */
1007 virtual bool CanHaveAttributes();
1008 };
1009
1010
1011
1012 /**
1013 @class wxGrid
1014
1015 wxGrid and its related classes are used for displaying and editing tabular
1016 data. They provide a rich set of features for display, editing, and
1017 interacting with a variety of data sources. For simple applications, and to
1018 help you get started, wxGrid is the only class you need to refer to
1019 directly. It will set up default instances of the other classes and manage
1020 them for you. For more complex applications you can derive your own classes
1021 for custom grid views, grid data tables, cell editors and renderers. The
1022 @ref overview_grid has examples of simple and more complex applications,
1023 explains the relationship between the various grid classes and has a
1024 summary of the keyboard shortcuts and mouse functions provided by wxGrid.
1025
1026 A wxGridTableBase class holds the actual data to be displayed by a wxGrid
1027 class. One or more wxGrid classes may act as a view for one table class.
1028 The default table class is called wxGridStringTable and holds an array of
1029 strings. An instance of such a class is created by CreateGrid().
1030
1031 wxGridCellRenderer is the abstract base class for rendereing contents in a
1032 cell. The following renderers are predefined:
1033
1034 - wxGridCellBoolRenderer
1035 - wxGridCellFloatRenderer
1036 - wxGridCellNumberRenderer
1037 - wxGridCellStringRenderer
1038
1039 The look of a cell can be further defined using wxGridCellAttr. An object
1040 of this type may be returned by wxGridTableBase::GetAttr().
1041
1042 wxGridCellEditor is the abstract base class for editing the value of a
1043 cell. The following editors are predefined:
1044
1045 - wxGridCellBoolEditor
1046 - wxGridCellChoiceEditor
1047 - wxGridCellFloatEditor
1048 - wxGridCellNumberEditor
1049 - wxGridCellTextEditor
1050
1051 Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
1052 wxGridEditorCreatedEvent for the documentation of all event types you can
1053 use with wxGrid.
1054
1055 @library{wxadv}
1056 @category{grid}
1057
1058 @see @ref overview_grid, wxGridUpdateLocker
1059 */
1060 class wxGrid : public wxScrolledWindow
1061 {
1062 public:
1063
1064 /**
1065 Different selection modes supported by the grid.
1066 */
1067 enum wxGridSelectionModes
1068 {
1069 /**
1070 The default selection mode allowing selection of the individual
1071 cells as well as of the entire rows and columns.
1072 */
1073 wxGridSelectCells,
1074
1075 /**
1076 The selection mode allowing the selection of the entire rows only.
1077
1078 The user won't be able to select any cells or columns in this mode.
1079 */
1080 wxGridSelectRows,
1081
1082 /**
1083 The selection mode allowing the selection of the entire columns only.
1084
1085 The user won't be able to select any cells or rows in this mode.
1086 */
1087 wxGridSelectColumns
1088 };
1089
1090
1091 /**
1092 @name Constructors and Initialization
1093 */
1094 //@{
1095
1096 /**
1097 Default constructor.
1098
1099 You must call Create() to really create the grid window and also call
1100 CreateGrid() or SetTable() to initialize the grid contents.
1101 */
1102 wxGrid();
1103 /**
1104 Constructor creating the grid window.
1105
1106 You must call either CreateGrid() or SetTable() to initialize the grid
1107 contents before using it.
1108 */
1109 wxGrid(wxWindow* parent, wxWindowID id,
1110 const wxPoint& pos = wxDefaultPosition,
1111 const wxSize& size = wxDefaultSize,
1112 long style = wxWANTS_CHARS,
1113 const wxString& name = wxGridNameStr);
1114
1115 /**
1116 Destructor.
1117
1118 This will also destroy the associated grid table unless you passed a
1119 table object to the grid and specified that the grid should not take
1120 ownership of the table (see SetTable()).
1121 */
1122 virtual ~wxGrid();
1123
1124 /**
1125 Creates the grid window for an object initialized using the default
1126 constructor.
1127
1128 You must call either CreateGrid() or SetTable() to initialize the grid
1129 contents before using it.
1130 */
1131 bool Create(wxWindow* parent, wxWindowID id,
1132 const wxPoint& pos = wxDefaultPosition,
1133 const wxSize& size = wxDefaultSize,
1134 long style = wxWANTS_CHARS,
1135 const wxString& name = wxGridNameStr);
1136
1137 /**
1138 Creates a grid with the specified initial number of rows and columns.
1139
1140 Call this directly after the grid constructor. When you use this
1141 function wxGrid will create and manage a simple table of string values
1142 for you. All of the grid data will be stored in memory.
1143
1144 For applications with more complex data types or relationships, or for
1145 dealing with very large datasets, you should derive your own grid table
1146 class and pass a table object to the grid with SetTable().
1147 */
1148 bool CreateGrid(int numRows, int numCols,
1149 wxGridSelectionModes selmode = wxGridSelectCells);
1150
1151 /**
1152 Passes a pointer to a custom grid table to be used by the grid.
1153
1154 This should be called after the grid constructor and before using the
1155 grid object. If @a takeOwnership is set to @true then the table will be
1156 deleted by the wxGrid destructor.
1157
1158 Use this function instead of CreateGrid() when your application
1159 involves complex or non-string data or data sets that are too large to
1160 fit wholly in memory.
1161 */
1162 bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
1163 wxGridSelectionModes selmode = wxGridSelectCells);
1164
1165 //@}
1166
1167
1168 /**
1169 @name Grid Line Formatting
1170 */
1171 //@{
1172
1173 /**
1174 Turns the drawing of grid lines on or off.
1175 */
1176 void EnableGridLines(bool enable = true);
1177
1178 /**
1179 Returns the pen used for vertical grid lines.
1180
1181 This virtual function may be overridden in derived classes in order to
1182 change the appearance of individual grid lines for the given column
1183 @a col.
1184
1185 See GetRowGridLinePen() for an example.
1186 */
1187 virtual wxPen GetColGridLinePen(int col);
1188
1189 /**
1190 Returns the pen used for grid lines.
1191
1192 This virtual function may be overridden in derived classes in order to
1193 change the appearance of grid lines. Note that currently the pen width
1194 must be 1.
1195
1196 @see GetColGridLinePen(), GetRowGridLinePen()
1197 */
1198 virtual wxPen GetDefaultGridLinePen();
1199
1200 /**
1201 Returns the colour used for grid lines.
1202
1203 @see GetDefaultGridLinePen()
1204 */
1205 wxColour GetGridLineColour() const;
1206
1207 /**
1208 Returns the pen used for horizontal grid lines.
1209
1210 This virtual function may be overridden in derived classes in order to
1211 change the appearance of individual grid line for the given @a row.
1212
1213 Example:
1214 @code
1215 // in a grid displaying music notation, use a solid black pen between
1216 // octaves (C0=row 127, C1=row 115 etc.)
1217 wxPen MidiGrid::GetRowGridLinePen(int row)
1218 {
1219 if ( row % 12 == 7 )
1220 return wxPen(*wxBLACK, 1, wxSOLID);
1221 else
1222 return GetDefaultGridLinePen();
1223 }
1224 @endcode
1225 */
1226 virtual wxPen GetRowGridLinePen(int row);
1227
1228 /**
1229 Returns @true if drawing of grid lines is turned on, @false otherwise.
1230 */
1231 bool GridLinesEnabled() const;
1232
1233 /**
1234 Sets the colour used to draw grid lines.
1235 */
1236 void SetGridLineColour(const wxColour& colour);
1237
1238 //@}
1239
1240
1241 /**
1242 @name Label Values and Formatting
1243 */
1244 //@{
1245
1246 /**
1247 Sets the arguments to the current column label alignment values.
1248
1249 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1250 or @c wxALIGN_RIGHT.
1251
1252 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1253 @c wxALIGN_BOTTOM.
1254 */
1255 void GetColLabelAlignment(int* horiz, int* vert) const;
1256
1257 /**
1258 Returns the orientation of the column labels (either @c wxHORIZONTAL or
1259 @c wxVERTICAL).
1260 */
1261 int GetColLabelTextOrientation() const;
1262
1263 /**
1264 Returns the specified column label.
1265
1266 The default grid table class provides column labels of the form
1267 A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can
1268 override wxGridTableBase::GetColLabelValue() to provide your own
1269 labels.
1270 */
1271 wxString GetColLabelValue(int col) const;
1272
1273 /**
1274 Returns the colour used for the background of row and column labels.
1275 */
1276 wxColour GetLabelBackgroundColour() const;
1277
1278 /**
1279 Returns the font used for row and column labels.
1280 */
1281 wxFont GetLabelFont() const;
1282
1283 /**
1284 Returns the colour used for row and column label text.
1285 */
1286 wxColour GetLabelTextColour() const;
1287
1288 /**
1289 Returns the alignment used for row labels.
1290
1291 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1292 or @c wxALIGN_RIGHT.
1293
1294 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1295 @c wxALIGN_BOTTOM.
1296 */
1297 void GetRowLabelAlignment(int* horiz, int* vert) const;
1298
1299 /**
1300 Returns the specified row label.
1301
1302 The default grid table class provides numeric row labels. If you are
1303 using a custom grid table you can override
1304 wxGridTableBase::GetRowLabelValue() to provide your own labels.
1305 */
1306 wxString GetRowLabelValue(int row) const;
1307
1308 /**
1309 Hides the column labels by calling SetColLabelSize() with a size of 0.
1310 Show labels again by calling that method with a width greater than 0.
1311 */
1312 void HideColLabels();
1313
1314 /**
1315 Hides the row labels by calling SetRowLabelSize() with a size of 0.
1316
1317 The labels can be shown again by calling SetRowLabelSize() with a width
1318 greater than 0.
1319 */
1320 void HideRowLabels();
1321
1322 /**
1323 Sets the horizontal and vertical alignment of column label text.
1324
1325 Horizontal alignment should be one of @c wxALIGN_LEFT,
1326 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
1327 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
1328 */
1329 void SetColLabelAlignment(int horiz, int vert);
1330
1331 /**
1332 Sets the orientation of the column labels (either @c wxHORIZONTAL or
1333 @c wxVERTICAL).
1334 */
1335 void SetColLabelTextOrientation(int textOrientation);
1336
1337 /**
1338 Set the value for the given column label.
1339
1340 If you are using a custom grid table you must override
1341 wxGridTableBase::SetColLabelValue() for this to have any effect.
1342 */
1343 void SetColLabelValue(int col, const wxString& value);
1344
1345 /**
1346 Sets the background colour for row and column labels.
1347 */
1348 void SetLabelBackgroundColour(const wxColour& colour);
1349
1350 /**
1351 Sets the font for row and column labels.
1352 */
1353 void SetLabelFont(const wxFont& font);
1354
1355 /**
1356 Sets the colour for row and column label text.
1357 */
1358 void SetLabelTextColour(const wxColour& colour);
1359
1360 /**
1361 Sets the horizontal and vertical alignment of row label text.
1362
1363 Horizontal alignment should be one of @c wxALIGN_LEFT,
1364 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
1365 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
1366 */
1367 void SetRowLabelAlignment(int horiz, int vert);
1368
1369 /**
1370 Sets the value for the given row label.
1371
1372 If you are using a derived grid table you must override
1373 wxGridTableBase::SetRowLabelValue() for this to have any effect.
1374 */
1375 void SetRowLabelValue(int row, const wxString& value);
1376
1377 /**
1378 Call this in order to make the column labels use a native look by using
1379 wxRenderer::DrawHeaderButton() internally.
1380
1381 There is no equivalent method for drawing row columns as there is not
1382 native look for that. This option is useful when using wxGrid for
1383 displaying tables and not as a spread-sheet.
1384
1385 @see UseNativeHeader()
1386 */
1387 void SetUseNativeColLabels(bool native = true);
1388
1389 /**
1390 Enable the use of native header window for column labels.
1391
1392 If this function is called with @true argument, a wxHeaderCtrl is used
1393 instead to display the column labels instead of drawing them in wxGrid
1394 code itself. This has the advantage of making the grid look and feel
1395 perfectly the same as native applications (using SetUseNativeColLabels()
1396 the grid can be made to look more natively but it still doesn't feel
1397 natively, notably the column resizing and dragging still works slightly
1398 differently as it is implemented in wxWidgets itself) but results in
1399 different behaviour for column and row headers, for which there is no
1400 equivalent function, and, most importantly, is unsuitable for grids
1401 with huge numbers of columns as wxHeaderCtrl doesn't support virtual
1402 mode. Because of this, by default the grid does not use the native
1403 header control but you should call this function to enable it if you
1404 are using the grid to display tabular data and don't have thousands of
1405 columns in it.
1406
1407 Also note that currently @c wxEVT_GRID_LABEL_LEFT_DCLICK and @c
1408 wxEVT_GRID_LABEL_RIGHT_DCLICK events are not generated for the column
1409 labels if the native columns header is used (but this limitation could
1410 possibly be lifted in the future).
1411 */
1412 void UseNativeColHeader(bool native = true);
1413
1414 //@}
1415
1416
1417 /**
1418 @name Cell Formatting
1419
1420 Note that wxGridCellAttr can be used alternatively to most of these
1421 methods. See the "Attributes Management" of wxGridTableBase.
1422 */
1423 //@{
1424
1425 /**
1426 Sets the arguments to the horizontal and vertical text alignment values
1427 for the grid cell at the specified location.
1428
1429 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1430 or @c wxALIGN_RIGHT.
1431
1432 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1433 @c wxALIGN_BOTTOM.
1434 */
1435 void GetCellAlignment(int row, int col, int* horiz, int* vert) const;
1436
1437 /**
1438 Returns the background colour of the cell at the specified location.
1439 */
1440 wxColour GetCellBackgroundColour(int row, int col) const;
1441
1442 /**
1443 Returns the font for text in the grid cell at the specified location.
1444 */
1445 wxFont GetCellFont(int row, int col) const;
1446
1447 /**
1448 Returns the text colour for the grid cell at the specified location.
1449 */
1450 wxColour GetCellTextColour(int row, int col) const;
1451
1452 /**
1453 Returns the default cell alignment.
1454
1455 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1456 or @c wxALIGN_RIGHT.
1457
1458 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1459 @c wxALIGN_BOTTOM.
1460
1461 @see SetDefaultCellAlignment()
1462 */
1463 void GetDefaultCellAlignment(int* horiz, int* vert) const;
1464
1465 /**
1466 Returns the current default background colour for grid cells.
1467 */
1468 wxColour GetDefaultCellBackgroundColour() const;
1469
1470 /**
1471 Returns the current default font for grid cell text.
1472 */
1473 wxFont GetDefaultCellFont() const;
1474
1475 /**
1476 Returns the current default colour for grid cell text.
1477 */
1478 wxColour GetDefaultCellTextColour() const;
1479
1480 /**
1481 Sets the horizontal and vertical alignment for grid cell text at the
1482 specified location.
1483
1484 Horizontal alignment should be one of @c wxALIGN_LEFT,
1485 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
1486
1487 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
1488 or @c wxALIGN_BOTTOM.
1489 */
1490 void SetCellAlignment(int row, int col, int horiz, int vert);
1491 /**
1492 Sets the horizontal and vertical alignment for grid cell text at the
1493 specified location.
1494
1495 Horizontal alignment should be one of @c wxALIGN_LEFT,
1496 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
1497
1498 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
1499 or @c wxALIGN_BOTTOM.
1500 */
1501 void SetCellAlignment(int align, int row, int col);
1502
1503 /**
1504 Set the background colour for the given cell or all cells by default.
1505 */
1506 void SetCellBackgroundColour(int row, int col, const wxColour& colour);
1507
1508 /**
1509 Sets the font for text in the grid cell at the specified location.
1510 */
1511 void SetCellFont(int row, int col, const wxFont& font);
1512
1513 /**
1514 Sets the text colour for the given cell.
1515 */
1516 void SetCellTextColour(int row, int col, const wxColour& colour);
1517 /**
1518 Sets the text colour for the given cell.
1519 */
1520 void SetCellTextColour(const wxColour& val, int row, int col);
1521 /**
1522 Sets the text colour for all cells by default.
1523 */
1524 void SetCellTextColour(const wxColour& colour);
1525
1526 /**
1527 Sets the default horizontal and vertical alignment for grid cell text.
1528
1529 Horizontal alignment should be one of @c wxALIGN_LEFT,
1530 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
1531 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
1532 */
1533 void SetDefaultCellAlignment(int horiz, int vert);
1534
1535 /**
1536 Sets the default background colour for grid cells.
1537 */
1538 void SetDefaultCellBackgroundColour(const wxColour& colour);
1539
1540 /**
1541 Sets the default font to be used for grid cell text.
1542 */
1543 void SetDefaultCellFont(const wxFont& font);
1544
1545 /**
1546 Sets the current default colour for grid cell text.
1547 */
1548 void SetDefaultCellTextColour(const wxColour& colour);
1549
1550 //@}
1551
1552
1553 /**
1554 @name Cell Values, Editors, and Renderers
1555
1556 Note that wxGridCellAttr can be used alternatively to most of these
1557 methods. See the "Attributes Management" of wxGridTableBase.
1558 */
1559 //@{
1560
1561 /**
1562 Returns @true if the in-place edit control for the current grid cell
1563 can be used and @false otherwise.
1564
1565 This function always returns @false for the read-only cells.
1566 */
1567 bool CanEnableCellControl() const;
1568
1569 /**
1570 Disables in-place editing of grid cells.
1571
1572 Equivalent to calling EnableCellEditControl(@false).
1573 */
1574 void DisableCellEditControl();
1575
1576 /**
1577 Enables or disables in-place editing of grid cell data.
1578
1579 The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
1580 @c wxEVT_GRID_EDITOR_HIDDEN event.
1581 */
1582 void EnableCellEditControl(bool enable = true);
1583
1584 /**
1585 Makes the grid globally editable or read-only.
1586
1587 If the edit argument is @false this function sets the whole grid as
1588 read-only. If the argument is @true the grid is set to the default
1589 state where cells may be editable. In the default state you can set
1590 single grid cells and whole rows and columns to be editable or
1591 read-only via wxGridCellAttr::SetReadOnly(). For single cells you
1592 can also use the shortcut function SetReadOnly().
1593
1594 For more information about controlling grid cell attributes see the
1595 wxGridCellAttr class and the @ref overview_grid.
1596 */
1597 void EnableEditing(bool edit);
1598
1599 /**
1600 Returns a pointer to the editor for the cell at the specified location.
1601
1602 See wxGridCellEditor and the @ref overview_grid for more information
1603 about cell editors and renderers.
1604
1605 The caller must call DecRef() on the returned pointer.
1606 */
1607 wxGridCellEditor* GetCellEditor(int row, int col) const;
1608
1609 /**
1610 Returns a pointer to the renderer for the grid cell at the specified
1611 location.
1612
1613 See wxGridCellRenderer and the @ref overview_grid for more information
1614 about cell editors and renderers.
1615
1616 The caller must call DecRef() on the returned pointer.
1617 */
1618 wxGridCellRenderer* GetCellRenderer(int row, int col) const;
1619
1620 /**
1621 Returns the string contained in the cell at the specified location.
1622
1623 For simple applications where a grid object automatically uses a
1624 default grid table of string values you use this function together with
1625 SetCellValue() to access cell values. For more complex applications
1626 where you have derived your own grid table class that contains various
1627 data types (e.g. numeric, boolean or user-defined custom types) then
1628 you only use this function for those cells that contain string values.
1629
1630 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
1631 more information.
1632 */
1633 wxString GetCellValue(int row, int col) const;
1634 /**
1635 Returns the string contained in the cell at the specified location.
1636
1637 For simple applications where a grid object automatically uses a
1638 default grid table of string values you use this function together with
1639 SetCellValue() to access cell values. For more complex applications
1640 where you have derived your own grid table class that contains various
1641 data types (e.g. numeric, boolean or user-defined custom types) then
1642 you only use this function for those cells that contain string values.
1643
1644 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
1645 more information.
1646 */
1647 const wxString GetCellValue(const wxGridCellCoords& coords) const;
1648
1649 /**
1650 Returns a pointer to the current default grid cell editor.
1651
1652 See wxGridCellEditor and the @ref overview_grid for more information
1653 about cell editors and renderers.
1654 */
1655 wxGridCellEditor* GetDefaultEditor() const;
1656
1657 /**
1658 Returns the default editor for the specified cell.
1659
1660 The base class version returns the editor appropriate for the current
1661 cell type but this method may be overridden in the derived classes to
1662 use custom editors for some cells by default.
1663
1664 Notice that the same may be achieved in a usually simpler way by
1665 associating a custom editor with the given cell or cells.
1666
1667 The caller must call DecRef() on the returned pointer.
1668 */
1669 virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const;
1670 /**
1671 Returns the default editor for the specified cell.
1672
1673 The base class version returns the editor appropriate for the current
1674 cell type but this method may be overridden in the derived classes to
1675 use custom editors for some cells by default.
1676
1677 Notice that the same may be achieved in a usually simpler way by
1678 associating a custom editor with the given cell or cells.
1679
1680 The caller must call DecRef() on the returned pointer.
1681 */
1682 wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const;
1683
1684 /**
1685 Returns the default editor for the cells containing values of the given
1686 type.
1687
1688 The base class version returns the editor which was associated with the
1689 specified @a typeName when it was registered RegisterDataType() but
1690 this function may be overridden to return something different. This
1691 allows to override an editor used for one of the standard types.
1692
1693 The caller must call DecRef() on the returned pointer.
1694 */
1695 virtual wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const;
1696
1697 /**
1698 Returns a pointer to the current default grid cell renderer.
1699
1700 See wxGridCellRenderer and the @ref overview_grid for more information
1701 about cell editors and renderers.
1702
1703 The caller must call DecRef() on the returned pointer.
1704 */
1705 wxGridCellRenderer* GetDefaultRenderer() const;
1706
1707 /**
1708 Returns the default renderer for the given cell.
1709
1710 The base class version returns the renderer appropriate for the current
1711 cell type but this method may be overridden in the derived classes to
1712 use custom renderers for some cells by default.
1713
1714 The caller must call DecRef() on the returned pointer.
1715 */
1716 virtual wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const;
1717
1718 /**
1719 Returns the default renderer for the cell containing values of the
1720 given type.
1721
1722 @see GetDefaultEditorForType()
1723 */
1724 virtual wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const;
1725
1726 /**
1727 Hides the in-place cell edit control.
1728 */
1729 void HideCellEditControl();
1730
1731 /**
1732 Returns @true if the in-place edit control is currently enabled.
1733 */
1734 bool IsCellEditControlEnabled() const;
1735
1736 /**
1737 Returns @true if the current cell is read-only.
1738
1739 @see SetReadOnly(), IsReadOnly()
1740 */
1741 bool IsCurrentCellReadOnly() const;
1742
1743 /**
1744 Returns @false if the whole grid has been set as read-only or @true
1745 otherwise.
1746
1747 See EnableEditing() for more information about controlling the editing
1748 status of grid cells.
1749 */
1750 bool IsEditable() const;
1751
1752 /**
1753 Returns @true if the cell at the specified location can't be edited.
1754
1755 @see SetReadOnly(), IsCurrentCellReadOnly()
1756 */
1757 bool IsReadOnly(int row, int col) const;
1758
1759 /**
1760 Register a new data type.
1761
1762 The data types allow to naturally associate specific renderers and
1763 editors to the cells containing values of the given type. For example,
1764 the grid automatically registers a data type with the name
1765 @c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and
1766 wxGridCellTextEditor as its renderer and editor respectively -- this is
1767 the data type used by all the cells of the default wxGridStringTable,
1768 so this renderer and editor are used by default for all grid cells.
1769
1770 However if a custom table returns @c wxGRID_VALUE_BOOL from its
1771 wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and
1772 wxGridCellBoolEditor are used for it because the grid also registers a
1773 boolean data type with this name.
1774
1775 And as this mechanism is completely generic, you may register your own
1776 data types using your own custom renderers and editors. Just remember
1777 that the table must identify a cell as being of the given type for them
1778 to be used for this cell.
1779
1780 @param typeName
1781 Name of the new type. May be any string, but if the type name is
1782 the same as the name of an already registered type, including one
1783 of the standard ones (which are @c wxGRID_VALUE_STRING, @c
1784 wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT
1785 and @c wxGRID_VALUE_CHOICE), then the new registration information
1786 replaces the previously used renderer and editor.
1787 @param renderer
1788 The renderer to use for the cells of this type. Its ownership is
1789 taken by the grid, i.e. it will call DecRef() on this pointer when
1790 it doesn't need it any longer.
1791 @param editor
1792 The editor to use for the cells of this type. Its ownership is also
1793 taken by the grid.
1794 */
1795 void RegisterDataType(const wxString& typeName,
1796 wxGridCellRenderer* renderer,
1797 wxGridCellEditor* editor);
1798
1799 /**
1800 Sets the value of the current grid cell to the current in-place edit
1801 control value.
1802
1803 This is called automatically when the grid cursor moves from the
1804 current cell to a new cell. It is also a good idea to call this
1805 function when closing a grid since any edits to the final cell location
1806 will not be saved otherwise.
1807 */
1808 void SaveEditControlValue();
1809
1810 /**
1811 Sets the editor for the grid cell at the specified location.
1812
1813 The grid will take ownership of the pointer.
1814
1815 See wxGridCellEditor and the @ref overview_grid for more information
1816 about cell editors and renderers.
1817 */
1818 void SetCellEditor(int row, int col, wxGridCellEditor* editor);
1819
1820 /**
1821 Sets the renderer for the grid cell at the specified location.
1822
1823 The grid will take ownership of the pointer.
1824
1825 See wxGridCellRenderer and the @ref overview_grid for more information
1826 about cell editors and renderers.
1827 */
1828 void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer);
1829
1830 /**
1831 Sets the string value for the cell at the specified location.
1832
1833 For simple applications where a grid object automatically uses a
1834 default grid table of string values you use this function together with
1835 GetCellValue() to access cell values. For more complex applications
1836 where you have derived your own grid table class that contains various
1837 data types (e.g. numeric, boolean or user-defined custom types) then
1838 you only use this function for those cells that contain string values.
1839
1840 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
1841 more information.
1842 */
1843 void SetCellValue(int row, int col, const wxString& s);
1844 /**
1845 Sets the string value for the cell at the specified location.
1846
1847 For simple applications where a grid object automatically uses a
1848 default grid table of string values you use this function together with
1849 GetCellValue() to access cell values. For more complex applications
1850 where you have derived your own grid table class that contains various
1851 data types (e.g. numeric, boolean or user-defined custom types) then
1852 you only use this function for those cells that contain string values.
1853
1854 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
1855 more information.
1856 */
1857 void SetCellValue(const wxGridCellCoords& coords, const wxString& s);
1858 /**
1859 @deprecated Please use SetCellValue(int,int,const wxString&) or
1860 SetCellValue(const wxGridCellCoords&,const wxString&)
1861 instead.
1862
1863 Sets the string value for the cell at the specified location.
1864
1865 For simple applications where a grid object automatically uses a
1866 default grid table of string values you use this function together with
1867 GetCellValue() to access cell values. For more complex applications
1868 where you have derived your own grid table class that contains various
1869 data types (e.g. numeric, boolean or user-defined custom types) then
1870 you only use this function for those cells that contain string values.
1871
1872 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
1873 more information.
1874 */
1875 void SetCellValue(const wxString& val, int row, int col);
1876
1877 /**
1878 Sets the specified column to display boolean values.
1879
1880 @see SetColFormatCustom()
1881 */
1882 void SetColFormatBool(int col);
1883
1884 /**
1885 Sets the specified column to display data in a custom format.
1886
1887 This method provides an alternative to defining a custom grid table
1888 which would return @a typeName from its GetTypeName() method for the
1889 cells in this column: while it doesn't really change the type of the
1890 cells in this column, it does associate the renderer and editor used
1891 for the cells of the specified type with them.
1892
1893 See the @ref overview_grid for more information on working with custom
1894 data types.
1895 */
1896 void SetColFormatCustom(int col, const wxString& typeName);
1897
1898 /**
1899 Sets the specified column to display floating point values with the
1900 given width and precision.
1901
1902 @see SetColFormatCustom()
1903 */
1904 void SetColFormatFloat(int col, int width = -1, int precision = -1);
1905
1906 /**
1907 Sets the specified column to display integer values.
1908
1909 @see SetColFormatCustom()
1910 */
1911 void SetColFormatNumber(int col);
1912
1913 /**
1914 Sets the default editor for grid cells.
1915
1916 The grid will take ownership of the pointer.
1917
1918 See wxGridCellEditor and the @ref overview_grid for more information
1919 about cell editors and renderers.
1920 */
1921 void SetDefaultEditor(wxGridCellEditor* editor);
1922
1923 /**
1924 Sets the default renderer for grid cells.
1925
1926 The grid will take ownership of the pointer.
1927
1928 See wxGridCellRenderer and the @ref overview_grid for more information
1929 about cell editors and renderers.
1930 */
1931 void SetDefaultRenderer(wxGridCellRenderer* renderer);
1932
1933 /**
1934 Makes the cell at the specified location read-only or editable.
1935
1936 @see IsReadOnly()
1937 */
1938 void SetReadOnly(int row, int col, bool isReadOnly = true);
1939
1940 /**
1941 Displays the in-place cell edit control for the current cell.
1942 */
1943 void ShowCellEditControl();
1944
1945 //@}
1946
1947
1948 /**
1949 @name Column and Row Sizes
1950 */
1951 //@{
1952
1953 /**
1954 Automatically sets the height and width of all rows and columns to fit
1955 their contents.
1956 */
1957 void AutoSize();
1958
1959 /**
1960 Automatically adjusts width of the column to fit its label.
1961 */
1962 void AutoSizeColLabelSize(int col);
1963
1964 /**
1965 Automatically sizes the column to fit its contents. If @a setAsMin is
1966 @true the calculated width will also be set as the minimal width for
1967 the column.
1968 */
1969 void AutoSizeColumn(int col, bool setAsMin = true);
1970
1971 /**
1972 Automatically sizes all columns to fit their contents. If @a setAsMin
1973 is @true the calculated widths will also be set as the minimal widths
1974 for the columns.
1975 */
1976 void AutoSizeColumns(bool setAsMin = true);
1977
1978 /**
1979 Automatically sizes the row to fit its contents. If @a setAsMin is
1980 @true the calculated height will also be set as the minimal height for
1981 the row.
1982 */
1983 void AutoSizeRow(int row, bool setAsMin = true);
1984
1985 /**
1986 Automatically adjusts height of the row to fit its label.
1987 */
1988 void AutoSizeRowLabelSize(int col);
1989
1990 /**
1991 Automatically sizes all rows to fit their contents. If @a setAsMin is
1992 @true the calculated heights will also be set as the minimal heights
1993 for the rows.
1994 */
1995 void AutoSizeRows(bool setAsMin = true);
1996
1997 /**
1998 Returns the current height of the column labels.
1999 */
2000 int GetColLabelSize() const;
2001
2002 /**
2003 Returns the minimal width to which a column may be resized.
2004
2005 Use SetColMinimalAcceptableWidth() to change this value globally or
2006 SetColMinimalWidth() to do it for individual columns.
2007
2008 @see GetRowMinimalAcceptableHeight()
2009 */
2010 int GetColMinimalAcceptableWidth() const;
2011
2012 /**
2013 Returns the width of the specified column.
2014 */
2015 int GetColSize(int col) const;
2016
2017 /**
2018 Returns @true if the specified column is not currently hidden.
2019 */
2020 bool IsColShown(int col) const;
2021
2022 /**
2023 Returns the default height for column labels.
2024 */
2025 int GetDefaultColLabelSize() const;
2026
2027 /**
2028 Returns the current default width for grid columns.
2029 */
2030 int GetDefaultColSize() const;
2031
2032 /**
2033 Returns the default width for the row labels.
2034 */
2035 int GetDefaultRowLabelSize() const;
2036
2037 /**
2038 Returns the current default height for grid rows.
2039 */
2040 int GetDefaultRowSize() const;
2041
2042 /**
2043 Returns the minimal size to which rows can be resized.
2044
2045 Use SetRowMinimalAcceptableHeight() to change this value globally or
2046 SetRowMinimalHeight() to do it for individual cells.
2047
2048 @see GetColMinimalAcceptableWidth()
2049 */
2050 int GetRowMinimalAcceptableHeight() const;
2051
2052 /**
2053 Returns the current width of the row labels.
2054 */
2055 int GetRowLabelSize() const;
2056
2057 /**
2058 Returns the height of the specified row.
2059 */
2060 int GetRowSize(int row) const;
2061
2062 /**
2063 Returns @true if the specified row is not currently hidden.
2064 */
2065 bool IsRowShown(int row) const;
2066
2067 /**
2068 Sets the height of the column labels.
2069
2070 If @a height equals to @c wxGRID_AUTOSIZE then height is calculated
2071 automatically so that no label is truncated. Note that this could be
2072 slow for a large table.
2073 */
2074 void SetColLabelSize(int height);
2075
2076 /**
2077 Sets the minimal @a width to which the user can resize columns.
2078
2079 @see GetColMinimalAcceptableWidth()
2080 */
2081 void SetColMinimalAcceptableWidth(int width);
2082
2083 /**
2084 Sets the minimal @a width for the specified column @a col.
2085
2086 It is usually best to call this method during grid creation as calling
2087 it later will not resize the column to the given minimal width even if
2088 it is currently narrower than it.
2089
2090 @a width must be greater than the minimal acceptable column width as
2091 returned by GetColMinimalAcceptableWidth().
2092 */
2093 void SetColMinimalWidth(int col, int width);
2094
2095 /**
2096 Sets the width of the specified column.
2097
2098 @param col
2099 The column index.
2100 @param width
2101 The new column width in pixels, 0 to hide the column or -1 to fit
2102 the column width to its label width.
2103 */
2104 void SetColSize(int col, int width);
2105
2106 /**
2107 Hides the specified column.
2108
2109 To show the column later you need to call SetColSize() with non-0
2110 width or ShowCol().
2111
2112 @param col
2113 The column index.
2114 */
2115 void HideCol(int col);
2116
2117 /**
2118 Shows the previously hidden column by resizing it to non-0 size.
2119
2120 @see HideCol(), SetColSize()
2121 */
2122 void ShowCol(int col);
2123
2124
2125 /**
2126 Sets the default width for columns in the grid.
2127
2128 This will only affect columns subsequently added to the grid unless
2129 @a resizeExistingCols is @true.
2130
2131 If @a width is less than GetColMinimalAcceptableWidth(), then the
2132 minimal acceptable width is used instead of it.
2133 */
2134 void SetDefaultColSize(int width, bool resizeExistingCols = false);
2135
2136 /**
2137 Sets the default height for rows in the grid.
2138
2139 This will only affect rows subsequently added to the grid unless
2140 @a resizeExistingRows is @true.
2141
2142 If @a height is less than GetRowMinimalAcceptableHeight(), then the
2143 minimal acceptable heihgt is used instead of it.
2144 */
2145 void SetDefaultRowSize(int height, bool resizeExistingRows = false);
2146
2147 /**
2148 Sets the width of the row labels.
2149
2150 If @a width equals @c wxGRID_AUTOSIZE then width is calculated
2151 automatically so that no label is truncated. Note that this could be
2152 slow for a large table.
2153 */
2154 void SetRowLabelSize(int width);
2155
2156 /**
2157 Sets the minimal row @a height used by default.
2158
2159 See SetColMinimalAcceptableWidth() for more information.
2160 */
2161 void SetRowMinimalAcceptableHeight(int height);
2162
2163 /**
2164 Sets the minimal @a height for the specified @a row.
2165
2166 See SetColMinimalWidth() for more information.
2167 */
2168 void SetRowMinimalHeight(int row, int height);
2169
2170 /**
2171 Sets the height of the specified row.
2172
2173 See SetColSize() for more information.
2174 */
2175 void SetRowSize(int row, int height);
2176
2177 /**
2178 Hides the specified row.
2179
2180 To show the row later you need to call SetRowSize() with non-0
2181 width or ShowRow().
2182
2183 @param col
2184 The row index.
2185 */
2186 void HideRow(int col);
2187
2188 /**
2189 Shows the previously hidden row by resizing it to non-0 size.
2190
2191 @see HideRow(), SetRowSize()
2192 */
2193 void ShowRow(int col);
2194
2195 //@}
2196
2197
2198 /**
2199 @name User-Resizing and Dragging
2200 */
2201 //@{
2202
2203 /**
2204 Return @true if the dragging of cells is enabled or @false otherwise.
2205 */
2206 bool CanDragCell() const;
2207
2208 /**
2209 Returns @true if columns can be moved by dragging with the mouse.
2210
2211 Columns can be moved by dragging on their labels.
2212 */
2213 bool CanDragColMove() const;
2214
2215 /**
2216 Returns @true if columns can be resized by dragging with the mouse.
2217
2218 Columns can be resized by dragging the edges of their labels. If grid
2219 line dragging is enabled they can also be resized by dragging the right
2220 edge of the column in the grid cell area (see EnableDragGridSize()).
2221 */
2222 bool CanDragColSize() const;
2223
2224 /**
2225 Return @true if the dragging of grid lines to resize rows and columns
2226 is enabled or @false otherwise.
2227 */
2228 bool CanDragGridSize() const;
2229
2230 /**
2231 Returns @true if rows can be resized by dragging with the mouse.
2232
2233 Rows can be resized by dragging the edges of their labels. If grid line
2234 dragging is enabled they can also be resized by dragging the lower edge
2235 of the row in the grid cell area (see EnableDragGridSize()).
2236 */
2237 bool CanDragRowSize() const;
2238
2239 /**
2240 Disables column moving by dragging with the mouse.
2241
2242 Equivalent to passing @false to EnableDragColMove().
2243 */
2244 void DisableDragColMove();
2245
2246 /**
2247 Disables column sizing by dragging with the mouse.
2248
2249 Equivalent to passing @false to EnableDragColSize().
2250 */
2251 void DisableDragColSize();
2252
2253 /**
2254 Disable mouse dragging of grid lines to resize rows and columns.
2255
2256 Equivalent to passing @false to EnableDragGridSize()
2257 */
2258 void DisableDragGridSize();
2259
2260 /**
2261 Disables row sizing by dragging with the mouse.
2262
2263 Equivalent to passing @false to EnableDragRowSize().
2264 */
2265 void DisableDragRowSize();
2266
2267 /**
2268 Enables or disables cell dragging with the mouse.
2269 */
2270 void EnableDragCell(bool enable = true);
2271
2272 /**
2273 Enables or disables column moving by dragging with the mouse.
2274 */
2275 void EnableDragColMove(bool enable = true);
2276
2277 /**
2278 Enables or disables column sizing by dragging with the mouse.
2279 */
2280 void EnableDragColSize(bool enable = true);
2281
2282 /**
2283 Enables or disables row and column resizing by dragging gridlines with
2284 the mouse.
2285 */
2286 void EnableDragGridSize(bool enable = true);
2287
2288 /**
2289 Enables or disables row sizing by dragging with the mouse.
2290 */
2291 void EnableDragRowSize(bool enable = true);
2292
2293 /**
2294 Returns the column ID of the specified column position.
2295 */
2296 int GetColAt(int colPos) const;
2297
2298 /**
2299 Returns the position of the specified column.
2300 */
2301 int GetColPos(int colID) const;
2302
2303 /**
2304 Sets the position of the specified column.
2305 */
2306 void SetColPos(int colID, int newPos);
2307
2308 /**
2309 Sets the positions of all columns at once.
2310
2311 This method takes an array containing the indices of the columns in
2312 their display order, i.e. uses the same convention as
2313 wxHeaderCtrl::SetColumnsOrder().
2314 */
2315 void SetColumnsOrder(const wxArrayInt& order);
2316
2317 /**
2318 Resets the position of the columns to the default.
2319 */
2320 void ResetColPos();
2321
2322 //@}
2323
2324
2325 /**
2326 @name Cursor Movement
2327 */
2328 //@{
2329
2330 /**
2331 Returns the current grid cell column position.
2332 */
2333 int GetGridCursorCol() const;
2334
2335 /**
2336 Returns the current grid cell row position.
2337 */
2338 int GetGridCursorRow() const;
2339
2340 /**
2341 Make the given cell current and ensure it is visible.
2342
2343 This method is equivalent to calling MakeCellVisible() and
2344 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
2345 event is generated by it and the selected cell doesn't change if the
2346 event is vetoed.
2347 */
2348 void GoToCell(int row, int col);
2349 /**
2350 Make the given cell current and ensure it is visible.
2351
2352 This method is equivalent to calling MakeCellVisible() and
2353 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
2354 event is generated by it and the selected cell doesn't change if the
2355 event is vetoed.
2356 */
2357 void GoToCell(const wxGridCellCoords& coords);
2358
2359 /**
2360 Moves the grid cursor down by one row.
2361
2362 If a block of cells was previously selected it will expand if the
2363 argument is @true or be cleared if the argument is @false.
2364 */
2365 bool MoveCursorDown(bool expandSelection);
2366
2367 /**
2368 Moves the grid cursor down in the current column such that it skips to
2369 the beginning or end of a block of non-empty cells.
2370
2371 If a block of cells was previously selected it will expand if the
2372 argument is @true or be cleared if the argument is @false.
2373 */
2374 bool MoveCursorDownBlock(bool expandSelection);
2375
2376 /**
2377 Moves the grid cursor left by one column.
2378
2379 If a block of cells was previously selected it will expand if the
2380 argument is @true or be cleared if the argument is @false.
2381 */
2382 bool MoveCursorLeft(bool expandSelection);
2383
2384 /**
2385 Moves the grid cursor left in the current row such that it skips to the
2386 beginning or end of a block of non-empty cells.
2387
2388 If a block of cells was previously selected it will expand if the
2389 argument is @true or be cleared if the argument is @false.
2390 */
2391 bool MoveCursorLeftBlock(bool expandSelection);
2392
2393 /**
2394 Moves the grid cursor right by one column.
2395
2396 If a block of cells was previously selected it will expand if the
2397 argument is @true or be cleared if the argument is @false.
2398 */
2399 bool MoveCursorRight(bool expandSelection);
2400
2401 /**
2402 Moves the grid cursor right in the current row such that it skips to
2403 the beginning or end of a block of non-empty cells.
2404
2405 If a block of cells was previously selected it will expand if the
2406 argument is @true or be cleared if the argument is @false.
2407 */
2408 bool MoveCursorRightBlock(bool expandSelection);
2409
2410 /**
2411 Moves the grid cursor up by one row.
2412
2413 If a block of cells was previously selected it will expand if the
2414 argument is @true or be cleared if the argument is @false.
2415 */
2416 bool MoveCursorUp(bool expandSelection);
2417
2418 /**
2419 Moves the grid cursor up in the current column such that it skips to
2420 the beginning or end of a block of non-empty cells.
2421
2422 If a block of cells was previously selected it will expand if the
2423 argument is @true or be cleared if the argument is @false.
2424 */
2425 bool MoveCursorUpBlock(bool expandSelection);
2426
2427 /**
2428 Moves the grid cursor down by some number of rows so that the previous
2429 bottom visible row becomes the top visible row.
2430 */
2431 bool MovePageDown();
2432
2433 /**
2434 Moves the grid cursor up by some number of rows so that the previous
2435 top visible row becomes the bottom visible row.
2436 */
2437 bool MovePageUp();
2438
2439 /**
2440 Set the grid cursor to the specified cell.
2441
2442 The grid cursor indicates the current cell and can be moved by the user
2443 using the arrow keys or the mouse.
2444
2445 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
2446 if the event handler vetoes this event, the cursor is not moved.
2447
2448 This function doesn't make the target call visible, use GoToCell() to
2449 do this.
2450 */
2451 void SetGridCursor(int row, int col);
2452 /**
2453 Set the grid cursor to the specified cell.
2454
2455 The grid cursor indicates the current cell and can be moved by the user
2456 using the arrow keys or the mouse.
2457
2458 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
2459 if the event handler vetoes this event, the cursor is not moved.
2460
2461 This function doesn't make the target call visible, use GoToCell() to
2462 do this.
2463 */
2464 void SetGridCursor(const wxGridCellCoords& coords);
2465
2466 //@}
2467
2468
2469 /**
2470 @name User Selection
2471 */
2472 //@{
2473
2474 /**
2475 Deselects all cells that are currently selected.
2476 */
2477 void ClearSelection();
2478
2479 /**
2480 Returns an array of individually selected cells.
2481
2482 Notice that this array does @em not contain all the selected cells in
2483 general as it doesn't include the cells selected as part of column, row
2484 or block selection. You must use this method, GetSelectedCols(),
2485 GetSelectedRows() and GetSelectionBlockTopLeft() and
2486 GetSelectionBlockBottomRight() methods to obtain the entire selection
2487 in general.
2488
2489 Please notice this behaviour is by design and is needed in order to
2490 support grids of arbitrary size (when an entire column is selected in
2491 a grid with a million of columns, we don't want to create an array with
2492 a million of entries in this function, instead it returns an empty
2493 array and GetSelectedCols() returns an array containing one element).
2494 */
2495 wxGridCellCoordsArray GetSelectedCells() const;
2496
2497 /**
2498 Returns an array of selected columns.
2499
2500 Please notice that this method alone is not sufficient to find all the
2501 selected columns as it contains only the columns which were
2502 individually selected but not those being part of the block selection
2503 or being selected in virtue of all of their cells being selected
2504 individually, please see GetSelectedCells() for more details.
2505 */
2506 wxArrayInt GetSelectedCols() const;
2507
2508 /**
2509 Returns an array of selected rows.
2510
2511 Please notice that this method alone is not sufficient to find all the
2512 selected rows as it contains only the rows which were individually
2513 selected but not those being part of the block selection or being
2514 selected in virtue of all of their cells being selected individually,
2515 please see GetSelectedCells() for more details.
2516 */
2517 wxArrayInt GetSelectedRows() const;
2518
2519 /**
2520 Returns the colour used for drawing the selection background.
2521 */
2522 wxColour GetSelectionBackground() const;
2523
2524 /**
2525 Returns an array of the bottom right corners of blocks of selected
2526 cells.
2527
2528 Please see GetSelectedCells() for more information about the selection
2529 representation in wxGrid.
2530
2531 @see GetSelectionBlockTopLeft()
2532 */
2533 wxGridCellCoordsArray GetSelectionBlockBottomRight() const;
2534
2535 /**
2536 Returns an array of the top left corners of blocks of selected cells.
2537
2538 Please see GetSelectedCells() for more information about the selection
2539 representation in wxGrid.
2540
2541 @see GetSelectionBlockBottomRight()
2542 */
2543 wxGridCellCoordsArray GetSelectionBlockTopLeft() const;
2544
2545 /**
2546 Returns the colour used for drawing the selection foreground.
2547 */
2548 wxColour GetSelectionForeground() const;
2549
2550 /**
2551 Returns the current selection mode.
2552
2553 @see SetSelectionMode().
2554 */
2555 wxGridSelectionModes GetSelectionMode() const;
2556
2557 /**
2558 Returns @true if the given cell is selected.
2559 */
2560 bool IsInSelection(int row, int col) const;
2561 /**
2562 Returns @true if the given cell is selected.
2563 */
2564 bool IsInSelection(const wxGridCellCoords& coords) const;
2565
2566 /**
2567 Returns @true if there are currently any selected cells, rows, columns
2568 or blocks.
2569 */
2570 bool IsSelection() const;
2571
2572 /**
2573 Selects all cells in the grid.
2574 */
2575 void SelectAll();
2576
2577 /**
2578 Selects a rectangular block of cells.
2579
2580 If @a addToSelected is @false then any existing selection will be
2581 deselected; if @true the column will be added to the existing
2582 selection.
2583 */
2584 void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol,
2585 bool addToSelected = false);
2586 /**
2587 Selects a rectangular block of cells.
2588
2589 If @a addToSelected is @false then any existing selection will be
2590 deselected; if @true the column will be added to the existing
2591 selection.
2592 */
2593 void SelectBlock(const wxGridCellCoords& topLeft,
2594 const wxGridCellCoords& bottomRight,
2595 bool addToSelected = false);
2596
2597 /**
2598 Selects the specified column.
2599
2600 If @a addToSelected is @false then any existing selection will be
2601 deselected; if @true the column will be added to the existing
2602 selection.
2603
2604 This method won't select anything if the current selection mode is
2605 wxGridSelectRows.
2606 */
2607 void SelectCol(int col, bool addToSelected = false);
2608
2609 /**
2610 Selects the specified row.
2611
2612 If @a addToSelected is @false then any existing selection will be
2613 deselected; if @true the row will be added to the existing selection.
2614
2615 This method won't select anything if the current selection mode is
2616 wxGridSelectColumns.
2617 */
2618 void SelectRow(int row, bool addToSelected = false);
2619
2620 /**
2621 Set the colour to be used for drawing the selection background.
2622 */
2623 void SetSelectionBackground(const wxColour& c);
2624
2625 /**
2626 Set the colour to be used for drawing the selection foreground.
2627 */
2628 void SetSelectionForeground(const wxColour& c);
2629
2630 /**
2631 Set the selection behaviour of the grid.
2632
2633 The existing selection is converted to conform to the new mode if
2634 possible and discarded otherwise (e.g. any individual selected cells
2635 are deselected if the new mode allows only the selection of the entire
2636 rows or columns).
2637 */
2638 void SetSelectionMode(wxGridSelectionModes selmode);
2639
2640 //@}
2641
2642
2643 /**
2644 @name Scrolling
2645 */
2646 //@{
2647
2648 /**
2649 Returns the number of pixels per horizontal scroll increment.
2650
2651 The default is 15.
2652
2653 @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
2654 */
2655 int GetScrollLineX() const;
2656
2657 /**
2658 Returns the number of pixels per vertical scroll increment.
2659
2660 The default is 15.
2661
2662 @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
2663 */
2664 int GetScrollLineY() const;
2665
2666 /**
2667 Returns @true if a cell is either entirely or at least partially
2668 visible in the grid window.
2669
2670 By default, the cell must be entirely visible for this function to
2671 return @true but if @a wholeCellVisible is @false, the function returns
2672 @true even if the cell is only partially visible.
2673 */
2674 bool IsVisible(int row, int col, bool wholeCellVisible = true) const;
2675 /**
2676 Returns @true if a cell is either entirely or at least partially
2677 visible in the grid window.
2678
2679 By default, the cell must be entirely visible for this function to
2680 return @true but if @a wholeCellVisible is @false, the function returns
2681 @true even if the cell is only partially visible.
2682 */
2683 bool IsVisible(const wxGridCellCoords& coords,
2684 bool wholeCellVisible = true) const;
2685
2686 /**
2687 Brings the specified cell into the visible grid cell area with minimal
2688 scrolling.
2689
2690 Does nothing if the cell is already visible.
2691 */
2692 void MakeCellVisible(int row, int col);
2693 /**
2694 Brings the specified cell into the visible grid cell area with minimal
2695 scrolling.
2696
2697 Does nothing if the cell is already visible.
2698 */
2699 void MakeCellVisible(const wxGridCellCoords& coords);
2700
2701 /**
2702 Sets the number of pixels per horizontal scroll increment.
2703
2704 The default is 15.
2705
2706 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
2707 */
2708 void SetScrollLineX(int x);
2709
2710 /**
2711 Sets the number of pixels per vertical scroll increment.
2712
2713 The default is 15.
2714
2715 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
2716 */
2717 void SetScrollLineY(int y);
2718
2719 //@}
2720
2721
2722 /**
2723 @name Cell and Device Coordinate Translation
2724 */
2725 //@{
2726
2727 /**
2728 Convert grid cell coordinates to grid window pixel coordinates.
2729
2730 This function returns the rectangle that encloses the block of cells
2731 limited by @a topLeft and @a bottomRight cell in device coords and
2732 clipped to the client size of the grid window.
2733
2734 @see CellToRect()
2735 */
2736 wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft,
2737 const wxGridCellCoords& bottomRight) const;
2738
2739 /**
2740 Return the rectangle corresponding to the grid cell's size and position
2741 in logical coordinates.
2742
2743 @see BlockToDeviceRect()
2744 */
2745 wxRect CellToRect(int row, int col) const;
2746 /**
2747 Return the rectangle corresponding to the grid cell's size and position
2748 in logical coordinates.
2749
2750 @see BlockToDeviceRect()
2751 */
2752 const wxRect CellToRect(const wxGridCellCoords& coords) const;
2753
2754 /**
2755 Returns the column at the given pixel position.
2756
2757 @param x
2758 The x position to evaluate.
2759 @param clipToMinMax
2760 If @true, rather than returning @c wxNOT_FOUND, it returns either
2761 the first or last column depending on whether @a x is too far to
2762 the left or right respectively.
2763 @return
2764 The column index or @c wxNOT_FOUND.
2765 */
2766 int XToCol(int x, bool clipToMinMax = false) const;
2767
2768 /**
2769 Returns the column whose right hand edge is close to the given logical
2770 @a x position.
2771
2772 If no column edge is near to this position @c wxNOT_FOUND is returned.
2773 */
2774 int XToEdgeOfCol(int x) const;
2775
2776 /**
2777 Translates logical pixel coordinates to the grid cell coordinates.
2778
2779 Notice that this function expects logical coordinates on input so if
2780 you use this function in a mouse event handler you need to translate
2781 the mouse position, which is expressed in device coordinates, to
2782 logical ones.
2783
2784 @see XToCol(), YToRow()
2785 */
2786 wxGridCellCoords XYToCell(int x, int y) const;
2787 /**
2788 Translates logical pixel coordinates to the grid cell coordinates.
2789
2790 Notice that this function expects logical coordinates on input so if
2791 you use this function in a mouse event handler you need to translate
2792 the mouse position, which is expressed in device coordinates, to
2793 logical ones.
2794
2795 @see XToCol(), YToRow()
2796 */
2797 wxGridCellCoords XYToCell(const wxPoint& pos) const;
2798 // XYToCell(int, int, wxGridCellCoords&) overload is intentionally
2799 // undocumented, using it is ugly and non-const reference parameters are
2800 // not used in wxWidgets API
2801
2802 /**
2803 Returns the row whose bottom edge is close to the given logical @a y
2804 position.
2805
2806 If no row edge is near to this position @c wxNOT_FOUND is returned.
2807 */
2808 int YToEdgeOfRow(int y) const;
2809
2810 /**
2811 Returns the grid row that corresponds to the logical @a y coordinate.
2812
2813 Returns @c wxNOT_FOUND if there is no row at the @a y position.
2814 */
2815 int YToRow(int y, bool clipToMinMax = false) const;
2816
2817 //@}
2818
2819
2820 /**
2821 @name Miscellaneous Functions
2822 */
2823 //@{
2824
2825 /**
2826 Appends one or more new columns to the right of the grid.
2827
2828 The @a updateLabels argument is not used at present. If you are using a
2829 derived grid table class you will need to override
2830 wxGridTableBase::AppendCols(). See InsertCols() for further
2831 information.
2832
2833 @return @true on success or @false if appending columns failed.
2834 */
2835 bool AppendCols(int numCols = 1, bool updateLabels = true);
2836
2837 /**
2838 Appends one or more new rows to the bottom of the grid.
2839
2840 The @a updateLabels argument is not used at present. If you are using a
2841 derived grid table class you will need to override
2842 wxGridTableBase::AppendRows(). See InsertRows() for further
2843 information.
2844
2845 @return @true on success or @false if appending rows failed.
2846 */
2847 bool AppendRows(int numRows = 1, bool updateLabels = true);
2848
2849 /**
2850 Return @true if the horizontal grid lines stop at the last column
2851 boundary or @false if they continue to the end of the window.
2852
2853 The default is to clip grid lines.
2854
2855 @see ClipHorzGridLines(), AreVertGridLinesClipped()
2856 */
2857 bool AreHorzGridLinesClipped() const;
2858
2859 /**
2860 Return @true if the vertical grid lines stop at the last row
2861 boundary or @false if they continue to the end of the window.
2862
2863 The default is to clip grid lines.
2864
2865 @see ClipVertGridLines(), AreHorzGridLinesClipped()
2866 */
2867 bool AreVertGridLinesClipped() const;
2868
2869 /**
2870 Increments the grid's batch count.
2871
2872 When the count is greater than zero repainting of the grid is
2873 suppressed. Each call to BeginBatch must be matched by a later call to
2874 EndBatch(). Code that does a lot of grid modification can be enclosed
2875 between BeginBatch() and EndBatch() calls to avoid screen flicker. The
2876 final EndBatch() call will cause the grid to be repainted.
2877
2878 Notice that you should use wxGridUpdateLocker which ensures that there
2879 is always a matching EndBatch() call for this BeginBatch() if possible
2880 instead of calling this method directly.
2881 */
2882 void BeginBatch();
2883
2884 /**
2885 Clears all data in the underlying grid table and repaints the grid.
2886
2887 The table is not deleted by this function. If you are using a derived
2888 table class then you need to override wxGridTableBase::Clear() for this
2889 function to have any effect.
2890 */
2891 void ClearGrid();
2892
2893 /**
2894 Change whether the horizontal grid lines are clipped by the end of the
2895 last column.
2896
2897 By default the grid lines are not drawn beyond the end of the last
2898 column but after calling this function with @a clip set to @false they
2899 will be drawn across the entire grid window.
2900
2901 @see AreHorzGridLinesClipped(), ClipVertGridLines()
2902 */
2903 void ClipHorzGridLines(bool clip);
2904
2905 /**
2906 Change whether the vertical grid lines are clipped by the end of the
2907 last row.
2908
2909 By default the grid lines are not drawn beyond the end of the last
2910 row but after calling this function with @a clip set to @false they
2911 will be drawn across the entire grid window.
2912
2913 @see AreVertGridLinesClipped(), ClipHorzGridLines()
2914 */
2915 void ClipVertGridLines(bool clip);
2916
2917 /**
2918 Deletes one or more columns from a grid starting at the specified
2919 position.
2920
2921 The @a updateLabels argument is not used at present. If you are using a
2922 derived grid table class you will need to override
2923 wxGridTableBase::DeleteCols(). See InsertCols() for further
2924 information.
2925
2926 @return @true on success or @false if deleting columns failed.
2927 */
2928 bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true);
2929
2930 /**
2931 Deletes one or more rows from a grid starting at the specified
2932 position.
2933
2934 The @a updateLabels argument is not used at present. If you are using a
2935 derived grid table class you will need to override
2936 wxGridTableBase::DeleteRows(). See InsertRows() for further
2937 information.
2938
2939 @return @true on success or @false if appending rows failed.
2940 */
2941 bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true);
2942
2943 /**
2944 Decrements the grid's batch count.
2945
2946 When the count is greater than zero repainting of the grid is
2947 suppressed. Each previous call to BeginBatch() must be matched by a
2948 later call to EndBatch(). Code that does a lot of grid modification can
2949 be enclosed between BeginBatch() and EndBatch() calls to avoid screen
2950 flicker. The final EndBatch() will cause the grid to be repainted.
2951
2952 @see wxGridUpdateLocker
2953 */
2954 void EndBatch();
2955
2956 /**
2957 Overridden wxWindow method.
2958 */
2959 virtual void Fit();
2960
2961 /**
2962 Causes immediate repainting of the grid.
2963
2964 Use this instead of the usual wxWindow::Refresh().
2965 */
2966 void ForceRefresh();
2967
2968 /**
2969 Returns the number of times that BeginBatch() has been called without
2970 (yet) matching calls to EndBatch(). While the grid's batch count is
2971 greater than zero the display will not be updated.
2972 */
2973 int GetBatchCount();
2974
2975 /**
2976 Returns the total number of grid columns.
2977
2978 This is the same as the number of columns in the underlying grid table.
2979 */
2980 int GetNumberCols() const;
2981
2982 /**
2983 Returns the total number of grid rows.
2984
2985 This is the same as the number of rows in the underlying grid table.
2986 */
2987 int GetNumberRows() const;
2988
2989 /**
2990 Returns the attribute for the given cell creating one if necessary.
2991
2992 If the cell already has an attribute, it is returned. Otherwise a new
2993 attribute is created, associated with the cell and returned. In any
2994 case the caller must call DecRef() on the returned pointer.
2995
2996 This function may only be called if CanHaveAttributes() returns @true.
2997 */
2998 wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const;
2999
3000 /**
3001 Returns a base pointer to the current table object.
3002
3003 The returned pointer is still owned by the grid.
3004 */
3005 wxGridTableBase *GetTable() const;
3006
3007 /**
3008 Inserts one or more new columns into a grid with the first new column
3009 at the specified position.
3010
3011 Notice that inserting the columns in the grid requires grid table
3012 cooperation: when this method is called, grid object begins by
3013 requesting the underlying grid table to insert new columns. If this is
3014 successful the table notifies the grid and the grid updates the
3015 display. For a default grid (one where you have called CreateGrid())
3016 this process is automatic. If you are using a custom grid table
3017 (specified with SetTable()) then you must override
3018 wxGridTableBase::InsertCols() in your derived table class.
3019
3020 @param pos
3021 The position which the first newly inserted column will have.
3022 @param numCols
3023 The number of columns to insert.
3024 @param updateLabels
3025 Currently not used.
3026 @return
3027 @true if the columns were successfully inserted, @false if an error
3028 occurred (most likely the table couldn't be updated).
3029 */
3030 bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true);
3031
3032 /**
3033 Inserts one or more new rows into a grid with the first new row at the
3034 specified position.
3035
3036 Notice that you must implement wxGridTableBase::InsertRows() if you use
3037 a grid with a custom table, please see InsertCols() for more
3038 information.
3039
3040 @param pos
3041 The position which the first newly inserted row will have.
3042 @param numRows
3043 The number of rows to insert.
3044 @param updateLabels
3045 Currently not used.
3046 @return
3047 @true if the rows were successfully inserted, @false if an error
3048 occurred (most likely the table couldn't be updated).
3049 */
3050 bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
3051
3052 /**
3053 Sets the cell attributes for all cells in the specified column.
3054
3055 For more information about controlling grid cell attributes see the
3056 wxGridCellAttr cell attribute class and the @ref overview_grid.
3057 */
3058 void SetColAttr(int col, wxGridCellAttr* attr);
3059
3060 /**
3061 Sets the extra margins used around the grid area.
3062
3063 A grid may occupy more space than needed for its data display and
3064 this function allows to set how big this extra space is
3065 */
3066 void SetMargins(int extraWidth, int extraHeight);
3067
3068 /**
3069 Sets the cell attributes for all cells in the specified row.
3070
3071 The grid takes ownership of the attribute pointer.
3072
3073 See the wxGridCellAttr class for more information about controlling
3074 cell attributes.
3075 */
3076 void SetRowAttr(int row, wxGridCellAttr* attr);
3077
3078 //@}
3079
3080 protected:
3081 /**
3082 Returns @true if this grid has support for cell attributes.
3083
3084 The grid supports attributes if it has the associated table which, in
3085 turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes()
3086 returns @true.
3087 */
3088 bool CanHaveAttributes() const;
3089
3090 /**
3091 Get the minimal width of the given column/row.
3092
3093 The value returned by this function may be different than that returned
3094 by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been
3095 called for this column.
3096 */
3097 int GetColMinimalWidth(int col) const;
3098
3099 /**
3100 Returns the coordinate of the right border specified column.
3101 */
3102 int GetColRight(int col) const;
3103
3104 /**
3105 Returns the coordinate of the left border specified column.
3106 */
3107 int GetColLeft(int col) const;
3108
3109 /**
3110 Returns the minimal size for the given column.
3111
3112 The value returned by this function may be different than that returned
3113 by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been
3114 called for this row.
3115 */
3116 int GetRowMinimalHeight(int col) const;
3117
3118
3119 /**
3120 @name Sorting support.
3121
3122 wxGrid doesn't provide any support for sorting the data but it does
3123 generate events allowing the user code to sort it and supports
3124 displaying the sort indicator in the column used for sorting.
3125
3126 To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
3127 event (and not veto it) and resort the data displayed in the grid. The
3128 grid will automatically update the sorting indicator on the column
3129 which was clicked.
3130
3131 You can also call the functions in this section directly to update the
3132 sorting indicator. Once again, they don't do anything with the grid
3133 data, it remains your responsibility to actually sort it appropriately.
3134 */
3135 //@{
3136
3137 /**
3138 Return the column in which the sorting indicator is currently
3139 displayed.
3140
3141 Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
3142 at all.
3143
3144 @see SetSortingColumn()
3145 */
3146 int GetSortingColumn() const;
3147
3148 /**
3149 Return @true if this column is currently used for sorting.
3150
3151 @see GetSortingColumn()
3152 */
3153 bool IsSortingBy(int col) const;
3154
3155 /**
3156 Return @true if the current sorting order is ascending or @false if it
3157 is descending.
3158
3159 It only makes sense to call this function if GetSortingColumn() returns
3160 a valid column index and not @c wxNOT_FOUND.
3161
3162 @see SetSortingColumn()
3163 */
3164 bool IsSortOrderAscending() const;
3165
3166 /**
3167 Set the column to display the sorting indicator in and its direction.
3168
3169 @param col
3170 The column to display the sorting indicator in or @c wxNOT_FOUND to
3171 remove any currently displayed sorting indicator.
3172 @param ascending
3173 If @true, display the ascending sort indicator, otherwise display
3174 the descending sort indicator.
3175
3176 @see GetSortingColumn(), IsSortOrderAscending()
3177 */
3178 void SetSortingColumn(int col, bool ascending = true);
3179
3180 /**
3181 Remove any currently shown sorting indicator.
3182
3183 This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
3184 first argument.
3185 */
3186 void UnsetSortingColumn();
3187 //@}
3188
3189 /**
3190 @name Accessors for component windows.
3191
3192 Return the various child windows of wxGrid.
3193
3194 wxGrid is an empty parent window for 4 children representing the column
3195 labels window (top), the row labels window (left), the corner window
3196 (top left) and the main grid window. It may be necessary to use these
3197 individual windows and not the wxGrid window itself if you need to
3198 handle events for them (this can be done using wxEvtHandler::Connect()
3199 or wxWindow::PushEventHandler()) or do something else requiring the use
3200 of the correct window pointer. Notice that you should not, however,
3201 change these windows (e.g. reposition them or draw over them) because
3202 they are managed by wxGrid itself.
3203 */
3204 //@{
3205
3206 /**
3207 Return the main grid window containing the grid cells.
3208
3209 This window is always shown.
3210 */
3211 wxWindow *GetGridWindow() const;
3212
3213 /**
3214 Return the row labels window.
3215
3216 This window is not shown if the row labels were hidden using
3217 HideRowLabels().
3218 */
3219 wxWindow *GetGridRowLabelWindow() const;
3220
3221 /**
3222 Return the column labels window.
3223
3224 This window is not shown if the columns labels were hidden using
3225 HideColLabels().
3226
3227 Depending on whether UseNativeColHeader() was called or not this can be
3228 either a wxHeaderCtrl or a plain wxWindow. This function returns a valid
3229 window pointer in either case but in the former case you can also use
3230 GetGridColHeader() to access it if you need wxHeaderCtrl-specific
3231 functionality.
3232 */
3233 wxWindow *GetGridWindow() const;
3234
3235 /**
3236 Return the window in the top left grid corner.
3237
3238 This window is shown only of both columns and row labels are shown and
3239 normally doesn't contain anything. Clicking on it is handled by wxGrid
3240 however and can be used to select the entire grid.
3241 */
3242 wxWindow *GetGridCornerLabelWindow() const;
3243
3244 /**
3245 Return the header control used for column labels display.
3246
3247 This function can only be called if UseNativeColHeader() had been
3248 called.
3249 */
3250 wxHeaderCtrl *GetGridColHeader() const;
3251
3252 //@}
3253 };
3254
3255
3256
3257 /**
3258 @class wxGridUpdateLocker
3259
3260 This small class can be used to prevent wxGrid from redrawing during its
3261 lifetime by calling wxGrid::BeginBatch() in its constructor and
3262 wxGrid::EndBatch() in its destructor. It is typically used in a function
3263 performing several operations with a grid which would otherwise result in
3264 flicker. For example:
3265
3266 @code
3267 void MyFrame::Foo()
3268 {
3269 m_grid = new wxGrid(this, ...);
3270
3271 wxGridUpdateLocker noUpdates(m_grid);
3272 m_grid-AppendColumn();
3273 // ... many other operations with m_grid ...
3274 m_grid-AppendRow();
3275
3276 // destructor called, grid refreshed
3277 }
3278 @endcode
3279
3280 Using this class is easier and safer than calling wxGrid::BeginBatch() and
3281 wxGrid::EndBatch() because you don't risk missing the call the latter (due
3282 to an exception for example).
3283
3284 @library{wxadv}
3285 @category{grid}
3286 */
3287 class wxGridUpdateLocker
3288 {
3289 public:
3290 /**
3291 Creates an object preventing the updates of the specified @a grid. The
3292 parameter could be @NULL in which case nothing is done. If @a grid is
3293 non-@NULL then the grid must exist for longer than this
3294 wxGridUpdateLocker object itself.
3295
3296 The default constructor could be followed by a call to Create() to set
3297 the grid object later.
3298 */
3299 wxGridUpdateLocker(wxGrid* grid = NULL);
3300
3301 /**
3302 Destructor reenables updates for the grid this object is associated
3303 with.
3304 */
3305 ~wxGridUpdateLocker();
3306
3307 /**
3308 This method can be called if the object had been constructed using the
3309 default constructor. It must not be called more than once.
3310 */
3311 void Create(wxGrid* grid);
3312 };
3313
3314
3315
3316 /**
3317 @class wxGridEvent
3318
3319 This event class contains information about various grid events.
3320
3321 Notice that all grid event table macros are available in two versions:
3322 @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
3323 two is that the former doesn't allow to specify the grid window identifier
3324 and so takes a single parameter, the event handler, but is not suitable if
3325 there is more than one grid control in the window where the event table is
3326 used (as it would catch the events from all the grids). The version with @c
3327 CMD takes the id as first argument and the event handler as the second one
3328 and so can be used with multiple grids as well. Otherwise there are no
3329 difference between the two and only the versions without the id are
3330 documented below for brevity.
3331
3332 @beginEventTable{wxGridEvent}
3333 @event{EVT_GRID_CELL_CHANGE(func)}
3334 The user changed the data in a cell. Processes a
3335 @c wxEVT_GRID_CELL_CHANGE event type.
3336 @event{EVT_GRID_CELL_LEFT_CLICK(func)}
3337 The user clicked a cell with the left mouse button. Processes a
3338 @c wxEVT_GRID_CELL_LEFT_CLICK event type.
3339 @event{EVT_GRID_CELL_LEFT_DCLICK(func)}
3340 The user double-clicked a cell with the left mouse button. Processes a
3341 @c wxEVT_GRID_CELL_LEFT_DCLICK event type.
3342 @event{EVT_GRID_CELL_RIGHT_CLICK(func)}
3343 The user clicked a cell with the right mouse button. Processes a
3344 @c wxEVT_GRID_CELL_RIGHT_CLICK event type.
3345 @event{EVT_GRID_CELL_RIGHT_DCLICK(func)}
3346 The user double-clicked a cell with the right mouse button. Processes a
3347 @c wxEVT_GRID_CELL_RIGHT_DCLICK event type.
3348 @event{EVT_GRID_EDITOR_HIDDEN(func)}
3349 The editor for a cell was hidden. Processes a
3350 @c wxEVT_GRID_EDITOR_HIDDEN event type.
3351 @event{EVT_GRID_EDITOR_SHOWN(func)}
3352 The editor for a cell was shown. Processes a
3353 @c wxEVT_GRID_EDITOR_SHOWN event type.
3354 @event{EVT_GRID_LABEL_LEFT_CLICK(func)}
3355 The user clicked a label with the left mouse button. Processes a
3356 @c wxEVT_GRID_LABEL_LEFT_CLICK event type.
3357 @event{EVT_GRID_LABEL_LEFT_DCLICK(func)}
3358 The user double-clicked a label with the left mouse button. Processes a
3359 @c wxEVT_GRID_LABEL_LEFT_DCLICK event type.
3360 @event{EVT_GRID_LABEL_RIGHT_CLICK(func)}
3361 The user clicked a label with the right mouse button. Processes a
3362 @c wxEVT_GRID_LABEL_RIGHT_CLICK event type.
3363 @event{EVT_GRID_LABEL_RIGHT_DCLICK(func)}
3364 The user double-clicked a label with the right mouse button. Processes
3365 a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
3366 @event{EVT_GRID_SELECT_CELL(func)}
3367 The user moved to, and selected a cell. Processes a
3368 @c wxEVT_GRID_SELECT_CELL event type.
3369 @event{EVT_GRID_COL_MOVE(func)}
3370 The user tries to change the order of the columns in the grid by
3371 dragging the column specified by GetCol(). This event can be vetoed to
3372 either prevent the user from reordering the column change completely
3373 (but notice that if you don't want to allow it at all, you simply
3374 shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
3375 but handled in some way in the handler, e.g. by really moving the
3376 column to the new position at the associated table level, or allowed to
3377 proceed in which case wxGrid::SetColPos() is used to reorder the
3378 columns display order without affecting the use of the column indices
3379 otherwise.
3380
3381 This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
3382 @event{EVT_GRID_COL_SORT(func)}
3383 This event is generated when a column is clicked by the user and its
3384 name is explained by the fact that the custom reaction to a click on a
3385 column is to sort the grid contents by this column. However the grid
3386 itself has no special support for sorting and it's up to the handler of
3387 this event to update the associated table. But if the event is handled
3388 (and not vetoed) the grid supposes that the table was indeed resorted
3389 and updates the column to indicate the new sort order and refreshes
3390 itself.
3391
3392 This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
3393 @endEventTable
3394
3395 @library{wxadv}
3396 @category{grid}
3397 */
3398 class wxGridEvent : public wxNotifyEvent
3399 {
3400 public:
3401 /**
3402 Default constructor.
3403 */
3404 wxGridEvent();
3405 /**
3406 Constructor for initializing all event attributes.
3407 */
3408 wxGridEvent(int id, wxEventType type, wxObject* obj,
3409 int row = -1, int col = -1, int x = -1, int y = -1,
3410 bool sel = true, bool control = false, bool shift = false,
3411 bool alt = false, bool meta = false);
3412
3413 /**
3414 Returns @true if the Alt key was down at the time of the event.
3415 */
3416 bool AltDown() const;
3417
3418 /**
3419 Returns @true if the Control key was down at the time of the event.
3420 */
3421 bool ControlDown() const;
3422
3423 /**
3424 Column at which the event occurred.
3425 */
3426 virtual int GetCol();
3427
3428 /**
3429 Position in pixels at which the event occurred.
3430 */
3431 wxPoint GetPosition();
3432
3433 /**
3434 Row at which the event occurred.
3435 */
3436 virtual int GetRow();
3437
3438 /**
3439 Returns @true if the Meta key was down at the time of the event.
3440 */
3441 bool MetaDown() const;
3442
3443 /**
3444 Returns @true if the user is selecting grid cells, or @false if
3445 deselecting.
3446 */
3447 bool Selecting();
3448
3449 /**
3450 Returns @true if the Shift key was down at the time of the event.
3451 */
3452 bool ShiftDown() const;
3453 };
3454
3455
3456
3457 /**
3458 @class wxGridSizeEvent
3459
3460 This event class contains information about a row/column resize event.
3461
3462 @beginEventTable{wxGridSizeEvent}
3463 @event{EVT_GRID_COL_SIZE(func)}
3464 The user resized a column by dragging it. Processes a
3465 @c wxEVT_GRID_COL_SIZE event type.
3466 @event{EVT_GRID_ROW_SIZE(func)}
3467 The user resized a row by dragging it. Processes a
3468 @c wxEVT_GRID_ROW_SIZE event type.
3469 @event{EVT_GRID_CMD_COL_SIZE(id, func)}
3470 The user resized a column by dragging it; variant taking a window
3471 identifier. Processes a @c wxEVT_GRID_COL_SIZE event type.
3472 @event{EVT_GRID_CMD_ROW_SIZE(id, func)}
3473 The user resized a row by dragging it; variant taking a window
3474 identifier. Processes a @c wxEVT_GRID_ROW_SIZE event type.
3475 @endEventTable
3476
3477 @library{wxadv}
3478 @category{grid}
3479 */
3480 class wxGridSizeEvent : public wxNotifyEvent
3481 {
3482 public:
3483 /**
3484 Default constructor.
3485 */
3486 wxGridSizeEvent();
3487 /**
3488 Constructor for initializing all event attributes.
3489 */
3490 wxGridSizeEvent(int id, wxEventType type, wxObject* obj,
3491 int rowOrCol = -1, int x = -1, int y = -1,
3492 bool control = false, bool shift = false,
3493 bool alt = false, bool meta = false);
3494
3495 /**
3496 Returns @true if the Alt key was down at the time of the event.
3497 */
3498 bool AltDown() const;
3499
3500 /**
3501 Returns @true if the Control key was down at the time of the event.
3502 */
3503 bool ControlDown() const;
3504
3505 /**
3506 Position in pixels at which the event occurred.
3507 */
3508 wxPoint GetPosition();
3509
3510 /**
3511 Row or column at that was resized.
3512 */
3513 int GetRowOrCol();
3514
3515 /**
3516 Returns @true if the Meta key was down at the time of the event.
3517 */
3518 bool MetaDown() const;
3519
3520 /**
3521 Returns @true if the Shift key was down at the time of the event.
3522 */
3523 bool ShiftDown() const;
3524 };
3525
3526
3527
3528 /**
3529 @class wxGridRangeSelectEvent
3530
3531 @beginEventTable{wxGridRangeSelectEvent}
3532 @event{EVT_GRID_RANGE_SELECT(func)}
3533 The user selected a group of contiguous cells. Processes a
3534 @c wxEVT_GRID_RANGE_SELECT event type.
3535 @event{EVT_GRID_CMD_RANGE_SELECT(id, func)}
3536 The user selected a group of contiguous cells; variant taking a window
3537 identifier. Processes a @c wxEVT_GRID_RANGE_SELECT event type.
3538 @endEventTable
3539
3540 @library{wxadv}
3541 @category{grid}
3542 */
3543 class wxGridRangeSelectEvent : public wxNotifyEvent
3544 {
3545 public:
3546 /**
3547 Default constructor.
3548 */
3549 wxGridRangeSelectEvent();
3550 /**
3551 Constructor for initializing all event attributes.
3552 */
3553 wxGridRangeSelectEvent(int id, wxEventType type,
3554 wxObject* obj,
3555 const wxGridCellCoords& topLeft,
3556 const wxGridCellCoords& bottomRight,
3557 bool sel = true, bool control = false,
3558 bool shift = false, bool alt = false,
3559 bool meta = false);
3560
3561 /**
3562 Returns @true if the Alt key was down at the time of the event.
3563 */
3564 bool AltDown() const;
3565
3566 /**
3567 Returns @true if the Control key was down at the time of the event.
3568 */
3569 bool ControlDown() const;
3570
3571 /**
3572 Top left corner of the rectangular area that was (de)selected.
3573 */
3574 wxGridCellCoords GetBottomRightCoords();
3575
3576 /**
3577 Bottom row of the rectangular area that was (de)selected.
3578 */
3579 int GetBottomRow();
3580
3581 /**
3582 Left column of the rectangular area that was (de)selected.
3583 */
3584 int GetLeftCol();
3585
3586 /**
3587 Right column of the rectangular area that was (de)selected.
3588 */
3589 int GetRightCol();
3590
3591 /**
3592 Top left corner of the rectangular area that was (de)selected.
3593 */
3594 wxGridCellCoords GetTopLeftCoords();
3595
3596 /**
3597 Top row of the rectangular area that was (de)selected.
3598 */
3599 int GetTopRow();
3600
3601 /**
3602 Returns @true if the Meta key was down at the time of the event.
3603 */
3604 bool MetaDown() const;
3605
3606 /**
3607 Returns @true if the area was selected, @false otherwise.
3608 */
3609 bool Selecting();
3610
3611 /**
3612 Returns @true if the Shift key was down at the time of the event.
3613 */
3614 bool ShiftDown() const;
3615 };
3616
3617
3618
3619 /**
3620 @class wxGridEditorCreatedEvent
3621
3622 @beginEventTable{wxGridEditorCreatedEvent}
3623 @event{EVT_GRID_EDITOR_CREATED(func)}
3624 The editor for a cell was created. Processes a
3625 @c wxEVT_GRID_EDITOR_CREATED event type.
3626 @event{EVT_GRID_CMD_EDITOR_CREATED(id, func)}
3627 The editor for a cell was created; variant taking a window identifier.
3628 Processes a @c wxEVT_GRID_EDITOR_CREATED event type.
3629 @endEventTable
3630
3631 @library{wxadv}
3632 @category{grid}
3633 */
3634 class wxGridEditorCreatedEvent : public wxCommandEvent
3635 {
3636 public:
3637 /**
3638 Default constructor.
3639 */
3640 wxGridEditorCreatedEvent();
3641 /**
3642 Constructor for initializing all event attributes.
3643 */
3644 wxGridEditorCreatedEvent(int id, wxEventType type, wxObject* obj,
3645 int row, int col, wxControl* ctrl);
3646
3647 /**
3648 Returns the column at which the event occurred.
3649 */
3650 int GetCol();
3651
3652 /**
3653 Returns the edit control.
3654 */
3655 wxControl* GetControl();
3656
3657 /**
3658 Returns the row at which the event occurred.
3659 */
3660 int GetRow();
3661
3662 /**
3663 Sets the column at which the event occurred.
3664 */
3665 void SetCol(int col);
3666
3667 /**
3668 Sets the edit control.
3669 */
3670 void SetControl(wxControl* ctrl);
3671
3672 /**
3673 Sets the row at which the event occurred.
3674 */
3675 void SetRow(int row);
3676 };
3677