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