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