Difference between revisions of "Grids Reference Page"

From Free Pascal wiki
Jump to navigationJump to search
Line 105: Line 105:
 
====procedure SortColRow(IsColumn: Boolean; index,FromIndex,ToIndex: Integer); overload;====
 
====procedure SortColRow(IsColumn: Boolean; index,FromIndex,ToIndex: Integer); overload;====
 
===TCustomStringGrid===
 
===TCustomStringGrid===
TCustomStringGrid serve as base for TStringGrid. It can be used for derived TStringGrid components that want to hide published properties. See [[new intermediate grids]] for more information.
+
TCustomStringGrid serves as the base for TStringGrid. It can be used for derived TStringGrid components that want to hide published properties. See [[new intermediate grids]] for more information.
  
This properties or methods are public and are also avalilable to TStringGrid.
+
These properties or methods are public and are also available to TStringGrid.
  
 
See the full [http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomstringgrid.html TCustomStringGrid Reference]
 
See the full [http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomstringgrid.html TCustomStringGrid Reference]
Line 113: Line 113:
 
This procedure sets the column width to the size of the widest text it finds in all rows for the column aCol. Tip: see the goDblClickAutoSize option to allow automatically resize columns when doubleClicking the column border.
 
This procedure sets the column width to the size of the widest text it finds in all rows for the column aCol. Tip: see the goDblClickAutoSize option to allow automatically resize columns when doubleClicking the column border.
 
====procedure AutoSizeColumns;====
 
====procedure AutoSizeColumns;====
Automatically resize all columns by fitting the larger text in each column, It's a quick method for applying AutoSizeColumn() for every column in the grid.
+
Automatically resizes all columns by adjusting them to fit in the longest text in each column. This is a quick method of applying AutoSizeColumn() for every column in the grid.
 
====procedure Clean; overload;====
 
====procedure Clean; overload;====
clean all cells in the grid, fixed or not.
+
Cleans all cells in the grid, fixed or not.
 
====procedure Clean(CleanOptions: TCleanOptions); overload;====
 
====procedure Clean(CleanOptions: TCleanOptions); overload;====
clean all cells in the grid subject to the given CleanOptions. see [[TCleanOptions]] for more information. Some examples:
+
Cleans all cells in the grid subject to the given CleanOptions. see [[TCleanOptions]] for more information. Some examples:
 
*Clean all cells: grid.Clean([]); (the same as grid.clean)
 
*Clean all cells: grid.Clean([]); (the same as grid.clean)
 
*Clean all non fixed cells: grid.Clean([gzNormal]);
 
*Clean all non fixed cells: grid.Clean([gzNormal]);
 
*Clean all cells but don't touch grid column headers: Grid.Clean[gzNormal, gzFixedRows]);
 
*Clean all cells but don't touch grid column headers: Grid.Clean[gzNormal, gzFixedRows]);
 
====procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TCleanOptions); overload;====
 
====procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TCleanOptions); overload;====
does the same as Clean(CleanOptions:TCleanOptions) but constrained to given StartCol,StartRow,EndCol and EndRow. Examples:
+
does the same as Clean(CleanOptions:TCleanOptions) but restricted to the given StartCol,StartRow,EndCol and EndRow. Examples:
 
*Clean column index 4 to 6 but don't touch grid column headers: many variations, Grid.Clean(4,Grid.FixedRows,6,Grid.RowCount-1,[]); Grid.Clean(4,0,6,Grid,RowCount-1, [gzNormal]); etc.
 
*Clean column index 4 to 6 but don't touch grid column headers: many variations, Grid.Clean(4,Grid.FixedRows,6,Grid.RowCount-1,[]); Grid.Clean(4,0,6,Grid,RowCount-1, [gzNormal]); etc.
 
====procedure Clean(aRect: TRect; CleanOptions: TCleanOptions); overload;====
 
====procedure Clean(aRect: TRect; CleanOptions: TCleanOptions); overload;====

Revision as of 13:57, 14 September 2005

Objective

This text will try to show the user some aspects of the grids components in lazarus. Also is intended to serve as a guide for users who never used grids before (as experienced users generally only need a reference for new functionality). So this text will try to reach the following objectives:

  1. To introduce the grids components to people with little or not previous delphi contact.
  2. To document the differences with respect to delphi grids components.
  3. To document the new functionality in lazarus grids.
  4. Create reference and examples for the components.

Overview

A grid is a component that provides a mean for display data in tabular format. The most obvious characteristic of grids is that they are composed of cells forming rows and columns.

The type of information that can be shown in a grid is very ample, mainly depends on what the user wants to show, generally this information is translated in text, colors, imagenes or one combination of them.

Given the great variety of information that can be represented, a series of grids exits whose purpose is to facilitate to the user showing a specific kind of information.

Inheritence Tree

[TCustomComponent]
     |
     |
 TCustomGrid
     |
     |
TCustomDrawGrid
     |
     |
  TDrawGrid
     |
     |
TCustomStringGrid
     |
     |
 TStringGrid

A Starting Example

As one of the objectives of this is to be nice with people with little or no previous lazarus knowledge lets do a quick starting example of grids in action. Why not, lets make a traditional "hello world" example using the TStringGrid Component.

  1. Create a new application.
    • From the main menu select: project->New Project
    • In the Create New Project dialog press the "Create Button"
    • A new empty form will be shown.
  2. Place a grid on the form
    • From the component palette select the "additional" tab
    • Click over the TStringGrid icon []
    • Click over the form, near to the top left corner. A new empty grid appears.
  3. Place a button on the form
    • From the component palette select the "Standard" tab
    • Click over the TButton icon []
    • Click over a empty area of the form. A new button appears.
  4. Doubleclick the button from the step 3, and write down the following code in the click button handler:
    • Stringgrid1.Cells[1,1] := 'Hi World!';
  5. Run the program by clicking the play icon []
    • by pressing the button1, the hello world text should appear in cell column 1, row 1.

Differences between Lazarus and Delphi grids

The current grids components present several differences with respect to the delphi's grids. This is mainly because the lazarus grids were created from scratch primarily without trying to make them fully compatible.

At a later stage, the compatibility with delphi's grids become a desired objective and the grids starting to follow more closely the delphi grid's interface, but still without doing strong efforts to make every single property or method to match the delphi counterpart. Also, because the grid's internals are much different some things are not possible or need to be done in a different way in the lazarus' grids. As the grids were evolved, greater compatibility becomes and is a desired.

Differences

In this place the known differences will be enumerated in no special order.

  • Cell Editors
  • Designtime Behaviour

New Functionality

  • Columns
  • Events
  • Grid Editor

Grids Reference

Information

The starting point for reference about TCustomGrid, TDrawGrid, TCustomDrawGrid, TCustomStringGrid and TStringGrid is the unit grids.pas reference

For TCustomDBGrid and TDBgrid is the unit dbgrids.pas reference

Currently there are not too much content in these links, due partly, to the lack of a tool that allows easily maintaining its content, but such tool is under construction and eventually the gaps will be filled.

In general, any Delphi referece about the grids should help to use Lazarus grids (don't forget that there are several differences between Delphi and Lazarus grids being documented), with this in mind and as a temporal place for reference information, this place will be used to document things that doesn't work the same as in Delphi or that is new functionality.

TCustomGrid

See the full TCustomGrid Reference

property OnBeforeSelection: TOnSelectEvent

property OnCompareCells: TOnCompareCells

property OnPrepareCanvas: TOnPrepareCanvasEvent

property OnDrawCell: TOnDrawCell

property OnEditButtonClick: TNotifyEvent

property OnSelection: TOnSelectEvent

property OnSelectEditor: TSelectEditorEvent

property OnTopLeftChanged: TNotifyEvent

procedure AutoAdjustColumns;

procedure BeginUpdate;

procedure Clear;

procedure DeleteColRow(IsColumn: Boolean; index: Integer);

function EditorByStyle(Style: TColumnButtonStyle): TWinControl;

procedure EndUpdate(UO: TUpdateOption); overload;

procedure EndUpdate(FullUpdate: Boolean); overload;

procedure EndUpdate; overload;

procedure ExchangeColRow(IsColumn: Boolean; index, WithIndex:Integer);

function IscellSelected(aCol,aRow: Integer): Boolean;

function IscellVisible(aCol, aRow: Integer): Boolean;

procedure LoadFromFile(FileName: string);

function MouseToCell(Mouse: TPoint): TPoint; overload;

function MouseToLogcell(Mouse: TPoint): TPoint;

function MouseToGridZone(X,Y: Integer): TGridZone;

function CellToGridZone(aCol,aRow: Integer): TGridZone;

procedure MoveColRow(IsColumn: Boolean; FromIndex, ToIndex: Integer);

procedure SaveToFile(FileName: string);

procedure SortColRow(IsColumn: Boolean; index:Integer); overload;

procedure SortColRow(IsColumn: Boolean; index,FromIndex,ToIndex: Integer); overload;

TCustomStringGrid

TCustomStringGrid serves as the base for TStringGrid. It can be used for derived TStringGrid components that want to hide published properties. See new intermediate grids for more information.

These properties or methods are public and are also available to TStringGrid.

See the full TCustomStringGrid Reference

procedure AutoSizeColumn(aCol: Integer);

This procedure sets the column width to the size of the widest text it finds in all rows for the column aCol. Tip: see the goDblClickAutoSize option to allow automatically resize columns when doubleClicking the column border.

procedure AutoSizeColumns;

Automatically resizes all columns by adjusting them to fit in the longest text in each column. This is a quick method of applying AutoSizeColumn() for every column in the grid.

procedure Clean; overload;

Cleans all cells in the grid, fixed or not.

procedure Clean(CleanOptions: TCleanOptions); overload;

Cleans all cells in the grid subject to the given CleanOptions. see TCleanOptions for more information. Some examples:

  • Clean all cells: grid.Clean([]); (the same as grid.clean)
  • Clean all non fixed cells: grid.Clean([gzNormal]);
  • Clean all cells but don't touch grid column headers: Grid.Clean[gzNormal, gzFixedRows]);

procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TCleanOptions); overload;

does the same as Clean(CleanOptions:TCleanOptions) but restricted to the given StartCol,StartRow,EndCol and EndRow. Examples:

  • Clean column index 4 to 6 but don't touch grid column headers: many variations, Grid.Clean(4,Grid.FixedRows,6,Grid.RowCount-1,[]); Grid.Clean(4,0,6,Grid,RowCount-1, [gzNormal]); etc.

procedure Clean(aRect: TRect; CleanOptions: TCleanOptions); overload;

The same as Clean(StartCol,StartRow,EndCol,EndRow, CleanOptions), just taking a TRect instead of individual cell coordinates. Useful to clean the selection: grid.Clean(Grid.Selection,[]);

property Cols[index: Integer]: TStrings read GetCols write SetCols;

Get/set a list of strings from/to the given grid's column index starting from row index 0 to RowCount-1.

Examples
  • Set Example: Set the content of the third column in the grid from a ListBox:
Grid.Cols[2] := ListBox1.Items;
  • Get Example: Set the content of a Listbox from the grid's column index 4:
procedure TForm1.FillListBox1;
var 
  StrTempList: TStringList;
begin
  StrTempList := TStringList(Grid.Cols[4]);
  if StrTempList<>nil then begin
    ListBox1.Items.Assign(StrTempList);
    StrTempList.Free;
  end;
end;   
Notes.

This property works in a different way in Lazarus than in Delphi when getting the data from the grid. In Lazarus a temporary TStringList object is created for retrieving the column content. It is the responsability of the user to free this object after use.

This means also that changes in the returned list will not affect the grids content or layout.

See the Get Example.

property Rows[index: Integer]: TStrings read GetRows write SetRows;

Get/set a list of strings from/to the given grid's row index starting from column index 0 to column ColCount-1.

Examples
  • Set Example: Set the content of the third row in the grid from a ListBox:
Grid.Rows[2] := ListBox1.Items;
  • Get Example: Set the content of a Listbox from the grid's row index 4:
procedure TForm1.FillListBox1;
var 
  StrTempList: TStringList;
begin
  StrTempList := TStringList(Grid.Rows[4]);
  if StrTempList<>nil then begin
    ListBox1.Items.Assign(StrTempList);
    StrTempList.Free;
  end;
end;   
Notes.

This property works in a different way in Lazarus than in Delphi when getting the data from the grid. In Lazarus a temporary TStringList object is created for retrieving the row content. It is the responsability of the user to free this object after use.

This means also that changes in the returned list will not affect the grids content or layout.

See the Get Example.

property UseXORFeatures;

Boolean property, default value: false;

This property controls how the dotted focus rectangle appears in the grid. When true, the rectangle is painted using the XOR raster operation. This allow us to see the focus rectangle no matter what the cells' background color is. When false, the user can control the color of the dotted focus rectangle using the FocusColor property

It also controls the look of the column/row resizing. When true, a line shows visually the size that the the column or row will have if the user ends the operation. When false, the column or row resizing takes effect just as the user drags the mouse.

Grids Howto

Editors

The editors support in Lazarus grids is covered in the Grids Custom Editors page: { When none of the builtin editors fits your application then you need to add a custom editor, and we have at least two options to this task, using a already existing component and try to fit that in the grid, or using custom drawing to "simulate" that there is a custom editor. Both methods are covered in the page. }

Todo

  • TInplaceEditor Support

known problems

29-marzo-2005:

  • mouse autoedit
    • linux: clicking a selected cell doesn't trigger the autoedit function (the editor lost focus inmmediatelly)
    • windows: it should work only if the grid has the focus, if not it should focus and a second click should autoedit (cannot detect if the grid was previously focused or not)
  • ColumnWidths: linux, windows: dbgrid start with default column widths instead of calculated ones (it's disabled because early canvas creation causes strange effects if the parent is a notebook page)
  • Resizing Columns: linux, windows. Resizing a column should not hide the editor (specially in dbgrid if we are inserting)
  • MouseWheel:
    • linux: mousewheel doesn't work as it should, (seems it's calling the default mousewheel handler)
    • windows: patch was sent.
  • Double painting: Apparently dbgrid is painting twice the cell background (one with fillrect and one in textRect)
  • AutoFillColumns: sometimes the clientwidth is evaluated incorrectly (sometimes there are phantom scrollbars)