Skip to content
This repository has been archived by the owner on Dec 28, 2021. It is now read-only.

3. Getting Started

Jump to bottom
Yeray edited this page Feb 15, 2019 · 9 revisions

Using TeeGrid

TeeGrid is "data-agnostic"

The "DataSource" property can be used with DataSets and other types of datasource including arrays and flat files.

Custom Data can also be set to TeeGrid using a data provider class, manually created by code.

TeeGrid has no dependencies on database units or any Dataset component. This enables the linking of a TeeGrid to any kind of data, like a Dataset, arrays of objects or records or a generic Lists, Collections, Strings, or other sources, including your own custom "virtual data" class.

Several classes are already provided to bind data to TeeGrid, like:

  • VirtualModeData
  • VirtualData
  • VirtualDBData
  • StringData

Examples:

// From a Bindingsource or System.Data.DataSet:
bindingCustomers.DataSource = this.fddemoDataSet.Customers.Take(50);
teeGrid1.DataSource = bindingCustomers;

// From a DataSource creating a class, here in a row expander:
private void GetOrders(object sender, ExpanderGetDataEventArgs e)
{
	DataRow row = this.fddemoDataSet.Customers.Rows[e.Row];
	string id = row["CustomerID"].ToString();

	VirtualDBData data = new VirtualDBData();
	e.Data = data.From(fddemoDataSet.Orders.Where(x => x.CustomerID == id));
}

// From an array of records or classes:
int[] myIntegers = new int[100];
... fill array...
teeGrid1.Data = new VirtualArrayData<int>(myIntegers);

TeeGrid can be used like a StringGrid:

StringsData tmp = new StringsData(2, 11);

teeGrid1.Data = tmp;

teeGrid1.Columns[0].Header.Text = "ABC" + Environment.NewLine + "Extra Content";
teeGrid1.Columns[1].Header.Text = "DEF" + Environment.NewLine + "Subtext";

tmp[0, 3] = "Sample";
tmp[0, 5] = "Hello" + Environment.NewLine + "World";

...more fill lines...

Current Features

  • Huge data

TeeGrid is capable of handling a very large number of cells. For example 1 billion cells ( 1000 columns by 1 million rows ).

The only limit is the memory used by your own data.

  • Virtual data mode

VirtualModeData class to automatically create columns and provide cell values using OnGet and OnSet events.

  • Sub-columns (any column can have children columns)
teeGrid1.Columns.Add("column1").Items.Add("subcolumn1");
  • Per-column formatting (font, back fill, stroke, text alignment, margins)
TeeGrid1.Columns[3].ParentFormat = false;
TeeGrid1.Columns[3].Format.Font.Size = 14;

teeGrid1.Columns[3].TextAlignment = Steema.TeeGrid.Columns.ColumnTextAlign.Custom;
teeGrid1.Columns[3].TextAlign.Horizontal = Steema.TeeGrid.Painter.HorizontalAlign.Center;
  • Per-cell custom paint using the column OnPaint event

  • Lock columns to left or right grid edges
teeGrid1.Columns[3].Locked = Steema.TeeGrid.Columns.ColumnLocked.Right;

  • Individual row heights (per-row custom height)
teeGrid1.Rows.Heights[3] = 50;;
  • Automatic multi-line text in cells
teeGrid1.Rows.Height.Automatic = true;  // <-- every row can be of different height

  • Custom rows height (same height for all rows)
teeGrid1.Rows.Height.Automatic = false;
teeGrid1.Rows.Height.Value = 0;
  • Row groups

Any row can be expanded to show a detail sub-grid (recursive grids-in-grids) The grid Data class must support master-detail relationships.

For example:

  • Totals and SubTotals

Automatic summary "grid bands" can be added to any grid header or footer, and also to "detail" subgrids.

ColumnTotals tmp = Totals(teeGrid1.Footer);
tmp.Calculation.Add("Quantity", ColumnCalculation.Sum);

// Add also another band with header names for the totals band:
TotalsHeader.CreateTotals(teeGrid1.Footer, tmp);
  • Row "Sub-Bands"

Any row might display a grid band above that row. The "band" can be anything, from a simple TTextBand to a complex group of bands or rows.

Steema.TeeGrid.Bands.TextBand title = new Steema.TeeGrid.Bands.TextBand(teeGrid1.Rows.SubBands);
title.Text = "my rows";

teeGrid1.Rows.SubBands[23] = title;  // <-- only for row 23

  • Custom cell rendering

The default class for cell rendering is CellRender. Other classes can be used or created to override the default behaviour, like for example the BooleanRender class to show check-boxes in columns that have boolean (true/false) values:

teeGrid1.Columns[7].Render = new BooleanRender();
  • Cell text custom formatting (float, date-time formatting strings)
teeGrid1.Columns[0].DataFormat.Float = "0.###";  // also Date, Time, DateTime formats
  • Automatic display of Bitmap and Picture data

Cells are filled with pictures when columns data is for example a TDataSet TField Blob type

  • Column Visible and Expanded (for sub-columns)
teeGrid1.Columns[0].Visible = false; 
teeGrid1.Columns[0].Items[3].Expanded = false; // visible, but collapsed

teeGrid1.Columns[3].Hide(); // <-- same as Visible:= False
  • Column Selectable (enable or disable focusing cells of that column)
teeGrid1.Columns[1].Selectable = false;
  • Automatic column width

Column width is automatically adjusted by default. It can also be set to a custom fixed value, in pixels or as % percent of total grid width.

teeGrid1.Columns[0].Width.Automatic = false; 
teeGrid1.Columns[0].Width.Value = 40; 
teeGrid1.Columns[0].Width.Units = Steema.TeeGrid.Format.SizeUnits.Percent;  // or Pixels
  • Column mouse drag resizing

Dragging the left mouse button in a column header edge resizes it

  • Automatic scroll bars visibility

Scrollbars are automatically displayed when necessary, or they can be forced visible or hidden.

teeGrid1.ScrollBars.Vertical.Width = 50;
teeGrid1.ScrollBars.Horizontal.Visible = ScrollBarVisible.Hide; // <-- Automatic, Show or Hide
  • Column ordering

Columns and sub-columns can be re-positioned:

teeGrid1.Columns[2].Index = 0;  // move 2nd column to first (left-most) position
  • Column dragging

Column headers can be mouse-dragged to move or re-order them to new positions

  • Grid Header formatting (font, back fill, stroke, margins, text alignment)
teeGrid1.Columns[0].Header.Text = "My Column";
teeGrid1.Columns[0].Header.Format.Font.Color = Color.Red;

  • Grid Header mouse-hover
teeGrid1.Header.Hover.Visible = true;
teeGrid1.Header.Hover.Format.Brush.Color = Color.Green;
  • Grid "indicator" column (left-most column with symbol for current row)
teeGrid1.Indicator.Visible = true; // <-- set to False to hide indicator
teeGrid1.Indicator.Width = 20;
  • Row highlighting (mouse-hover and selected row formatting)

Cells can be selected by mouse clicking them or using the arrow, enter and tab keys to navigate among them.

Selecting by mouse happens at mouse down or mouse up depending on grid scrolling and range selection, see below.

// selecting a single cell
teeGrid1.Selected.Column = teeGrid1.Columns[3];
teeGrid1.Selected.Row = 5;
  
// formatting of selected cells
teeGrid1.Selected.ParentFont = false;
teeGrid1.Selected.Format.Font.Style = Steema.TeeGrid.Format.FontStyle.Bold;
  • Unfocused selected format

Selected cells can be displayed using different formatting settings when the grid is not the focused control

teeGrid1.Selected.UnFocused.Format.Brush.Color = Color.Red;
  • Multi-cell range selection (by mouse and/or arrow keys, or by code)
// range selection
teeGrid1.Selected.Range.Enabled = true; // <-- It is disabled by default

teeGrid1.Selected.Range.FromColumn = teeGrid1.Columns[3];
teeGrid1.Selected.Range.ToColumn = teeGrid1.Columns[6];

teeGrid1.Selected.Range.FromRow = 10;
teeGrid1.Selected.Range.ToRow = 15;

  • Automatic grid scrolling when selecting cells

Grid can be automatically scrolled when selecting cells so the selected cell is always visible

teeGrid1.Selected.ScrollToView = true; // default is False
  • Grid scrolling

Horizontal and / or vertical scrolling can be performed using the grid scrollbars or arrow keys, and also optionally dragging the grid using the mouse left button or panning via finger touch for touch devices.

Note: Cell range selection is disabled when mouse or touch scrolling is enabled

teeGrid1.Scrolling.Mode = Steema.TeeGrid.RowGroup.ScrollingMode.Touch; // or Mouse, Both, None
teeGrid1.Scrolling.HorizontalteeGrid1.Scrolling.Horizontal = Steema.TeeGrid.RowGroup.ScrollDirection.Normal; // or Inverted, Disabled
  • Copy selected cells to clipboard in CSV format, pressing Ctrl+C or Ctrl+Insert key and also by code:
// The second parameter can be omitted to use all cells in the grid
Clipboard.SetText(Steema.TeeGrid.CSV.CSVData.From(teeGrid1.Grid, teeGrid1.Selected));
  • Full selected row highlight
teeGrid1.Selected.fullRow= True;
  • Grid and Columns ReadOnly

Note: If grid data is readonly (for example a DataSet), it cannot be overridden

teeGrid1.ReadOnly = false;
teeGrid1.Columns[0].ReadOnly = true;
  • Grid Editing properties

Several properties control grid cell editing features.

Selected cells can be edited by pressing the F2 key or by other means.

teeGrid1.Editing.AutoEdit = true; // start editing cells when typing any letter or number

teeGrid1.Editing.AlwaysVisible = true; // keep cell editor active when moving to other cells

teeGrid1.Editing.DoubleClick = true; // start editing cells when double-clicking them

teeGrid1.Editing.EnterKey = Steema.TeeGrid.EditingEnter.NextCell; // move to other cells when finishing editing them pressing the Enter key

teeGrid1.Editing.Text.Selected = true; // select all cell text when starting editing it
  • Rows and Columns lines separators (stroke settings)
// row line dividers
teeGrid1.Rows.RowLines.Visible = true;
teeGrid1.Rows.RowLines.Size:= 3;
teeGrid1.Rows.RowLines.Color:= TAlphaColors.Skyblue;

// column line dividers
teeGrid1.Rows.Lines.Visible:= False;
teeGrid1.Rows.Lines.Size:= 2;
  • Cell mouse-hover (highlights cell under mouse cursor)

The Cell (or all cells in a row) under the mouse cursor can be highlighted:

teeGrid1.Cells.Hover.Visible = true;
teeGrid1.Cells.Hover.FullRow = true;
teeGrid1.Cells.Hover.Format.Stroke.Size = 2;
  • All coordinates as floats

For sub-pixel finetuning.

Note: For VCL, using the old "GDI" canvas always rounds to integer pixels

teeGrid1.Header.Height.Automatic = false;
teeGrid1.Header.Height.Value = 124.3F;   // sub-pixels, decimals
  • Alternate row background filling (back brush, stroke settings)
teeGrid1.Rows.Alternate.Brush.Visible = true;
teeGrid1.Rows.Alternate.Brush.Color = Color.Lightcoral;
teeGrid1.Rows.Alternate.Stroke.Visible = true;
  • Events

The usual Onxxx events:

OnAfterDraw

OnCellEditing

OnCellEdited

OnClickedHeader

OnColumnResized

TeeGrid-specific events:

OnMoved (at TeeGrid.Columns, called when a column is dragged)

OnNewDetail (called when a row is expanded to show a sub-grid)

OnPaint (at TColumn class, to custom paint individual cells)

OnSelect (called when the grid selected cell is changed)

Several editor dialogs available for Winform projects, usable at design-time and runtime to modify all TeeGrid properties like columns, formatting, etc

using Steema.TeeGrid.WinForm.Editors;
TeeGridEditor editor = TeeGridEditor.Embed(this, this, tTeeGrid1.Editing);
editor.Show();

  • "Ticker" class

Update grid cell changes using a background thread with optional fade-out colors

Clone this wiki locally