docs/latex/wx/grid.tex

   1 \section{\class{wxGrid}}\label{wxgrid}
   2
   3 wxGrid 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
  12 \wxheading{Include files}
  13
  14 <wx/grid.h>
  15
  16 \wxheading{Window styles}
  17
  18 There are no specific window styles for this class.
  19
  20 See 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
  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"}}
  32
  33 Constructor. 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
  39 Call this function whenever a change has been made via the API that might alter the scrollbar characteristics:
  40 particularly when adding or deleting rows, or changing row or column dimensions. For example,
  41 removing 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
  47 Appends {\it n} columns to the grid. If {\it updateLabels} is TRUE,
  48 the 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
  54 Appends {\it n} rows to the grid. If {\it updateLabels} is TRUE,
  55 the 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
  61 Start a BeginBatch/EndBatch pair between which, calls to SetCellValue or
  62 SetCellBitmap 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,
  64 these two functions.
  65
  66 See 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
  72 Returns TRUE if the x, y panel position coincides with a cell. If so, {\it row} and {\it col} are
  73 returned.
  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
  81 Creates a grid {\it rows} high and {\it cols} wide. You can optionally specify an array of initial values
  82 and widths, and/or default cell width and height.
  83
  84 Call this function after creating the wxGrid object.
  85
  86 \membersection{wxGrid::CurrentCellVisible}\label{wxgridcurrentcellvisible}
  87
  88 \func{bool}{CurrentCellVisible}{\void}
  89
  90 Returns 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
  96 Deletes {\it n} columns from the grid at position {\it pos}. If {\it updateLabels} is TRUE,
  97 the 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
 103 Deletes {\it n} rows from the grid at position {\it pos}. If {\it updateLabels} is TRUE,
 104 the 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
 110 End a BeginBatch/EndBatch pair between which, calls to SetCellValue or
 111 SetCellBitmap 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,
 113 these two functions.
 114
 115 See also \helpref{wxGrid::BeginBatch}{wxgridbeginbatch}, \helpref{wxGrid::GetBatchCount}{wxgridgetbatchcount}.
 116
 117 \membersection{wxGrid::GetBatchCount}\label{wxgridgetbatchcount}
 118
 119 \constfunc{int}{GetBatchCount}{\void}
 120
 121 Return the level of batch nesting. This is initially zero, and will be incremented
 122 every time BeginBatch is called, and decremented when EndBatch is called. When the
 123 batch count is more zero, some functions (such as SetCellValue and SetCellBitmap) will
 124 not refresh the cell.
 125
 126 See also \helpref{wxGrid::BeginBatch}{wxgridbeginbatch}, \helpref{wxGrid::EndBatch}{wxgridendbatch}.
 127
 128 \membersection{wxGrid::GetCell}\label{wxgridgetcell}
 129
 130 \constfunc{wxGridCell *}{GetCell}{\param{int}{ row}, \param{int}{ col}}
 131
 132 Returns the grid cell object associated with this position.
 133
 134 wxGenericGrid implementation only.
 135
 136 \membersection{wxGrid::GetCellAlignment}\label{wxgridgetcellalignment}
 137
 138 \constfunc{int}{GetCellAlignment}{\param{int}{ row}, \param{int}{ col}}
 139
 140 \constfunc{int}{GetCellAlignment}{\void}
 141
 142 Sets the text alignment for the cell at the given position, or the global alignment value.
 143 The return value is wxLEFT, wxRIGHT or wxCENTRE.
 144
 145 \membersection{wxGrid::GetCellBackgroundColour}\label{wxgridgetcellbackgroundcolour}
 146
 147 \constfunc{wxColour\&}{GetCellBackgroundColour}{\param{int}{ row}, \param{int}{ col}}
 148
 149 \constfunc{wxColour\&}{GetCellBackgroundColour}{\void}
 150
 151 Gets the background colour for the cell at the given position, or the global background colour.
 152
 153 \membersection{wxGrid::GetCells}\label{wxgridgetcells}
 154
 155 \constfunc{wxGridCell ***}{GetCells}{\void}
 156
 157 Returns the array of grid cell object associated with this wxGrid.
 158
 159 \membersection{wxGrid::GetCellTextColour}\label{wxgridgetcelltextcolour}
 160
 161 \constfunc{wxColour\&}{GetCellTextColour}{\param{int}{ row}, \param{int}{ col}}
 162
 163 \constfunc{wxColour\&}{GetCellTextColour}{\void}
 164
 165 Gets the text colour for the cell at the given position, or the global text colour.
 166
 167 \membersection{wxGrid::GetCellTextFont}\label{wxgridgetcelltextfont}
 168
 169 \constfunc{const wxFont\&}{GetCellTextFont}{\param{int}{ row}, \param{int}{ col}}
 170
 171 \constfunc{wxFont\&}{GetCellTextFont}{\void}
 172
 173 Gets the text font for the cell at the given position, or the global text font.
 174
 175 \membersection{wxGrid::GetCellValue}\label{wxgridgetcellvalue}
 176
 177 \constfunc{wxString\&}{GetCellValue}{\param{int}{ row}, \param{int}{ col}}
 178
 179 Returns the cell value at the given position.
 180
 181 \membersection{wxGrid::GetCols}\label{wxgridgetcols}
 182
 183 \constfunc{int}{GetCols}{\void}
 184
 185 Returns the number of columns in the grid.
 186
 187 \membersection{wxGrid::GetColumnWidth}\label{wxgridcolumnwidth}
 188
 189 \constfunc{int}{GetColumnWidth}{\param{int}{ col}}
 190
 191 Gets the width in pixels for column {\it col}.
 192
 193 \membersection{wxGrid::GetCurrentRect}\label{wxgridgetcurrentrect}
 194
 195 \constfunc{wxRectangle *}{GetCurrentRect}{\void}
 196
 197 Returns a pointer to the rectangle enclosing the currently selected cell.
 198 Do not delete this pointer.
 199
 200 \membersection{wxGrid::GetCursorColumn}\label{wxgridgetcursorcolumn}
 201
 202 \constfunc{int}{GetCursorColumn}{\void}
 203
 204 Returns the column position of the currently selected cell.
 205
 206 \membersection{wxGrid::GetCursorRow}\label{wxgridgetcursorrow}
 207
 208 \constfunc{int}{GetCursorRow}{\void}
 209
 210 Returns the row position of the currently selected cell.
 211
 212 \membersection{wxGrid::GetEditable}\label{wxgridgeteditable}
 213
 214 \constfunc{bool}{GetEditable}{\void}
 215
 216 Returns TRUE if the grid cells can be edited.
 217
 218 \membersection{wxGrid::GetHorizScrollBar}\label{wxgridgethorizscrollbar}
 219
 220 \constfunc{wxScrollBar *}{GetHorizScrollBar}{\void}
 221
 222 Returns a pointer to the horizontal scrollbar.
 223
 224 \membersection{wxGrid::GetLabelAlignment}\label{wxgridgetlabelalignment}
 225
 226 \constfunc{int}{GetLabelAlignment}{\param{int}{ orientation}}
 227
 228 Gets the row or column label alignment. {\it orientation} should
 229 be 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
 234 \constfunc{wxColour\&}{GetLabelBackgroundColour}{\void}
 235
 236 Gets a row and column label text colour.
 237
 238 \membersection{wxGrid::GetLabelSize}\label{wxgridgetlabelsize}
 239
 240 \constfunc{int}{GetLabelSize}{\param{int}{ orientation}}
 241
 242 Gets the row label height, or column label width, in pixels. {\it orientation} should
 243 be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.
 244
 245 \membersection{wxGrid::GetLabelTextColour}\label{wxgridgetlabeltextcolour}
 246
 247 \constfunc{wxColour\&}{GetLabelTextColour}{\void}
 248
 249 Gets a row and column label text colour.
 250
 251 \membersection{wxGrid::GetLabelTextFont}\label{wxgridgetlabeltextfont}
 252
 253 \constfunc{wxFont\&}{GetLabelTextFont}{\void}
 254
 255 Gets the font to be used for the row and column labels.
 256
 257 \membersection{wxGrid::GetLabelValue}\label{wxgridgetlabelvalue}
 258
 259 \constfunc{wxString\&}{GetLabelValue}{\param{int}{ orientation}, \param{int}{ pos}}
 260
 261 Gets a row or column label value. {\it orientation} should
 262 be 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
 267 \constfunc{int}{GetRowHeight}{\param{int}{ row}}
 268
 269 Gets the height in pixels for row {\it row}.
 270
 271 \membersection{wxGrid::GetRows}\label{wxgridgetrows}
 272
 273 \constfunc{int}{GetRows}{\void}
 274
 275 Returns the number of rows in the grid.
 276
 277 \membersection{wxGrid::GetScrollPosX}\label{wxgridgetscrollposx}
 278
 279 \constfunc{int}{GetScrollPosX}{\void}
 280
 281 Returns the column scroll position.
 282
 283 \membersection{wxGrid::GetScrollPosY}\label{wxgridgetscrollposy}
 284
 285 \constfunc{int}{GetScrollPosY}{\void}
 286
 287 Returns the row scroll position.
 288
 289 \membersection{wxGrid::GetTextItem}\label{wxgridgettextitem}
 290
 291 \constfunc{wxText *}{GetTextItem}{\void}
 292
 293 Returns a pointer to the text item used for entering text into a cell.
 294
 295 \membersection{wxGrid::GetVertScrollBar}\label{wxgridgetvertscrollbar}
 296
 297 \constfunc{wxScrollBar *}{GetVertScrollBar}{\void}
 298
 299 Returns 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
 305 Inserts {\it n} number of columns before position {\it pos}. If {\it updateLabels} is TRUE,
 306 the 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
 312 Inserts {\it n} number of rows before position {\it pos}. If {\it updateLabels} is TRUE,
 313 the 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
 319 Sets the text item to have the focus. Call this function when the wxGrid window should have the
 320 focus, for example from wxFrame::OnActivate.
 321
 322 \membersection{wxGrid::OnChangeLabels}\label{wxgridonchangelabels}
 323
 324 \func{void}{OnChangeLabels}{\void}
 325
 326 Called when rows and columns are created or deleted, to allow the application an
 327 opportunity to update the labels. By default, columns are labelled alphabetically,
 328 and rows numerically.
 329
 330 \membersection{wxGrid::OnChangeSelectionLabel}\label{wxgridonchangeselectionlabel}
 331
 332 \func{void}{OnChangeSelectionLabel}{\void}
 333
 334 Called when a cell is selected, to allow the application an
 335 opportunity to update the selection label (the label of the wxText item
 336 used for entering cell text). By default, the cell column letter and row
 337 number are concatenated to form the selection label.
 338
 339 \membersection{wxGrid::OnCreateCell}\label{wxgridoncreatecell}
 340
 341 \func{wxGridCell *}{OnCreateCell}{\void}
 342
 343 Override this virtual function if you want to replace the normal wxGridCell with a derived
 344 class.
 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
 350 Virtual 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
 356 Virtual 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
 362 Virtual function called when the left button is depressed within a
 363 label.
 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
 370 left 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
 376 Virtual 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
 383 left corner.
 384
 385 \membersection{wxGrid::OnSelectCell}\label{wxgridonselectcell}
 386
 387 \func{void}{OnSelectCell}{\param{int}{ row}, \param{int}{ col}}
 388
 389 Virtual 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
 395 Virtual function called when the user left-clicks on a cell. If you override this function,
 396 call 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
 404 Sets 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
 412 Sets 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
 420 Sets the text colour for the cell at the given position, or for the whole grid.
 421
 422 \membersection{wxGrid::SetCellTextFont}\label{wxgridsetcelltextfont}
 423
 424 \func{void}{SetCellTextFont}{\param{const wxFont\&}{ font}, \param{int}{ row}, \param{int}{ col}}
 425
 426 \func{void}{SetCellTextFont}{\param{const wxFont\&}{ font}}
 427
 428 Sets 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
 434 Sets 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
 440 Sets the width in pixels for column {\it col}.
 441
 442 \membersection{wxGrid::SetDividerPen}\label{wxgridsetdividerpen}
 443
 444 \func{void}{SetDividerPen}{\param{const wxPen\&}{ pen}}
 445
 446 Specifies the pen to be used for drawing the divisions between cells. The default
 447 is 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
 453 If {\it editable} is TRUE (the default), the grid cells will be editable by means of the
 454 text edit control. If FALSE, the text edit control will be hidden and the user will not
 455 be 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
 461 Sets 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
 467 Sets the row or column label alignment. {\it orientation} should
 468 be 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
 475 Sets 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
 481 Sets the row label height, or column label width, in pixels. {\it orientation} should
 482 be wxHORIZONTAL to specify column label, wxVERTICAL to specify row label.
 483
 484 If a dimension of zero is specified, the row or column labels will not be
 485 shown.
 486
 487 \membersection{wxGrid::SetLabelTextColour}\label{wxgridsetlabeltextcolour}
 488
 489 \func{void}{SetLabelTextColour}{\param{const wxColour\&}{ value}}
 490
 491 Sets a row and column label text colour.
 492
 493 \membersection{wxGrid::SetLabelTextFont}\label{wxgridsetlabeltextfont}
 494
 495 \func{void}{SetLabelTextFont}{\param{const wxFont\&}{ font}}
 496
 497 Sets 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
 503 Sets a row or column label value. {\it orientation} should
 504 be 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
 511 Sets the height in pixels for row {\it row}.
 512
 513 \membersection{wxGrid::UpdateDimensions}\label{wxgridupdatedimensions}
 514
 515 \func{void}{UpdateDimensions}{\void}
 516
 517 Call this function whenever a change has been made via the API that
 518 might alter size characteristics. You may also need to follow it with
 519 a call to AdjustScrollbars.
 520
 521