Grids Reference Page/de

From Free Pascal wiki
Revision as of 13:40, 1 April 2006 by Swen (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Die Zielsetzung

Dieser Text will versuchen, dem Benutzer einige Aspekte der Grid-Komponenten in Lazarus zu zeigen. Es ist auch vorgesehen, als ein Handbuch für Benutzer zu dienen, die noch nie zuvor Grids benutzt haben (während erfahrene Benutzer im Allgemeinen nur eine Referenz benötigen für neue Funktionalitäten). Daher will dieser Text versuchen, die folgenden Ziele zu erreichen:

  1. Die Grid-Komponenten den Menschen mit geringem oder gar keinem Delphi Kontakt vorzustellen.
  2. Die Unterschiede hinsichtlich der Delphi Grid-Komponenten zu dokumentieren.
  3. Die neuen Funktionalitäten in Lazarus Grids zu dokumentieren.
  4. Referenzen und Beispiele für die Komponenten zu erstellen.

Überblick

Ein Grid ist eine Komponente, die a mean zur Anzeige von Daten in einem tabellarischen Format bietet. Die offensichtlichste Charakteristik von Grids ist, daß sie aus Zellen bestehen, Zeilen und Spalten bildend.

Der Informationstyp, der in einem Grid angezeigt werden kann, ist sehr weitläufig, hauptsächlich abhängig von dem, was der Benutzer anzeigen möchte. Gewöhnlich wird diese Information in Text, Farben, Bilder oder eine Kombination daraus übersetzt.

In Anbetracht der großen Vielfalt von Informationen, die representiert werden können, existiert eine Reihe von Grids, deren Zweck darin besteht, den Benutzer zu unterstützen, eine spezifische Art von Informationen zu zeigen.

Vererbungsbaum

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

Ein Anfangsbeispiel

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. Erstellen sie eine neue Anwendung.
    • Im Hauptmenü wählen sie: Projekt -> Neues Projekt
    • Im Erzeuge neues Projekt Dialog drücken sie den "Erzeuge Button"
    • Ein neues leeres Formular wird angezeigt.
  2. Platzieren sie ein Grid auf dem Formular.
    • In der Komponentenpalette wählen sie den "Additional" Tab.
    • Klicken sie auf das TStringGrid Icon [].
    • Klicken sie auf das Formular, in der Nähe der oberen linken Ecke. Ein neues leeres Grid erscheint.
  3. Platzieren sie einen Button auf dem Formular.
    • In der Komponentenpalette wählen sie den "Standard" Tab.
    • Klicken sie auf das TButton Icon [].
    • Klicken sie auf einen freien Bereich im Formular. Ein neuer Button erscheint.
  4. Klicken sie doppelt auf den Button von Schritt 3, und schreiben sie den folgenden Code in den click button handler:
    • Stringgrid1.Cells[1,1] := 'Hi World!';
  5. Starten sie das Programm durch klicken auf das Start Icon [].
    • Durch Drücken von Button1, sollte der hello world Text in der Zelle Spalte 1, Zeile 1 erscheinen.

Unterschiede zwischen Lazarus und 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.

Unterschiede

An dieser Stelle werden die bekannten Unterschiede aufgeführt ohne spezielle Reihenfolge.

  • Cell Editors
  • Designtime Behaviour

Neue Funktionsweise

  • Columns
  • Events
  • Grid Editor

Grids Referenz

Information

Der Ausgangspunkt für eine Referenz über TCustomGrid, TDrawGrid, TCustomDrawGrid, TCustomStringGrid und TStringGrid ist die Unit grids.pas Referenz.

Für TCustomDBGrid und TDBgrid ist es die Unit dbgrids.pas Referenz.

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

Siehe die vollständige TCustomGrid Referenz

Eigenschaft OnBeforeSelection: TOnSelectEvent

Eigenschaft OnCompareCells: TOnCompareCells

Eigenschaft OnPrepareCanvas: TOnPrepareCanvasEvent

Eigenschaft OnDrawCell: TOnDrawCell

Eigenschaft OnEditButtonClick: TNotifyEvent

Eigenschaft OnSelection: TOnSelectEvent

Eigenschaft OnSelectEditor: TSelectEditorEvent

Eigenschaft OnTopLeftChanged: TNotifyEvent

Prozedur AutoAdjustColumns;

Prozedur BeginUpdate;

Prozedur Clear;

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

Funktion EditorByStyle(Style: TColumnButtonStyle): TWinControl;

Prozedur EndUpdate(UO: TUpdateOption); overload;

Prozedur EndUpdate(FullUpdate: Boolean); overload;

Prozedur EndUpdate; overload;

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

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

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

Prozedur LoadFromFile(FileName: string);

Die LoadFromFile Prozedur erlaubt ihnen, Attribute, Formate und Werte von einer XML Datei in eine StringGrid Instanz zu laden. Zuerst, müssen sie einige dieser Optionen der SaveOptios Eigenschaft setzen (in ihrer TStringGrid Instanz) SaveOptions

 soDesign:     Save & Load ColCount,RowCount,FixedCols,FixedRows,
               ColWidths, RowHeights and Options (TCustomGrid)
 soPosition:   Save & Load Scroll Position, Row, Col and Selection (TCustomGrid)
 soAttributes: Save & Load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)
 soContent:    Save & Load Text (TCustomStringGrid)

Beispiel: 1) Öffnen sie ein neues Projekt "Application". 2) Fügen sie ein leeres TStringGrid hinzu. 3) Fügen sie einen TButton hinzu. 4) Fügen sie einen TOpenDialog hinzu. 5) Fügen sie das Ereignis OnCreate für das Formular hinzu. 5) Fügen sie das Ereignis OnClick für den Button hinzu.

unit Unit1; 

{$mode objfpc}{$H+}

interface

uses
  Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, Grids,
  Buttons, StdCtrls, XMLCfg;

type

  { TForm1 }
  TForm1 = class(TForm)
    StringGrid1: TStringGrid;
    Button1: TButton;
    OpenDialog1: TOpenDialog;
    procedure Button1Click(Sender: TObject);
    procedure Form1Create(Sender: TObject);
  private
    { private declarations }
  public
    { public declarations }
  end; 

var
  Form1: TForm1; 

implementation

{ TForm1 }

procedure TForm1.Form1Create(Sender: TObject);
begin
 //setzt die SaveOptions zur creation Zeit des Formulars 
 stringgrid1.SaveOptions := [soDesign,soPosition,soAttributes,soContent];
end;


procedure TForm1.Button1Click(Sender: TObject);
begin
 //Fragt ob die Execute Methode des OpenDialog gestartet wurde 
 //wenn ja, wählt der Benutzer eine XML Datei zum laden
 //dieser Name wird in der FileName Eigenschaft abgelegt

 if opendialog1.Execute then
 Begin
   //Clear the grid 
   StringGrid1.Clear;
   //Load the XML
   StringGrid1.LoadFromFile(OpenDialog1.FileName);
   //Refresh the Grid
   StringGrid1.Refresh;
 End;
end;

initialization
  {$I unit1.lrs}

end.

The sample xml file: (Kopieren sie den Text unterhalb in eine txt Datei, vergessen sie nicht den XML Header :-))

''<?xml version="1.0"?>
<CONFIG>
  <grid version="3">
    <saveoptions create="True" position="True" content="True"/>
    <design columncount="2" rowcount="5" fixedcols="1" fixedrows="1" defaultcolwidth="64" defaultRowHeight="20">
      <options>
        <goFixedVertLine value="True"/>
        <goFixedHorzLine value="True"/>
        <goVertLine value="True"/>
        <goHorzLine value="True"/>
        <goRangeSelect value="True"/>
        <goDrawFocusSelected value="False"/>
        <goRowSizing value="False"/>
        <goColSizing value="False"/>
        <goRowMoving value="False"/>
        <goColMoving value="False"/>
        <goEditing value="False"/>
        <goTabs value="False"/>
        <goRowSelect value="False"/>
        <goAlwaysShowEditor value="False"/>
        <goThumbTracking value="False"/>
        <goColSpanning value="False"/>
        <goRelaxedRowSelect value="False"/>
        <goDblClickAutoSize value="False"/>
        <goSmoothScroll value="True"/>
      </options>
    </design>
    <position topleftcol="1" topleftrow="1" col="1" row="1">
      <selection left="1" top="1" right="1" bottom="1"/>
    </position>
    <content>
      <cells cellcount="10">
        <cell1 column="0" row="0" text="Title Col1"/>
        <cell2 column="0" row="1" text="value(1.1)"/>
        <cell3 column="0" row="2" text="value(2.1)"/>
        <cell4 column="0" row="3" text="value(3.1)"/>
        <cell5 column="0" row="4" text="value(4.1)"/>
        <cell6 column="1" row="0" text="Title Col2"/>
        <cell7 column="1" row="1" text="value(1.2)"/>
        <cell8 column="1" row="2" text="value(2.2)"/>
        <cell9 column="1" row="3" text="value(3.2)"/>
        <cell10 column="1" row="4" text="value(4.2)"/>
      </cells>
    </content>
  </grid>
</CONFIG>''

--Raditz 20:49, 11 Jan 2006 (CET) Raditz aus Argentinien (Siehe /lcl/grids.pas für mehr Informationen) Diese Fähigkeit wurde hinzugefügt in Version: 0.7.1 (DATE: 3-DEC-2002)

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

Funktion MouseToLogcell(Mouse: TPoint): TPoint;

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

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

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

Prozedur SaveToFile(FileName: string);

Die SaveToFile Prozedur erlaubt ihnen, Formate, Attribute und Werte von TStringGrid in eine XML Datei zu speichern. Zuvor müssen sie die SaveOptios Eigenschaft wie folgt setzen:

soDesign:     Save & Load ColCount,RowCount,FixedCols,FixedRows,
              ColWidths, RowHeights and Options (TCustomGrid)
soPosition:   Save & Load Scroll Position, Row, Col and Selection (TCustomGrid)
soAttributes: Save & Load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)
soContent:    Save & Load Text (TCustomStringGrid)

Siehe Prozedur LoadFromFile für mehr Informationen.

--Raditz 21:06, 11 Jan 2006 (CET) aus ARGENTINIEN

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

Prozedur 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. Siehe new intermediate grids für mehr Informationen.

Diese Eigenschaften bzw. methoden sind public und auch bei TStringGrid verfügbar.

Siehe die vollständige TCustomStringGrid Referenz.

Prozedur AutoSizeColumn(aCol: Integer);

Diese Prozedur setzt die Spaltenbreite auf die Größe des breitesten Texts, den sie in allen Zeilen finden kann für die Spalte aCol. Tipp: siehe die goDblClickAutoSize Option, um den Spalten die automatische Anpassung zu erlauben, wenn doppelt auf den Spaltenrand geklickt wird.

Prozedur 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.

Prozedur Clean; overload;

Cleans all cells in the grid, fixed or not.

Prozedur 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]);

Prozedur 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.

Prozedur 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,[]);

Eigenschaft 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.

Beispiele
  • 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;   
Anmerkungen

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.

Eigenschaft 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.

Beispiele
  • 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;   
Anmerkungen

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.

Eigenschaft UseXORFeatures;

Boolean Eigenschaft, Vorgabewert: 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

Bekannte Probleme

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)