Grids Reference Page/de: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1		-	\
2	1		Zurück zu den [[Additional information/de\|Zusätzlichen Informationen]].\
3		-	\
	2	+
4	3		== 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:
5	4
6	5		1. Die Grid-Komponenten den Menschen mit geringem oder gar keinem Delphi Kontakt vorzustellen.
7	6		2. Die Unterschiede hinsichtlich der Delphi Grid-Komponenten zu dokumentieren.
8	7		3. Die neuen Funktionalitäten in Lazarus Grids zu dokumentieren.
9	8		4. Referenzen und Beispiele für die Komponenten zu erstellen.
10	9
11	10		## Überblick
12	11
13	12		Ein Grid ist eine Komponente, die hauptsächlich zur Anzeige von Daten in einem tabellarischen Format dient. Die offensichtlichste Charakteristik von Grids ist, dass sie aus Zellen bestehen, Zeilen und Spalten bildend.
14	13
15	14		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.
16	15
17	16		In Anbetracht der großen Vielfalt von Informationen, die repräsentiert werden können, existiert eine Reihe von Grids, deren Zweck darin besteht, den Benutzer zu unterstützen, eine spezifische Art von Informationen zu zeigen.
18	17
19	18		## Vererbungsbaum
20	19
21	20		[TCustomControl]
22	21		\|
23	22		\|
24	23		TCustomGrid
25	24		\|
26	25		+-------------+------------+
27	26		\| \|
28	27		TCustomDrawGrid TCustomDbGrid
29	28		\| \|
30	29		+--------+--------+ \|
31	30		\| \| TDbGrid
32	31		TDrawGrid TCustomStringGrid
33	32		\|
34	33		\|
35	34		TStringGrid
36	35
37	36		## Ein Anfangsbeispiel
38	37
39	38		Eine Zielsetzung dieses Textes soll die Benutzerfreundlichkeit sein, insbesondere für diejenigen, die keine oder wenig Erfahrung mit Lazarus haben. Fangen wir also mit einem einfachen Beispiel an, in dem wir die Grids-Komponente in Aktion sehen und beginnen mit dem traditionellen "Hallo Welt" Beispiel unter Verwendung der TStringGrid Komponente.
40	39
41	40		1. Erstellen sie eine neue Anwendung.
42	41		- Im Hauptmenü wählen sie: Projekt -\> Neues Projekt
43	42		- Im Erzeuge neues Projekt Dialog drücken sie den "Erzeuge Button"
44	43		- Ein neues leeres Formular wird angezeigt.
45	44		2. Platzieren sie ein Grid auf dem Formular.
46	45		- In der Komponentenpalette wählen sie den "Additional" Tab.
47	46		- Klicken sie auf das TStringGrid Icon ![](/wiki-images/6/67/Tstringgrid.png).
48	47		- Klicken sie auf das Formular, in der Nähe der oberen linken Ecke. Ein neues leeres Grid erscheint.
49	48		3. Platzieren sie einen Button auf dem Formular.
50	49		- In der Komponentenpalette wählen sie den "Standard" Tab.
51	50		- Klicken sie auf das TButton Icon ![](/wiki-images/b/b2/Tbutton.png).
52	51		- Klicken sie auf einen freien Bereich im Formular. Ein neuer Button erscheint.
53	52		4. Klicken sie doppelt auf den Button von Schritt 3, und schreiben sie den folgenden Code in den click button handler:
54	53		- ``` Pascal
55	54		StringGrid1.Cells[1,1] := 'Hi World!';
56	55		```
57	56		5. Starten sie das Programm durch klicken auf das Start Icon ![](/wiki-images/8/85/Menu_run.png).
58	57		- Durch Drücken von Button1, sollte der hello world Text in der Zelle Spalte 1, Zeile 1 erscheinen.
59	58
60	59		## Unterschiede zwischen Lazarus und Delphi Grids
61	60
62	61		Die momentanen Grid-Komponenten haben mehrere Unterschiede im Vergleich zu den Delphi Grid-Komponenten. Dies kommt vor allem daher, dass die Lazarus Grid-Komponenten komplett neu geschrieben wurden und dabei nicht zwingend auf die Kompatibilität geachtet wurde.
63	62
64	63		Die Kompatibiliät wurde erst zu einem späteren Zeitpunkt zu einem Ziel. Die Grid-Komponenten passten sich immer mehr dem Interface der Delphi Grid-Komponenten an, aber dabei wurde nicht jede einzelne Methode und jede Eigenschaft 1:1 übernommen.
65	64
66	65		Weil die Grid-Komponenten intern recht unterschiedlich sind, gibt es Dinge die nicht möglich sind oder anders als bei einer Delphi Grid-Komponente funktionieren. Im Laufe der Entwicklung der Grid-Komponenten, wurde die Kompatibilität jedoch immer besser was durchaus auch wünschenswert ist.
67	66
68	67		### Unterschiede
69	68
70	69		An dieser Stelle werden die bekannten Unterschiede aufgeführt ohne spezielle Reihenfolge.
71	70
72	71		- Zelleneditoren
73	72		- Entwicklungszeitverhalten
74	73		- Es gibt einige Unterschiede beim Zeichnen der Zellen, siehe Abschnitt Customizing grids
75	74
76	75		### Neue Funktionsweise
77	76
78	77		- Spalten
79	78		- Ereignisse
80	79		- Grid Editor
81	80
82	81		### Anpassungen zur Verbesserung der Delphi grids Kompatibilität
83	82
84	83		Hier ist eine Liste von Eigenschaften und Anpassungen die vorgenommen werden können, damit Lazarus grids wie Delphi grids aussehen oder sich so verhalten. This adjustments are based in a newly created grid. Einträge mit \[Code\] müssen im Quellcode gesetzt werden, \[Design\] Einträge können zur Entwicklungszeit geändert werden.
85	84
86	85		- \[Design\] TitleStyle:=tsStandard;
87	86		- \[Design\] DefaultRowHeight:=24;
88	87		- \[Code\] EditorBorderStyle:=bsNone; // dies dürfte nur unter Windows funktionieren.
89	88		- \[Code\] UseXORFatures:=true;
90	89		- \[Code\] AllowOutBoundClicks:=False; (r10992 oder später)
91	90		- \[Code\] FastEditing:=False; (unterstützt in dbgrid. StringGrid benötigt r10992 oder später)
92	91		- \[Design\] AutoAdvance:=aaNone;
93	92
94	93		## Grids Referenz
95	94
96	95		### Information
97	96
98	97		Der Ausgangspunkt für eine Referenz über TCustomGrid, TDrawGrid, TCustomDrawGrid, TCustomStringGrid und TStringGrid ist die [Unit grids.pas Referenz](http://lazarus-ccr.sourceforge.net/docs/lcl/grids/index.html).
99	98
100	99		Für TCustomDBGrid und TDBgrid ist es die [Unit dbgrids.pas Referenz](http://lazarus-ccr.sourceforge.net/docs/lcl/dbgrids/index.html).
101	100
102	101		Gegenwärtig enthalten diese Links noch nicht viel Inhalt, teilweise wegen des Fehlens eines Werkzeugs, das eine einfache Wartung ihres Inhalts erlaubt. Aber ein solches Werkzeug ist im Aufbau befindlich und irgendwann werden die Lücken gefüllt werden.
103	102
104	103		Im Allgemeinen, jede Delphi Referenz über Grids sollte helfen, die Lazarus Grids zu verwenden (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, wird dieser Ort genutzt, um Dinge zu dokumentieren, die nicht wie in Delphi funktionieren oder die eine neue Funktionalität darstellen.
105	104
106	105		\[TODO: the rest of this section will dissapear, it's content will be moved to [unit grids.pas reference](http://lazarus-ccr.sourceforge.net/docs/lcl/grids/index.html)
107	106
108	107		### TCustomGrid
109	108
110	109		See the full [[doc:lcl/grids/tcustomgrid.html\|TCustomGrid Reference]]
111	110
112	111		#### property OnBeforeSelection: TOnSelectEvent
113	112
114	113		#### property OnCompareCells: TOnCompareCells
115	114
116	115		#### property OnPrepareCanvas: TOnPrepareCanvasEvent
117	116
118	117		#### property OnDrawCell: TOnDrawCell
119	118
120	119		#### property OnEditButtonClick: TNotifyEvent
121	120
122	121		#### property OnSelection: TOnSelectEvent
123	122
124	123		#### property OnSelectEditor: TSelectEditorEvent
125	124
126	125		#### property OnTopLeftChanged: TNotifyEvent
127	126
128	127		#### procedure AutoAdjustColumns;
129	128
130	129		#### procedure BeginUpdate;
131	130
132	131		#### procedure Clear;
133	132
134	133		#### procedure DeleteColRow(IsColumn: Boolean; index: Integer);
135	134
136	135		#### function EditorByStyle(Style: TColumnButtonStyle): TWinControl;
137	136
138	137		#### procedure EndUpdate(UO: TUpdateOption); overload;
139	138
140	139		#### procedure EndUpdate(FullUpdate: Boolean); overload;
141	140
142	141		#### procedure EndUpdate; overload;
143	142
144	143		#### procedure ExchangeColRow(IsColumn: Boolean; index, WithIndex:Integer);
145	144
146	145		#### function IscellSelected(aCol,aRow: Integer): Boolean;
147	146
148	147		#### function IscellVisible(aCol, aRow: Integer): Boolean;
149	148
150	149		#### procedure LoadFromFile(FileName: string);
151	150
152	151		#### function MouseToCell(Mouse: TPoint): TPoint; overload;
153	152
154	153		#### function MouseToLogcell(Mouse: TPoint): TPoint;
155	154
156	155		#### function MouseToGridZone(X,Y: Integer): TGridZone;
157	156
158	157		#### function CellToGridZone(aCol,aRow: Integer): TGridZone;
159	158
160	159		#### procedure MoveColRow(IsColumn: Boolean; FromIndex, ToIndex: Integer);
161	160
162	161		#### procedure SaveToFile(FileName: string);
163	162
164	163		#### procedure SortColRow(IsColumn: Boolean; index:Integer); overload;
165	164
166	165		#### procedure SortColRow(IsColumn: Boolean; index,FromIndex,ToIndex: Integer); overload;
167	166
168	167		### TCustomStringGrid
169	168
170	169		TCustomStringGrid dient als Basis für TStringGrid. It can be used for derived TStringGrid components that want to hide published properties. See [[new intermediate grids]] for more information.
171	170
172	171		These properties or methods are public and are also available to TStringGrid.
173	172
174	173		See the full [TCustomStringGrid Reference](http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomstringgrid.html)
175	174
176	175		#### procedure AutoSizeColumn(aCol: Integer);
177	176
178	177		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 columns to be automatically resized when doubleClicking the column border.
179	178
180	179		#### procedure AutoSizeColumns;
181	180
182	181		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.
183	182
184	183		#### procedure Clean; overload;
185	184
186	185		Cleans all cells in the grid, fixed or not.
187	186
188	187		#### procedure Clean(CleanOptions: TCleanOptions); overload;
189	188
190	189		Cleans all cells in the grid subject to the given CleanOptions. see [[TCleanOptions]] for more information. Some examples:
191	190
192	191		- Clean all cells: grid.Clean(\[\]); (the same as grid.clean)
193	192		- Clean all non fixed cells: grid.Clean(\[gzNormal\]);
194	193		- Clean all cells but don't touch grid column headers: Grid.Clean\[gzNormal, gzFixedRows\]);
195	194
196	195		#### procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TCleanOptions); overload;
197	196
198	197		does the same as Clean(CleanOptions:TCleanOptions) but restricted to the given StartCol,StartRow,EndCol and EndRow. Examples:
199	198
200	199		- 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.
201	200
202	201		#### procedure Clean(aRect: TRect; CleanOptions: TCleanOptions); overload;
203	202
204	203		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,\[\]);
205	204
206	205		#### property Cols\[index: Integer\]: TStrings read GetCols write SetCols;
207	206
208	207		Get/set a list of strings from/to the given grid's column index starting from row index 0 to RowCount-1.
209	208
210	209		##### Beispiele
211	210
212	211		- Set Example: Set the content of the third column in the grid from a ListBox:
213	212
214	213		`Grid.Cols[2] := ListBox1.Items;`
215	214
216	215		- Get Example: Set the content of a Listbox from the grid's column index 4:
217	216
218	217		`procedure TForm1.FillListBox1;`\
219	218		`var `\
220	219		` StrTempList: TStringList;`\
221	220		`begin`\
222	221		` StrTempList := TStringList(Grid.Cols[4]);`\
223	222		` if StrTempList<>nil then begin`\
224	223		` ListBox1.Items.Assign(StrTempList);`\
225	224		` StrTempList.Free;`\
226	225		` end;`\
227	226		`end; `
228	227
229	228		##### Anmerkungen
230	229
231	230		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 responsibility of the user to free this object after use.
232	231
233	232		This means also that changes in the returned list will not affect the grids content or layout.
234	233
235	234		See the Get Example.
236	235
237	236		#### property Rows\[index: Integer\]: TStrings read GetRows write SetRows;
238	237
239	238		Get/set a list of strings from/to the given grid's row index starting from column index 0 to column ColCount-1.
240	239
241	240		##### Anmerkungen
242	241
243	242		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 responsibility of the user to free this object after use.
244	243
245	244		This means also that changes in the returned list will not affect the grids content or layout.
246	245
247	246		##### Beispiele
248	247
249	248		- Set Example: Set the content of the third row in the grid from a ListBox:
250	249
251	250		`Grid.Rows[2] := ListBox1.Items;`
252	251
253	252		- Get Example: Set the content of a Listbox from the grid's row index 4:
254	253
255	254		`procedure TForm1.FillListBox1;`\
256	255		`var `\
257	256		` StrTempList: TStringList;`\
258	257		`begin`\
259	258		` StrTempList := TStringList(Grid.Rows[4]);`\
260	259		` if StrTempList<>nil then begin`\
261	260		` ListBox1.Items.Assign(StrTempList);`\
262	261		` StrTempList.Free;`\
263	262		` end;`\
264	263		`end; `
265	264
266	265		- Not Working Example and Fix: Retrieved string list is read only
267	266
268	267		`// this will not work and will cause memory leak`\
269	268		`// because returned StringList is not being freed`\
270	269		`Grid.Rows[1].CommaText := '1,2,3,4,5';`\
271	270		`Grid.Rows[2].Text := 'a'+#13#10+'s'+#13#10+'d'+#13#10+'f'+#13#10+'g'; `\
272		-	\
	271	+
273	272		`// fixing the first case`\
274	273		`Lst:=TStringList.Create;`\
275	274		`Lst.CommaText := '1,2,3,4,5';`\
276	275		`Grid.Rows[1] := Lst;`\
277	276		`Lst.Free;`
278	277
279	278		#### property UseXORFeatures;
280	279
281	280		Boolesche Eigenschaft, Vorgabewert: false;
282	281
283	282		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]]
284	283
285	284		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.
286	285
287	286		## Grids Howto
288	287
289	288		### Customizing grids
290	289
291	290		Grid are components derived from TCustomControl class, and don't have a native widget associated to them which means that grids are not restricted by the look of current interface theme. This can be equally considered an advantage but also a disadvantage because usually programmers want to create a uniform-look application. The good news is that Lazarus grids are flexible enough to get something from both worlds, programmers can easily make grids to look like other native controls or they can customize the grid to the finest detail so they can obtain almost the same look in any platform or widget interface, that is, with the exception of scrollbars because their look is still determined by current theme.
292	291
293	292		### Eigenschaften und Ereignisse für customizing grids
294	293
295	294		Some properties can affect the way the grid looks by acting when the cell is about to be painted in PrepareCanvas/OnPrepareCanvas by changing default canvas properties like brush color or font. Following is a list of such properties:
296	295
297	296		- AlternateColor. With this the user can change the background color appears on alternated rows. This is to allow easy reading off of grid rows data.
298	297		- Color. This sets the primary color used to draw non fixed cells background.
299	298		- FixedColor. This is the color used to draw fixed cells background.
300	299		- Flat. this eliminates the 3d look of fixed cells.\
301	300		- TitleFont. Font used to draw the text in fixed cells.\
302	301		- TitleStyle. This property changes the 3D look of fixed cells, there are 3 settings:
303	302		- tsLazarus. This is the default look
304	303		- tsNative. This tries to set a look that is in concordance with current widgetset theme.
305	304		- tsStandard. This style is a more contrasted look, like delphi grids.
306	305		- AltColorStartNormal. boolean, if true alternate color is always in the second row after fixed rows, the first row after fixed rows will be always color, if false default color is set to the first row as if there were no fixed rows.
307	306		- BorderColor. This sets the grid's border color used when Flat:=True and BorderStyle:=bsSingle;
308	307		- EditorBorderStyle. If set to bsNone under windows the cell editors will not have the border, like in delphi, set to bsSingle by default because the border can be theme specific in some widgetsets and to allow a uniform look.\
309	308		- FocusColor. The color used to draw the current focused cell if UseXORFeatures is not set, by default this is clRed.
310	309		- FocusRectVisible. turns on/off the drawing of focused cell.
311	310		- GridLineColor. color of grid lines in non fixed area.
312	311		- GridLineStyle. Pen style used to draw lines in non fixed area, possible choices are: psSolid, psDash, psDot, psDashDot, psDashDotDot, psinsideFrame, psPattern,psClear. default is psSolid.
313	312		- SelectedColor. Color used to draw cell background on selected cells.
314	313		- UseXORFeatures. If set, focus rect is drawn using XOR mode so it should make visible the focus rect in combination with any cell color ackground. It also affects the moving columns look.
315	314		- DefaultDrawing. boolean. Normally the grids prepare the grid canvas using some properties according to the kind of cell is being painted. If user write an OnDrawCell event handler, DefaultDrawing if set also paints the cell background, if user is drawing fully the cell is better turn off this property so painting is not duplicated. In a StringGrid if DefaultDrawing is set it draws the text in each cell.
316	315		- AutoAdvance. where the cell cursor will go when pressing enter or tab/shift tab, or after editing.
317	316		- ExtendedColSizing. If true user can resize columns not just at the headers but along the columns height.
318	317
319	318		Other properties that also affect the grids look.
320	319
321	320		Options. Options property is a set with some elements to enable diverse functionality but some are related directly with grid's look. This options can be set at designtime or runtime.
322	321
323	322		- goFixedVertLine, goFixedHorzLine it draws a vertical or horizontal line respectively delimiting cells or columns in fixed area, active by default.
324	323		- goVertLine, goHorzLine the same as previous, but for normal browseable area. A listbox can be simulated with a grid by unsetting both of this elements.
325	324		- goDrawFocusSelected if this element is enabled a selection background is painted in focused cell in addition to focused dotted rectangle (note this doesn't work yet when goRowSelect option is set, in such case row is always painted as if goDrawFocusSelected is set)
326	325		- goRowSelect select the full row instead of individual cells
327	326		- goFixedRowNumbering if set, grid will do numbering of rows in first fixed column
328	327		- goHeaderHotTracking if set, the grid will try to show a different look when the mouse cursor is overing any fixed cell. In order for this to work, desired cell zone needs to be enabled with property HeaderHotZones. Try combining this option with property TitleStyle:=tsNative to get themed hot tracking look.
329	328		- goHeaderPushedLook if set, this element enables a pushed look when clicking any fixed cell. The zone of "pushable" cells is enabled using HeaderPusedZones property.
330	329
331	330		(write more)
332	331
333	332		### Description of grid's drawing process
334	333
335	334		Like other custom controls, the grid draws itself in the paint method, in general terms the grid is drawn by painting all rows, and each row by painting it's individual cells. The process is as follow:
336	335
337	336		- First the visible cells area is determined, each row is tested to see if it intersects the canvas clipping region, if it's ok, then visible area is painted by drawing columns of each row.
338	337		- The column and row values are used to identify the cell that is about to be painted and again each column is tested for intersection with clippling region, if everything is ok, some additional properties like it's rectangualar extent and visual state are passed as arguments to DrawCell method.
339	338		- As the drawing process is running, the visual state of each cell is adjusted according to grid options and position within grid. The visual state is resumed in a varible of type TGridDrawState which is a set with following elements:
340	339		- gdSelected The cell will have a selected look.
341	340		- gdFocused The cell will have a focused look.
342	341		- gdFixed Cell have to be painted with fixed cell look.
343	342		- gdHot the mouse is over this cell, so paint it with hot tracking look
344	343		- gdPushed the cell is being clicked, paint it with pushed look
345	344		- DrawCell. The DrawCell method is virtual and may be overriden in descendant grids to do custom drawing. The information passed to DrawCell method helps to identify the particular cell is being painted, the physical area ocuppied in screen and it's visible status. See DrawCell reference for details. For each cell following occurs:
346	345		- PrepareCanvas. PrepareCanvas method is called, in this method, If DefaultDrawing property es set, the grid canvas is setup with default properties for brush and font based on current visual state and on several design and runtime properties, the text alignment is set to match programmer selection in custom columns if they exists. If DefaultDrawing is false, brush color is set to clWindow and Font color to clWindowText, the text alignment is set with grids defaultTextStyle property value.
347	346		- OnPrepareCanvas. If programmer wrote a event handler for OnPrepareCanvas event, it's called at this point. This event can be used for doing simple customization like changing cell's background color, font's properties like color, fontface and style, Text layout like different combinations of left, center, top, bottom, right alignment, etc. Any change made to the canvas in this event would be lost, because the next cell drawing will reset canvas again to a default state. So it's safe doing changes only for particular cell or cells and forget about it for the rest. Using this event sometimes helps to avoid uusing OnDrawCell grid event where users would be forced to duplicate the grid's drawing code. todo: samples of what can be made and what to leave for OnDrawCell?...
348	347		- OnDrawCell. Next if no handler for OnDrawCell event was specified, the grid calls the DefaultDrawCell method which simply paints the cell background using current canvas brush color and style, if OnDrawCell handler exists, the grid first paints the cell background but only if DefaultDrawing property was set, then it calls OnDrawCell event to do custom cell painting. Usually programmers want to do custom drawing only for particular cells, but standard drawing for others, in this case, they can restrict custom operation to certain cell or cells by looking into ACol,ARow and AState arguments, and for other cells simply call DefaultDrawCell method and let the grid to take care of it.
349	348		- Text. At this point (only for TStringGrid) if DefaultDrawing property is true, the cell's text content is painted.
350	349		- Grid lines. The last step for each cell is to paint the grid lines if grid options goVertLine,goHorzLine, goFixedVertLine and goFixedHorzLine are specified the cell grid is drawn at this point. Grids with only rows or only cols can be obtained by changing these options. If programmer elected to have a "themed" look it's done at this point also (see property TitleStyle).
351	350		- FocusRect. When all columns of current row have been painted it's time to draw the focus rectangle for current selected cell or for the whole row if goRowSelect option is set.
352	351
353	352		### Grid's cell selection
354	353
355	354		Grid's current (focused) cell (or row) can be changed of location using keyboard, mouse or through code, in order a cell focus can be successfully changed to another position, target position need to be tested if it's allowed to receive cell focus. When using keyboard, the property AutoAdvance takes part of the process by finding what should be the next focused cell. When using mouse by clicking or by code, the target cell needs to be allowed to receive focus or currently focused cell will not move.
356	355
357	356		The way the grid knows what cell is focusable is by calling function SelectCell, if this function returns true, then the target cell identified with arguments acol and arow is focusable, current implementation in TCustomGrid simply returns true. TCustomDrawGrid and hence TDrawGrid and TStringGrid override this method to check first if cell is any wider than 0, normally you don't want a 0 width cell selected so a cell with this characteristics is skipped automatically in the process to find a suitable cell. The other thing the overriden method SelectCell does is to call the user configurable event OnSelectCell, this event receive as arguments, the cell coordinates and a default result value of true always.
358	357
359	358		Once a cell is known to be focusable and for sure a movement will take place, first method BeforeMoveSelection is called which in turns triggers OnBeforeSelection event, this method's arguments are the coordinates the new focused cell will have, at this point any visible editor is hidden too. the "before" word means that selection is not yet changed and current focused coordinates can be accessed with grid.Col and grid.Row properties.
360	359
361	360		After that, the internal focused cell coordinates are changed and then method MoveSelection is called, this method purpose is to trigger OnSelection event if set, this is a notification that focused cell has, by this time, already changed and cell coordinates are now available through grid.row and grid.col properties.
362	361
363	362		Note that is not good to use OnSelectCell event to detect cell focus changes, this event will be triggered several times even for the same cell in the process of finding a suitable cell. Is better to use OnBeforeSelection or OnSelection events for this purpose.
364	363
365	364		### Several differences with delphi have been identified
366	365
367	366		- In Lazarus TCustomGrid.DrawCell method is not abstract and it's default implementation do basic cell background filling.
368	367		- In delphi, the cell's text is drawn before entering the OnDrawCell event see [bug report \#9619](http://www.freepascal.org/mantis/view.php?id=9619)).
369	368		- SelectCell and OnSelectCell behaviour is probably different, can't really comment on the differences but in lazarus is they are used in functinality like AutoAdvance which afaik doesn't exist in delphi.
370	369
371	370		### When above customizaton is not enough, derived grids
372	371
373	372		Derivd grids usually have to override following methods:\
374	373		DrawAllRows: Draws all visible rows.\
375	374		DrawRow: Draw All Cells in a Row.\
376	375		DrawRow draws all cells in the row by first checking if cell is withing clipping region, and only draws the cell if it is.\
377	376		DrawCell:\
378	377		DrawCellGrid:\
379	378		DrawCellText:\
380	379		DrawFocusRect:\
381	380		(write me).\
382	381
383	382		### Ablauf der Methodenaufrufe in `TCustomGrid.Paint`
384	383
385	384		Die folgenden Auflistungen sollen den Ablauf zum Zeichnen eines TCustomGrid-Nachkommen vereinfacht darstellen. Die verschachtelten Aufzählungen bezeichnen jeweils Methodenaufrufe innerhalb eines Grids. Bei der Entwicklung von Nachkommen von TCustomGrid, kann so die richtige Methode zum Überschreiben leichter gefunden werden.
386	385
387	386		- `DrawEdges`: Zeichnet den äußeren Rahmen des Grids.
388	387		- `DrawAllRows` (virtual): Hier werden alle sichtbaren Zellen des Gitters gezeichnet.
389	388		- `DrawRow` (virtual): Zeichnet alle sichtbaren Zellen einer Zeile. Wird für jede Gitterzeile im aktuellen Sichtfenster einmal ausgeführt.
390	389		- `DrawCell` (virtual): Wird zunächst für jede 'normale' (also nicht fixierte) Zelle der Zeile ausgeführt.
391	390		- `PrepareCanvas` (virtual): Setzt die Eigenschaften der Zeichenfläche für das Zeichnen der aktuellen Zelle.
392	391		- `DrawFillRect`: Zeichnet den Hintergrund der Zelle im mit `PrepareCanvas` eingestellten Stil.
393	392		- `DrawCellGrid` (virtual): Zeichnet die Begrenzungen der Zelle.
394	393		- `DrawFocusRect` (virtual): In `TCustomGrid` hat diese Methode keine Funktion. In abeleiteten Grid-Klassen wird hier das Focus-Rechteck innerhalb der aktiven Zelle gezeichnet.
395	394		- `DrawCell` (virtual): (siehe oben) Abschließend wird `DrawCell` für jede fixierte Zelle im Sichtbereich der Zeile einmal ausgeführt.
396	395		- `DrawColRowMoving`: Wird nur während des Verschiebens einer Zeile/Spalte ausgeführt. Es zeichnet die Linie mit welcher die neue Position der verschobenen Zeile/Spalte angedeutet wird.
397	396		- `DrawBorder`: Wenn nötig (`Flat=TRUE` und `BorderStyle=bsSingle`), wird hier ein innerer Rand gezeichnet.
398	397
399	398		#### Weitere Methoden zum Zeichnen in `TCustomGrid`
400	399
401	400		Die folgenden Methoden werden zwar in `TCustomGrid` deklariert, hier aber nicht direkt aufgerufen. Sie werden von abgeleiteten Klassen ausgeführt um den Zelleninhalt zu zeichnen.
402	401
403	402		- `DrawCellText` (virtual): Zeichnet den im Parameter übergebenen Text in die Zelle. Verwendet zur Formatierung die in `Canvas.TextStyle` aktiven Einstellungen (siehe `PrepareCanvas`).
404	403
405		-	\
406	404		*`DrawThemedCell` (virtual): Wird nur für fixierte Zellen verwendet, wenn `TitleStyle=tsNative`. Zeichnet den Hintergrund der Zelle mit den Einstellungen der `ThemeServices`.\
407	405		*`DrawColumnText` (virtual): Wird nur für die Zellen der Spaltenüberschriften ausgeführt
408	406
409	407		- - `DrawColumnTitleImage`: Wenn eine `TitleImageList` zugewiesen und in `Columns.Title[x].Title.ImageIndex` ein gültiger Wert eingetragen ist, wird das entsprechende Icon gezeichnet.
410	408		- `DrawCellText` : (siehe oben)
411	409
412		-	\
413	410		*`DrawTextInCell` (virtual): Wird nur für 'normale' (nicht fixierte) Zellen verwendet. In `TCustomGrid` hat diese Methode keine Funktion. In abeleiteten Grid-Klassen wird hier der Zelleninhalt in die Zelle gezeichnet. In `TStringGrid` ruft diese Methode wiederum `DrawCellText` (siehe oben) auf.
414	411
415	412		#### Erweiterung des Zeichenfunktionen in `TCustomDrawGrid`
416	413
417	414		Wie man sieht, Zeichnet die Basisklasse `TCustomGrid` keinen Inhalt in das Grid. Dies geschieht in `TCustomDrawGrid`. Hier wird die Methode `DrawCell` folgendermaßen überschrieben.
418	415
419	416		- `DrawCell` (override):
420	417		- `PrepareCanvas`: Aufruf der von `TCustomGrid`geerbten Methode
421	418		- `DefaultDrawCell` (virtual): Ist eine Ereignisbehandlung für `OnDrawCell` zugewiesen, wird diese Methode nicht ausgeführt. Sonst
422	419		- `DrawFillRect / DrawThemedCell` (von `TCustomGrid`): Zeichnet den Hintergrund der Zelle. Ist `TitleStyle=tsNative`, wird der Hintergrund für fixierte Zellen mit `DrawThemedCell` gezeichnet.
423	420		- `DrawCellAutonumbering` (virtual): Nur, wenn `goFixedAutonumbering in Options` wird in der ersten fixierten Spalte mit `TCustomGrid.DrawCellText` die Numerierung gezeichnet.
424	421		- `DrawColumnText` (von `TCustomGrid`): Wird nur für die Zellen der Spaltenüberschriften ausgeführt. Siehe Weitere Methoden zum Zeichnen in `TCustomGrid`.
425	422		- `DrawTextInCell` (von `TCustomGrid`): Wird nur für 'normale' (nicht fixierte) Zellen ausgeführt. Siehe Weitere Methoden zum Zeichnen in `TCustomGrid`.
426	423		- `DrawCellGrid` (virtual): Zeichnet die Begrenzungen der Zelle.
427	424
428	425		### Operationen
429	426
430	427		#### Save and Retrieve Grid Content
431	428
432	429		The SaveToFile procedure allows you save the TStringGrid format, attributes & values to a XML file. Previously you must set the SaveOptios property as follow:
433	430
434	431		`soDesign: Save & Load ColCount,RowCount,FixedCols,FixedRows,`\
435	432		` ColWidths, RowHeights and Options (TCustomGrid)`\
436	433		`soPosition: Save & Load Scroll Position, Row, Col and Selection (TCustomGrid)`\
437	434		`soAttributes: Save & Load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)`\
438	435		`soContent: Save & Load Text (TCustomStringGrid)`
439	436
440	437		The LoadFromFile procedure allows you to load into a StringGrid instance, attributes, formats & values, from a XML file. First, you must set some of this options of the SaveOptios property (on your TStringGrid instance) [[SaveOptions]]
441	438
442	439		` soDesign: Save & Load ColCount,RowCount,FixedCols,FixedRows,`\
443	440		` ColWidths, RowHeights and Options (TCustomGrid)`\
444	441		` soPosition: Save & Load Scroll Position, Row, Col and Selection (TCustomGrid)`\
445	442		` soAttributes: Save & Load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)`\
446	443		` soContent: Save & Load Text (TCustomStringGrid)`
447	444
448	445		------------------------------------------------------------------------
449	446
450	447		Beispiel: 1) First Open a new project "Application". 2) Put an empty TStringGrid. 3) Put a TButton. 4) Put a TOpenDialog 5) Add the event OnCreate for the Form 5) Add the event OnClick for the Button
451	448
452	449		``` pascal
453	450		unit Unit1;
454	451
455	452		{$mode objfpc}{$H+}
456	453
457	454		interface
458	455
459	456		uses
460	457		Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, Grids,
461	458		Buttons, StdCtrls, XMLCfg;
462	459
463	460		type
464	461
465	462		{ TForm1 }
466	463		TForm1 = class(TForm)
467	464		StringGrid1: TStringGrid;
468	465		Button1: TButton;
469	466		OpenDialog1: TOpenDialog;
470	467		procedure Button1Click(Sender: TObject);
471	468		procedure Form1Create(Sender: TObject);
472	469		private
473	470		{ private declarations }
474	471		public
475	472		{ public declarations }
476	473		end;
477	474
478	475		var
479	476		Form1: TForm1;
480	477
481	478		implementation
482	479
483	480		{ TForm1 }
484	481
485	482		procedure TForm1.Form1Create(Sender: TObject);
486	483		begin
487	484		//sets the SaveOptions at creation time of the form
488	485		stringgrid1.SaveOptions := [soDesign,soPosition,soAttributes,soContent];
489	486		end;
490	487
491	488		procedure TForm1.Button1Click(Sender: TObject);
492	489		begin
493	490		//Ask if thew Execute method of the OpenDialog was launched
494	491		//when this occurs, the user selects an XML file to Load
495	492		//wich name was stored in the FileName prop.
496	493
497	494		if opendialog1.Execute then
498	495		Begin
499	496		//Clear the grid
500	497		StringGrid1.Clear;
501	498		//Load the XML
502	499		StringGrid1.LoadFromFile(OpenDialog1.FileName);
503	500		//Refresh the Grid
504	501		StringGrid1.Refresh;
505	502		End;
506	503		end;
507	504
508	505		initialization
509	506		{$I unit1.lrs}
510	507
511	508		end.
512	509		```
513	510
514	511		------------------------------------------------------------------------
515	512
516	513		Die Beispiel XML-Datei: (Kopieren sie den text unterhalb in eine .txt Datei. Vergessen sie den XML header nicht :-))
517	514
518	515		``` xml
519	516		''<?xml version="1.0"?>
520	517		<CONFIG>
521	518		<grid version="3">
522	519		<saveoptions create="True" position="True" content="True"/>
523	520		<design columncount="2" rowcount="5" fixedcols="1" fixedrows="1" defaultcolwidth="64" defaultRowHeight="20">
524	521		<options>
525	522		<goFixedVertLine value="True"/>
526	523		<goFixedHorzLine value="True"/>
527	524		<goVertLine value="True"/>
528	525		<goHorzLine value="True"/>
529	526		<goRangeSelect value="True"/>
530	527		<goDrawFocusSelected value="False"/>
531	528		<goRowSizing value="False"/>
532	529		<goColSizing value="False"/>
533	530		<goRowMoving value="False"/>
534	531		<goColMoving value="False"/>
535	532		<goEditing value="False"/>
536	533		<goTabs value="False"/>
537	534		<goRowSelect value="False"/>
538	535		<goAlwaysShowEditor value="False"/>
539	536		<goThumbTracking value="False"/>
540	537		<goColSpanning value="False"/>
541	538		<goRelaxedRowSelect value="False"/>
542	539		<goDblClickAutoSize value="False"/>
543	540		<goSmoothScroll value="True"/>
544	541		</options>
545	542		</design>
546	543		<position topleftcol="1" topleftrow="1" col="1" row="1">
547	544		<selection left="1" top="1" right="1" bottom="1"/>
548	545		</position>
549	546		<content>
550	547		<cells cellcount="10">
551	548		<cell1 column="0" row="0" text="Title Col1"/>
552	549		<cell2 column="0" row="1" text="value(1.1)"/>
553	550		<cell3 column="0" row="2" text="value(2.1)"/>
554	551		<cell4 column="0" row="3" text="value(3.1)"/>
555	552		<cell5 column="0" row="4" text="value(4.1)"/>
556	553		<cell6 column="1" row="0" text="Title Col2"/>
557	554		<cell7 column="1" row="1" text="value(1.2)"/>
558	555		<cell8 column="1" row="2" text="value(2.2)"/>
559	556		<cell9 column="1" row="3" text="value(3.2)"/>
560	557		<cell10 column="1" row="4" text="value(4.2)"/>
561	558		</cells>
562	559		</content>
563	560		</grid>
564	561		</CONFIG>''
565	562		```
566	563
567	564		------------------------------------------------------------------------
568	565
569	566		--Raditz 21:06, 11 Jan 2006 (CET) from ARGENTINA
570	567
571	568		### Grid Cell Editors
572	569
573	570		The grid uses cell editors to change the content of cells. For a specilized grid like TStringGrid, the editor is the habitual single line text editor control, sometimes it's desireable to have other means to enter information. For example,
574	571
575	572		`to call the open file dialog to find the location of a file so the user doesn't have to type the full path manually, if `
576	573
577	574		the text in the cell represents a date, it would be more friendly if we could popup a calendar so we can choose a specific date easily. Sometimes the information the user should enter in a cell is restricted to a limited list of words, in this case typing the information directly might introduce errors and validating routines might need to be implemented, we can avoid this by using a cell editor that present the user a list with only the legal values. This is also the case of generic grids like TDrawGrid where user have to have some kind of structure to hold the data that will be shown in the grid, in this situation, the information that is entered in the cell editor updates the internal structure to reflect the changes in the grid.
578	575
579	576		#### Builtin cell editors
580	577
581	578		The grids.pas unit already include some of the most used cell editors ready for use in grids, there is also the posibility to create new cell editors (custom cell editors) if the builtin editors are not appropiated for a specific tasks.
582	579
583	580		The builtin cell editors are Button, Edit, and Picklist.
584	581
585	582		#### Using cell editors
586	583
587	584		Users can specify what editor will be used for a cell using one of two methods.
588	585
589	586		1. Using a custom column and selecting the ButtonStyle property of column. In this method the user can select the style of
590	587
591	588		the editor that will be shown. Available values are: cbsAuto, cbsEllipsis, cbsNone, cbsPickList, cbsCheckboxColumn
592	589
593	590		1. Using OnSelectEditor grid event, here the user specify in the Editor parameter which editor to use for a cell identified
594	591
595	592		for column aCol and row ARow in a TCustomDrawGrid derived grid or TColumn in TCustomDBGrid. For this purpose there is a useful public function of grids, EditorByStyle() that takes as parameter one of the following values: cbsAuto, cbsEllipsis, cbsNone, cbsPickList, cbsCheckboxColumn. This method takes precedence over the first one using custom columns. A Custom cell editor can be specified here. This event is also the place to setup the editor with values specific to the cell, row or column.
596	593
597	594		#### Description of editor styles
598	595
599	596		The following is the description of each editor style, they are enumeated values of type TColumnButtonStyle and so they are prefixed by 'cbs'. This type was used so it remains compatible with delphi's dbgrid.
600	597
601	598		- cbsAuto
602	599
603	600
604	601		This is the default editor style for TCustomGrid derived grids. The actual editor class that will be used to edit the
605	602
606	603		cell content, depends on several factors. For TCustomGrids it uses a TStringCelleditor class derived from TCustomMaskEdit,
607	604
608	605		`this editor is speciallized to edit single line strings. It is then used in TStringGrid and TDrawGrid by default. When `
609	606
610	607		using Custom Columns and programmer filled the Column's PickList property, this behaves as if cbsPickList editor style was set. For a TCustomDBGrid that have a field of type boolean, behaves as if cbsCheckBoxColumn editor style was specified. This is the recomended value for Custom Cell Editors TODO: related OnEditingDone.
611	608
612	609		- cbsEllipsis
613	610
614	611
615	612		This editor style is the most generic one. When used, a button appears in the editing cell, programmers could use the
616	613
617	614		OnEditButtonClick grid event to detect when user has pressed the button and take any action was programmed for such cell. For example a programmer could use this editor style to pop up a calendar dialog so user can easily pick a specific date, another could be to show a file open dialog to find files, a calculator so user can enter the numeric result of calcs, etc.
618	615
619	616
620	617		OnEditButtonClick is just a notification, so to find out which cell a button has been clicked, take a look at grid.Row
621	618
622	619		and grid.Col properties.
623	620
624	621
625	622		A DbGrid has specific properties to retrieve the active column or field and because this event occurs in active record,
626	623
627	624		it could update the information in active field.
628	625
629	626
630	627		This editor style is implemented using TButtonCellEditor a direct descendant of TButton.
631	628
632	629		- cbsNone
633	630
634	631
635	632		This editor style instruct the grid to not use any editor for a specific cell or column, it behaves then, as if the grid
636	633
637	634		is readonly for such cell or column.
638	635
639	636		- cbsPickList
640	637
641	638
642	639		Used to present the user a list of values that can be entered, this editor style is implemented using
643	640
644	641		TPickListCellEditor a component derived from TCustomComboBox. The list of values that are shown, are filled in two ways depending of the method used to select the editor style.
645	642
646	643		:#When using custom columns, programmers can enter a list of values using the column's PickList property. \[FOR BEGINNERS: TODO: exact procedure to edit the list\]
647	644
648	645		:#In OnSelectEditor, programmers get the TPickListCellEditor instance using the function EditorByStyle(cbsPickList), an example would be: var Lst:TPickListCellEditor; begin \[...\] Lst:=TPickListCellEditor(EditorByStyle(cbsPickList)); Lst.clear; Lst.Items.add('One');lst.items.add('Two'); Editor:=Lst; end;
649	646
650	647
651	648		The value in a TStringGrid grid will automatically reflect the value selected, if necessary the programmer could detect
652	649
653	650		the moment the value is selected by writing an event handler for grid's OnPickListSelect event, so additional steps can be taken for example, to process the new value. TODO: related OnEditingDone.
654	651
655	652		- cbsCheckboxColumn
656	653
657	654
658	655		This editor style is at the moment only available in TDbGrid. This editor style can be useful when field content
659	656
660	657		associated with the column are restricted to a pair of values, for example, yes-no, true-false, on-off, 1-0, etc. Instead of forcing the user to type the values for this kind of field in a StringCellEditor or to choose one from a list, cbsCheckboxColumn is used to modify the field content of a column by using a checkbox representation that user can toggle by using a mouse click or pressing the SPACE key.
661	658
662	659
663	660		If columns' ButtonStyle property is set to cbsAuto and DbGrid detects that the field associated to the column is a
664	661
665	662		boolean field, then the grid use this editor style automatically, this automatic selection can be disabled or enabled using dbgrid's OptionsExtra property, setting dgeCheckboxColumn element to false disable this feature.
666	663
667	664
668	665		The values that are used to recognize the checked or unchecked states are set in column's properties ValueChecked and
669	666
670	667		ValueUnchecked.
671	668
672	669
673	670		In any moment, the field value can be in one to three states: Unchecked, checked or grayed. Internally this states are
674	671
675	672		identified by the following values of type TDBGridCheckBoxState: gcbpUnChecked, gcbpChecked and gcbpGrayed.
676	673
677	674
678	675		This editor style doesn't use real TCheckbox components to handle user interaction, the visual representation is given
679	676
680	677		by three builtin bitmap images that corresponds to the possible states of checkbox. The used bitmaps can be customized by writing a handler for DBGrid event OnUserCheckboxBitmap, the handler of this event gets the state of the checkbox in parameter CheckedState of type TDbGridCheckboxState and a bitmap parameter that programmer could use to specify custom bitmaps.
681	678
682	679		#### Beispiel: How to set a custom cell editor
683	680
684	681		Siehe lazarus/examples/gridcelleditor/gridcelleditor.lpi
685	682
686	683		### Wie scrollt man ein Grid in "Echtzeit" (während man den Scrollbalken per Maus bewegt)
687	684
688	685		Wenn man ein Grid scrollt, indem man den Scrollbalken per Maus bewegt, dann scrollt das Grid per Default nicht "in Echtzeit", sondern erst, wenn man die Maus los lässt, "springt" das Grid an seine neue Position. Man kann ein scrollen "in Echtzeit" aktivieren, in dem man Option `goThumbTracking` hinzufügt.
689	686
690	687		Beispiel:
691	688
692	689		``` pascal
693	690		StringGrid1.Options:=StringGrid1.Options + [goThumbTracking];
694	691		```
695	692
696	693		Leider ist diese Option weder dokumentiert in `<lazarus-installdir>\lcl\grids.pas` (ver 2.0.6) noch in <https://lazarus-ccr.sourceforge.io/docs/lcl/grids/tgridoptions.html>
697	694
698	695		## Todo
699	696
700	697		- TInplaceEditor Unterstützung
701	698
702	699		### Bekannte Probleme
703	700
704	701		29-März-2005:
705	702
706	703		- mouse autoedit
707	704		- linux: clicking a selected cell doesn't trigger the autoedit function (the editor lost focus inmmediatelly)
708	705		- 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)
709	706		- 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)
710	707		- Resizing Columns: linux, windows. Resizing a column should not hide the editor (specially in dbgrid if we are inserting)
711	708		- MouseWheel:
712	709		- linux: mousewheel doesn't work as it should, (seems it's calling the default mousewheel handler)
713	710		- windows: patch was sent.
714	711		- Double painting: Apparently dbgrid paints the cell background twice (once with fillrect and once in textRect)
715	712		- AutoFillColumns: sometimes the clientwidth is evaluated incorrectly (sometimes there are phantom scrollbars)
716		-
717		-	\
718		-	\
719	713
720	714		---
721	715		From the Free Pascal wiki, page "Grids Reference Page/de", as it stood on 2022-01-21 after a change by Slawek, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
722	716		Category: Deutsch
723	717		Category: Tutorials/de

Back to history