Cured last focus bug (I hope); some wxMotif mods
[wxWidgets.git] / docs / latex / wx / grid.tex
CommitLineData
a660d684
KB
1\section{\class{wxGrid}}\label{wxgrid}
2
3wxGrid is a class for displaying and editing tabular information.
4
5\wxheading{Derived from}
6
7\helpref{wxPanel}{wxpanel}\\
8\helpref{wxWindow}{wxwindow}\\
9\helpref{wxEvtHandler}{wxevthandler}\\
10\helpref{wxObject}{wxobject}
11
954b8ae6
JS
12\wxheading{Include files}
13
14<wx/grid.h>
15
a660d684
KB
16\wxheading{Window styles}
17
18There are no specific window styles for this class.
19
20See also \helpref{window styles overview}{windowstyles}.
21
22\wxheading{See also}
23
24\helpref{wxGrid classes overview}{gridoverview}
25
26\latexignore{\rtfignore{\wxheading{Members}}}
27
28\membersection{wxGrid::wxGrid}\label{wxgridconstr}
29
eaaa6a06
JS
30\func{void}{wxGrid}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id}, \param{const wxPoint\&}{ pos},
31\rtfsp\param{const wxSize\&}{ size}, \param{long}{ style=0}, \param{const wxString\& }{name="grid"}}
a660d684
KB
32
33Constructor. Before using a wxGrid object, you must call CreateGrid to set up the required rows and columns.
34
35\membersection{wxGrid::AdjustScrollbars}\label{wxgridadjustscrollbars}
36
37\func{void}{AdjustScrollbars}{\void}
38
39Call this function whenever a change has been made via the API that might alter the scrollbar characteristics:
40particularly when adding or deleting rows, or changing row or column dimensions. For example,
41removing rows might make it unnecessary to show the vertical scrollbar.
42
43\membersection{wxGrid::AppendCols}\label{wxgridappendcols}
44
45\func{bool}{AppendCols}{\param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
46
47Appends {\it n} columns to the grid. If {\it updateLabels} is TRUE,
48the function OnChangeLabels is called to give the application the opportunity to relabel.
49
50\membersection{wxGrid::AppendRows}\label{wxgridappendrows}
51
52\func{bool}{AppendRows}{\param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
53
54Appends {\it n} rows to the grid. If {\it updateLabels} is TRUE,
55the function OnChangeLabels is called to give the application the opportunity to relabel.
56
57\membersection{wxGrid::BeginBatch}\label{wxgridbeginbatch}
58
59\func{void}{BeginBatch}{\void}
60
61Start a BeginBatch/EndBatch pair between which, calls to SetCellValue or
62SetCellBitmap will not cause a refresh. This allows you to speed up some operations
63(for example, setting several hundred cell values). You can nest, but not overlap,
64these two functions.
65
66See also \helpref{wxGrid::EndBatch}{wxgridendbatch}, \helpref{wxGrid::GetBatchCount}{wxgridgetbatchcount}.
67
68\membersection{wxGrid::CellHitTest}\label{wxgridcellhittest}
69
70\func{bool}{CellHitTest}{\param{int}{ x}, \param{int}{ y}, \param{int *}{row}, \param{int *}{col}}
71
72Returns TRUE if the x, y panel position coincides with a cell. If so, {\it row} and {\it col} are
73returned.
74
75\membersection{wxGrid::CreateGrid}\label{wxgridcreategrid}
76
77\func{bool}{CreateGrid}{\param{int}{ rows}, \param{int}{ cols}, \param{wxString **}{cellValues=NULL},
78 \param{short *}{widths=NULL}, \param{short}{ defaultWidth=wxGRID\_DEFAULT\_CELL\_WIDTH},
79 \param{short}{ defaultHeight=wxGRID\_DEFAULT\_CELL\_HEIGHT}}
80
81Creates a grid {\it rows} high and {\it cols} wide. You can optionally specify an array of initial values
82and widths, and/or default cell width and height.
83
84Call this function after creating the wxGrid object.
85
86\membersection{wxGrid::CurrentCellVisible}\label{wxgridcurrentcellvisible}
87
88\func{bool}{CurrentCellVisible}{\void}
89
90Returns TRUE if the currently selected cell is visible, FALSE otherwise.
91
92\membersection{wxGrid::DeleteCols}\label{wxgriddeletecols}
93
94\func{bool}{DeleteCols}{\param{int}{ pos=0}, \param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
95
96Deletes {\it n} columns from the grid at position {\it pos}. If {\it updateLabels} is TRUE,
97the function OnChangeLabels is called to give the application the opportunity to relabel.
98
99\membersection{wxGrid::DeleteRows}\label{wxgriddeleterows}
100
101\func{bool}{DeleteRows}{\param{int}{ pos=0}, \param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
102
103Deletes {\it n} rows from the grid at position {\it pos}. If {\it updateLabels} is TRUE,
104the function OnChangeLabels is called to give the application the opportunity to relabel.
105
106\membersection{wxGrid::EndBatch}\label{wxgridendbatch}
107
108\func{void}{EndBatch}{\void}
109
110End a BeginBatch/EndBatch pair between which, calls to SetCellValue or
111SetCellBitmap will not cause a refresh. This allows you to speed up some operations
112(for example, setting several hundred cell values). You can nest, but not overlap,
113these two functions.
114
115See also \helpref{wxGrid::BeginBatch}{wxgridbeginbatch}, \helpref{wxGrid::GetBatchCount}{wxgridgetbatchcount}.
116
117\membersection{wxGrid::GetBatchCount}\label{wxgridgetbatchcount}
118
c0ed460c 119\constfunc{int}{GetBatchCount}{\void}
a660d684
KB
120
121Return the level of batch nesting. This is initially zero, and will be incremented
122every time BeginBatch is called, and decremented when EndBatch is called. When the
123batch count is more zero, some functions (such as SetCellValue and SetCellBitmap) will
124not refresh the cell.
125
126See also \helpref{wxGrid::BeginBatch}{wxgridbeginbatch}, \helpref{wxGrid::EndBatch}{wxgridendbatch}.
127
128\membersection{wxGrid::GetCell}\label{wxgridgetcell}
129
c0ed460c 130\constfunc{wxGridCell *}{GetCell}{\param{int}{ row}, \param{int}{ col}}
a660d684
KB
131
132Returns the grid cell object associated with this position.
133
134wxGenericGrid implementation only.
135
136\membersection{wxGrid::GetCellAlignment}\label{wxgridgetcellalignment}
137
c0ed460c 138\constfunc{int}{GetCellAlignment}{\param{int}{ row}, \param{int}{ col}}
a660d684 139
c0ed460c 140\constfunc{int}{GetCellAlignment}{\void}
a660d684
KB
141
142Sets the text alignment for the cell at the given position, or the global alignment value.
143The return value is wxLEFT, wxRIGHT or wxCENTRE.
144
145\membersection{wxGrid::GetCellBackgroundColour}\label{wxgridgetcellbackgroundcolour}
146
c0ed460c 147\constfunc{wxColour\&}{GetCellBackgroundColour}{\param{int}{ row}, \param{int}{ col}}
a660d684 148
c0ed460c 149\constfunc{wxColour\&}{GetCellBackgroundColour}{\void}
a660d684
KB
150
151Gets the background colour for the cell at the given position, or the global background colour.
152
153\membersection{wxGrid::GetCells}\label{wxgridgetcells}
154
c0ed460c 155\constfunc{wxGridCell ***}{GetCells}{\void}
a660d684
KB
156
157Returns the array of grid cell object associated with this wxGrid.
158
159\membersection{wxGrid::GetCellTextColour}\label{wxgridgetcelltextcolour}
160
c0ed460c 161\constfunc{wxColour\&}{GetCellTextColour}{\param{int}{ row}, \param{int}{ col}}
a660d684 162
c0ed460c 163\constfunc{wxColour\&}{GetCellTextColour}{\void}
a660d684
KB
164
165Gets the text colour for the cell at the given position, or the global text colour.
166
167\membersection{wxGrid::GetCellTextFont}\label{wxgridgetcelltextfont}
168
c0ed460c 169\constfunc{const wxFont\&}{GetCellTextFont}{\param{int}{ row}, \param{int}{ col}}
a660d684 170
c0ed460c 171\constfunc{wxFont\&}{GetCellTextFont}{\void}
a660d684
KB
172
173Gets the text font for the cell at the given position, or the global text font.
174
175\membersection{wxGrid::GetCellValue}\label{wxgridgetcellvalue}
176
c0ed460c 177\constfunc{wxString\&}{GetCellValue}{\param{int}{ row}, \param{int}{ col}}
a660d684
KB
178
179Returns the cell value at the given position.
180
181\membersection{wxGrid::GetCols}\label{wxgridgetcols}
182
c0ed460c 183\constfunc{int}{GetCols}{\void}
a660d684
KB
184
185Returns the number of columns in the grid.
186
187\membersection{wxGrid::GetColumnWidth}\label{wxgridcolumnwidth}
188
c0ed460c 189\constfunc{int}{GetColumnWidth}{\param{int}{ col}}
a660d684
KB
190
191Gets the width in pixels for column {\it col}.
192
193\membersection{wxGrid::GetCurrentRect}\label{wxgridgetcurrentrect}
194
c0ed460c 195\constfunc{wxRectangle *}{GetCurrentRect}{\void}
a660d684
KB
196
197Returns a pointer to the rectangle enclosing the currently selected cell.
198Do not delete this pointer.
199
200\membersection{wxGrid::GetCursorColumn}\label{wxgridgetcursorcolumn}
201
c0ed460c 202\constfunc{int}{GetCursorColumn}{\void}
a660d684
KB
203
204Returns the column position of the currently selected cell.
205
206\membersection{wxGrid::GetCursorRow}\label{wxgridgetcursorrow}
207
c0ed460c 208\constfunc{int}{GetCursorRow}{\void}
a660d684
KB
209
210Returns the row position of the currently selected cell.
211
212\membersection{wxGrid::GetEditable}\label{wxgridgeteditable}
213
c0ed460c 214\constfunc{bool}{GetEditable}{\void}
a660d684
KB
215
216Returns TRUE if the grid cells can be edited.
217
218\membersection{wxGrid::GetHorizScrollBar}\label{wxgridgethorizscrollbar}
219
c0ed460c 220\constfunc{wxScrollBar *}{GetHorizScrollBar}{\void}
a660d684
KB
221
222Returns a pointer to the horizontal scrollbar.
223
224\membersection{wxGrid::GetLabelAlignment}\label{wxgridgetlabelalignment}
225
c0ed460c 226\constfunc{int}{GetLabelAlignment}{\param{int}{ orientation}}
a660d684
KB
227
228Gets the row or column label alignment. {\it orientation} should
229be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.\rtfsp
230{\it alignment} should be wxCENTRE, wxLEFT or wxRIGHT.
231
232\membersection{wxGrid::GetLabelBackgroundColour}\label{wxgridgetlabelbackgroundcolour}
233
c0ed460c 234\constfunc{wxColour\&}{GetLabelBackgroundColour}{\void}
a660d684
KB
235
236Gets a row and column label text colour.
237
238\membersection{wxGrid::GetLabelSize}\label{wxgridgetlabelsize}
239
c0ed460c 240\constfunc{int}{GetLabelSize}{\param{int}{ orientation}}
a660d684
KB
241
242Gets the row label height, or column label width, in pixels. {\it orientation} should
243be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.
244
245\membersection{wxGrid::GetLabelTextColour}\label{wxgridgetlabeltextcolour}
246
c0ed460c 247\constfunc{wxColour\&}{GetLabelTextColour}{\void}
a660d684
KB
248
249Gets a row and column label text colour.
250
251\membersection{wxGrid::GetLabelTextFont}\label{wxgridgetlabeltextfont}
252
c0ed460c 253\constfunc{wxFont\&}{GetLabelTextFont}{\void}
a660d684
KB
254
255Gets the font to be used for the row and column labels.
256
257\membersection{wxGrid::GetLabelValue}\label{wxgridgetlabelvalue}
258
c0ed460c 259\constfunc{wxString\&}{GetLabelValue}{\param{int}{ orientation}, \param{int}{ pos}}
a660d684
KB
260
261Gets a row or column label value. {\it orientation} should
262be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.\rtfsp
263{\it pos} is the label position.
264
265\membersection{wxGrid::GetRowHeight}\label{wxgridgetrowheight}
266
c0ed460c 267\constfunc{int}{GetRowHeight}{\param{int}{ row}}
a660d684
KB
268
269Gets the height in pixels for row {\it row}.
270
271\membersection{wxGrid::GetRows}\label{wxgridgetrows}
272
c0ed460c 273\constfunc{int}{GetRows}{\void}
a660d684
KB
274
275Returns the number of rows in the grid.
276
277\membersection{wxGrid::GetScrollPosX}\label{wxgridgetscrollposx}
278
c0ed460c 279\constfunc{int}{GetScrollPosX}{\void}
a660d684
KB
280
281Returns the column scroll position.
282
283\membersection{wxGrid::GetScrollPosY}\label{wxgridgetscrollposy}
284
c0ed460c 285\constfunc{int}{GetScrollPosY}{\void}
a660d684
KB
286
287Returns the row scroll position.
288
289\membersection{wxGrid::GetTextItem}\label{wxgridgettextitem}
290
c0ed460c 291\constfunc{wxText *}{GetTextItem}{\void}
a660d684
KB
292
293Returns a pointer to the text item used for entering text into a cell.
294
295\membersection{wxGrid::GetVertScrollBar}\label{wxgridgetvertscrollbar}
296
c0ed460c 297\constfunc{wxScrollBar *}{GetVertScrollBar}{\void}
a660d684
KB
298
299Returns a pointer to the vertical scrollbar.
300
301\membersection{wxGrid::InsertCols}\label{wxgridinsertcols}
302
303\func{bool}{InsertCols}{\param{int}{ pos=0}, \param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
304
305Inserts {\it n} number of columns before position {\it pos}. If {\it updateLabels} is TRUE,
306the function OnChangeLabels is called to give the application the opportunity to relabel.
307
308\membersection{wxGrid::InsertRows}\label{wxgridinsertrows}
309
310\func{bool}{InsertRows}{\param{int}{ pos=0}, \param{int}{ n=1}, \param{bool}{ updateLabels=TRUE}}
311
312Inserts {\it n} number of rows before position {\it pos}. If {\it updateLabels} is TRUE,
313the function OnChangeLabels is called to give the application the opportunity to relabel.
314
315\membersection{wxGrid::OnActivate}\label{wxgridonactivate}
316
317\func{void}{OnActivate}{\param{bool}{ active}}
318
319Sets the text item to have the focus. Call this function when the wxGrid window should have the
320focus, for example from wxFrame::OnActivate.
321
322\membersection{wxGrid::OnChangeLabels}\label{wxgridonchangelabels}
323
324\func{void}{OnChangeLabels}{\void}
325
326Called when rows and columns are created or deleted, to allow the application an
327opportunity to update the labels. By default, columns are labelled alphabetically,
328and rows numerically.
329
330\membersection{wxGrid::OnChangeSelectionLabel}\label{wxgridonchangeselectionlabel}
331
332\func{void}{OnChangeSelectionLabel}{\void}
333
334Called when a cell is selected, to allow the application an
335opportunity to update the selection label (the label of the wxText item
336used for entering cell text). By default, the cell column letter and row
337number are concatenated to form the selection label.
338
339\membersection{wxGrid::OnCreateCell}\label{wxgridoncreatecell}
340
341\func{wxGridCell *}{OnCreateCell}{\void}
342
343Override this virtual function if you want to replace the normal wxGridCell with a derived
344class.
345
346\membersection{wxGrid::OnCellLeftClick}\label{wxgridoncellleftclick}
347
348\func{void}{OnLeftClick}{\param{int}{ row}, \param{int}{ col}, \param{int}{ x}, \param{int}{ y}, \param{bool}{ control}, \param{bool}{ shift}}
349
350Virtual function called when the left button is depressed within a cell, just after OnSelectCell is called.
351
352\membersection{wxGrid::OnCellRightClick}\label{wxgridoncellrightclick}
353
354\func{void}{OnRightClick}{\param{int}{ row}, \param{int}{ col}, \param{int}{ x}, \param{int}{ y}, \param{bool}{ control}, \param{bool}{ shift}}
355
356Virtual function called when the right button is depressed within a cell, just after OnSelectCell is called.
357
358\membersection{wxGrid::OnLabelLeftClick}\label{wxgridonlabelleftclick}
359
360\func{void}{OnLeftClick}{\param{int}{ row}, \param{int}{ col}, \param{int}{ x}, \param{int}{ y}, \param{bool}{ control}, \param{bool}{ shift}}
361
362Virtual function called when the left button is depressed within a
363label.
364
365{\it row} will be {\it -1} if the click is in the top labels.
366
367{\it col} will be {\it -1} if the click is in the left labels.
368
369{\it row} and {\it col} will be {\it -1} if the click is in the upper
370left corner.
371
372\membersection{wxGrid::OnLabelRightClick}\label{wxgridonlabelrightclick}
373
374\func{void}{OnRightClick}{\param{int}{ row}, \param{int}{ col}, \param{int}{ x}, \param{int}{ y}, \param{bool}{ control}, \param{bool}{ shift}}
375
376Virtual function called when the right button is depressed within a label.
377
378{\it row} will be {\it -1} if the click is in the top labels.
379
380{\it col} will be {\it -1} if the click is in the left labels.
381
382{\it row} and {\it col} will be {\it -1} if the click is in the upper
383left corner.
384
385\membersection{wxGrid::OnSelectCell}\label{wxgridonselectcell}
386
387\func{void}{OnSelectCell}{\param{int}{ row}, \param{int}{ col}}
388
389Virtual function called when the user left-clicks on a cell.
390
391\membersection{wxGrid::OnSelectCellImplementation}\label{wxgridonselectcellimplementation}
392
393\func{void}{OnSelectCellImplementation}{\param{wxDC *}{dc}, \param{int}{ row}, \param{int}{ col}}
394
395Virtual function called when the user left-clicks on a cell. If you override this function,
396call wxGrid::OnSelectCell to apply the default behaviour.
397
398\membersection{wxGrid::SetCellAlignment}\label{wxgridsetcellalignment}
399
400\func{void}{SetCellAlignment}{\param{int}{ alignment}, \param{int}{ row}, \param{int}{ col}}
401
402\func{void}{SetCellAlignment}{\param{int}{ alignment}}
403
404Sets the text alignment for the cell at the given position, or for the whole grid. {\it alignment} may be wxLEFT, wxRIGHT or wxCENTRE.
405
406\membersection{wxGrid::SetCellBackgroundColour}\label{wxgridsetcellbackgroundcolour}
407
408\func{void}{SetCellBackgroundColour}{\param{const wxColour\&}{ colour}, \param{int}{ row}, \param{int}{ col}}
409
410\func{void}{SetCellBackgroundColour}{\param{const wxColour\&}{ colour}}
411
412Sets the background colour for the cell at the given position, or for the whole grid.
413
414\membersection{wxGrid::SetCellTextColour}\label{wxgridsetcelltextcolour}
415
416\func{void}{SetCellTextColour}{\param{const wxColour\&}{ colour}, \param{int}{ row}, \param{int}{ col}}
417
418\func{void}{SetCellTextColour}{\param{const wxColour\&}{ colour}}
419
420Sets the text colour for the cell at the given position, or for the whole grid.
421
422\membersection{wxGrid::SetCellTextFont}\label{wxgridsetcelltextfont}
423
c0ed460c 424\func{void}{SetCellTextFont}{\param{const wxFont\&}{ font}, \param{int}{ row}, \param{int}{ col}}
a660d684 425
c0ed460c 426\func{void}{SetCellTextFont}{\param{const wxFont\&}{ font}}
a660d684
KB
427
428Sets the text font for the cell at the given position, or for the whole grid.
429
430\membersection{wxGrid::SetCellValue}\label{wxgridsetcellvalue}
431
432\func{void}{SetCellValue}{\param{const wxString\&}{ val}, \param{int}{ row}, \param{int}{ col}}
433
434Sets the cell value at the given position.
435
436\membersection{wxGrid::SetColumnWidth}\label{wxgridsetcolumnwidth}
437
438\func{void}{SetColumnWidth}{\param{int}{ col}, \param{int}{ width}}
439
440Sets the width in pixels for column {\it col}.
441
442\membersection{wxGrid::SetDividerPen}\label{wxgridsetdividerpen}
443
c0ed460c 444\func{void}{SetDividerPen}{\param{const wxPen\&}{ pen}}
a660d684
KB
445
446Specifies the pen to be used for drawing the divisions between cells. The default
447is a light grey. If NULL is specified, the divisions will not be drawn.
448
449\membersection{wxGrid::SetEditable}\label{wxgridseteditable}
450
451\func{void}{SetEditable}{\param{bool}{ editable}}
452
453If {\it editable} is TRUE (the default), the grid cells will be editable by means of the
454text edit control. If FALSE, the text edit control will be hidden and the user will not
455be able to edit the cell contents.
456
457\membersection{wxGrid::SetGridCursor}\label{wxgridsetgridcursor}
458
459\func{void}{SetGridCursor}{\param{int }{row}, \param{int}{ col}}
460
461Sets the position of the selected cell.
462
463\membersection{wxGrid::SetLabelAlignment}\label{wxgridsetlabelalignment}
464
465\func{void}{SetLabelAlignment}{\param{int}{ orientation}, \param{int}{ alignment}}
466
467Sets the row or column label alignment. {\it orientation} should
468be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.\rtfsp
469{\it alignment} should be wxCENTRE, wxLEFT or wxRIGHT.
470
471\membersection{wxGrid::SetLabelBackgroundColour}\label{wxgridsetlabelbackgroundcolour}
472
473\func{void}{SetLabelBackgroundColour}{\param{const wxColour\&}{ value}}
474
475Sets a row or column label background colour.
476
477\membersection{wxGrid::SetLabelSize}\label{wxgridsetlabelsize}
478
479\func{void}{SetLabelSize}{\param{int}{ orientation}, \param{int}{ size}}
480
481Sets the row label height, or column label width, in pixels. {\it orientation} should
482be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.
483
484If a dimension of zero is specified, the row or column labels will not be
485shown.
486
487\membersection{wxGrid::SetLabelTextColour}\label{wxgridsetlabeltextcolour}
488
489\func{void}{SetLabelTextColour}{\param{const wxColour\&}{ value}}
490
491Sets a row and column label text colour.
492
493\membersection{wxGrid::SetLabelTextFont}\label{wxgridsetlabeltextfont}
494
c0ed460c 495\func{void}{SetLabelTextFont}{\param{const wxFont\&}{ font}}
a660d684
KB
496
497Sets the font to be used for the row and column labels.
498
499\membersection{wxGrid::SetLabelValue}\label{wxgridsetlabelvalue}
500
501\func{void}{SetLabelValue}{\param{int}{ orientation}, \param{const wxString\&}{ value}, \param{int}{ pos}}
502
503Sets a row or column label value. {\it orientation} should
504be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.\rtfsp
505{\it pos} is the label position.
506
507\membersection{wxGrid::SetRowHeight}\label{wxgridsetrowheight}
508
509\func{void}{SetRowHeight}{\param{int}{ row}, \param{int}{ height}}
510
511Sets the height in pixels for row {\it row}.
512
513\membersection{wxGrid::UpdateDimensions}\label{wxgridupdatedimensions}
514
515\func{void}{UpdateDimensions}{\void}
516
517Call this function whenever a change has been made via the API that
518might alter size characteristics. You may also need to follow it with
519a call to AdjustScrollbars.
520
521