]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/grid.h
Check wxDateTime components validity more rigorously.
[wxWidgets.git] / docs / doxygen / overviews / grid.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: grid.h
3 // Purpose: topic overview
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10
11 @page overview_grid wxGrid Overview
12
13 Classes: wxGrid
14
15 @li @ref overview_grid_intro
16 @li @ref overview_grid_simpleexample
17 @li @ref overview_grid_complexexample
18 @li @ref overview_grid_classrelations
19 @li @ref overview_grid_keyboardmouse
20
21
22 <hr>
23
24
25 @section overview_grid_intro Introduction
26
27 wxGrid and its related classes are used for displaying and editing tabular
28 data. wxGrid supports custom attributes for the table cells, allowing to
29 completely customize its appearance and uses a separate grid table
30 (wxGridTableBase-derived) class for the data management meaning that it
31 can be used to display arbitrary amounts of data.
32
33 @section overview_grid_simpleexample Getting started: a simple example
34
35 For simple applications you need only refer to the wxGrid class in your
36 code. This example shows how you might create a grid in a frame or
37 dialog constructor and illustrates some of the formatting functions.
38
39 @code
40 // Create a wxGrid object
41
42 grid = new wxGrid( this,
43 -1,
44 wxPoint( 0, 0 ),
45 wxSize( 400, 300 ) );
46
47 // Then we call CreateGrid to set the dimensions of the grid
48 // (100 rows and 10 columns in this example)
49 grid->CreateGrid( 100, 10 );
50
51 // We can set the sizes of individual rows and columns
52 // in pixels
53 grid->SetRowSize( 0, 60 );
54 grid->SetColSize( 0, 120 );
55
56 // And set grid cell contents as strings
57 grid->SetCellValue( 0, 0, "wxGrid is good" );
58
59 // We can specify that some cells are read->only
60 grid->SetCellValue( 0, 3, "This is read->only" );
61 grid->SetReadOnly( 0, 3 );
62
63 // Colours can be specified for grid cell contents
64 grid->SetCellValue(3, 3, "green on grey");
65 grid->SetCellTextColour(3, 3, *wxGREEN);
66 grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY);
67
68 // We can specify the some cells will store numeric
69 // values rather than strings. Here we set grid column 5
70 // to hold floating point values displayed with width of 6
71 // and precision of 2
72 grid->SetColFormatFloat(5, 6, 2);
73 grid->SetCellValue(0, 6, "3.1415");
74 @endcode
75
76 Here is a list of classes related to wxGrid:
77
78 @li wxGrid: The main grid control class itself.
79 @li wxGridTableBase: The base class for grid data provider.
80 @li wxGridStringTable: Simple wxGridTableBase implementation supporting only
81 string data items and storing them all in memory (hence suitable for not
82 too large grids only).
83 @li wxGridCellAttr: A cell attribute, allowing to customize its appearance as
84 well as the renderer and editor used for displaying and editing it.
85 @li wxGridCellAttrProvider: The object responsible for storing and retrieving
86 the cell attributes.
87 @li wxGridColLabelWindow: The window showing the grid columns labels.
88 @li wxGridRowLabelWindow: The window showing the grid rows labels.
89 @li wxGridCornerLabelWindow: The window used in the upper left grid corner.
90 @li wxGridWindow: The window representing the main part of the grid.
91 @li wxGridCellRenderer: Base class for objects used to display a cell value.
92 @li wxGridCellStringRenderer: Renderer showing the cell as a text string.
93 @li wxGridCellNumberRenderer: Renderer showing the cell as an integer number.
94 @li wxGridCellFloatRenderer: Renderer showing the cell as a floating point
95 number.
96 @li wxGridCellBoolRenderer: Renderer showing the cell as checked or unchecked
97 box.
98 @li wxGridCellEditor: Base class for objects used to edit the cell value.
99 @li wxGridCellStringEditor: Editor for cells containing text strings.
100 @li wxGridCellNumberEditor: Editor for cells containing integer numbers.
101 @li wxGridCellFloatEditor: Editor for cells containing floating point numbers.
102 @li wxGridCellBoolEditor: Editor for boolean-valued cells.
103 @li wxGridCellChoiceEditor: Editor allowing to choose one of the predefined
104 strings (and possibly enter new one).
105 @li wxGridEvent: The event sent by most of wxGrid actions.
106 @li wxGridSizeEvent: The special event sent when a grid column or row is
107 resized.
108 @li wxGridRangeSelectEvent: The special event sent when a range of cells is
109 selected in the grid.
110 @li wxGridEditorCreatedEvent: The special event sent when a cell editor is
111 created.
112 @li wxGridSelection: The object efficiently representing the grid selection.
113 @li wxGridTypeRegistry: Contains information about the data types supported by
114 the grid.
115
116 @section overview_grid_complexexample A more complex example
117
118 @todo To be written
119
120
121 @section overview_grid_classrelations How the wxGrid classes relate to each other
122
123 @todo To be written
124
125
126 @section overview_grid_keyboardmouse Keyboard and mouse actions
127
128 @todo To be written
129
130 @section overview_grid_resizing Column and row sizes
131
132 @b NB: This section will discuss the resizing of wxGrid rows only to avoid
133 repetitions but everything in it also applies to grid columns, just replace @c
134 Row in the method names with @c Col.
135
136 Initially all wxGrid rows have the same height, which can be modified for all
137 of them at once using wxGrid::SetDefaultRowSize(). However, unlike simpler
138 controls such as wxListBox or wxListCtrl, wxGrid also allows its rows to be
139 individually resized to have their own height using wxGrid::SetRowSize() (as a
140 special case, a row may be hidden entirely by setting its size to 0, which is
141 done by a helper wxGrid::HideRow() method). It is also possible to resize a row
142 to fit its contents with wxGrid::AutoSizeRow() or do it for all rows at once
143 with wxGrid::AutoSizeRows().
144
145 Additionally, by default the user can also drag the row separator lines to
146 resize the rows interactively. This can be forbidden completely by calling
147 wxGrid::DisableDragRowSize() or just for the individual rows using
148 wxGrid::DisableRowResize().
149
150 If you do allow the user to resize the grid rows, it may be a good idea to save
151 their heights and restore it when the grid is recreated the next time (possibly
152 during a next program execution): the functions wxGrid::GetRowSizes() and
153 wxGrid::SetRowSizes() can help with this, you will just need to serialize
154 wxGridSizesInfo structure returned by the former in some way and deserialize it
155 back before calling the latter.
156
157 */