Grids Reference Page: what changed

Revision 4 to 5. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Objective
2	2
3	3		This text will try to show the user some aspects of the grids components in Lazarus. It is also intended to serve as a guide for users who have never used grids before (as experienced users generally only need a reference for new functionality). This text will therefore try to reach the following objectives:
4	4
5	5		1. To introduce the grids components to people with little or no previous Delphi experience.
6	6		2. To document the differences with respect to Delphi grids components.
7	7		3. To document the new functionality in Lazarus grids.
8	8		4. Create reference and examples for the components.
9	9
10	10		## Overview
11	11
12	12		A grid is a component that provides a means for displaying data in tabular format. The most obvious characteristic of grids is that they are composed of cells forming rows and columns.
13	13
14	14		The type of information that can be shown in a grid varies and mainly depends on what the user wants to show. Generally this information consists of text, colors, images or a combination of those three.
15	15
16	16		Given the great variety of information that can be represented, a series of grids exist whose purpose is to facilitate the user in showing specific kinds of information. For instance, there is a grid designed to show text: the StringGrid. Documentation for that grid can be found [here](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tstringgrid.html>)
17	17
18	18		## Inheritance Tree
19	19		```
20	20		[[TCustomControl]]
21	21		\|
22	22		\|
23	23		TCustomGrid
24	24		\|
25	25		+-------------+------------+
26	26		\| \|
27	27		TCustomDrawGrid TCustomDbGrid
28	28		\| \|
29	29		+--------+--------+ \|
30	30		\| \| [[TDBGrid]]
31	31		[[TDrawGrid]] TCustomStringGrid
32	32		\|
33	33		---------+----------
34	34		\| \|
35	35		[[TStringGrid]] [[TValueListEditor]]
36	36		```
37	37
38	38		## A Starting Example
39	39
40	40		As one of the objectives of this page is to help people with little or no previous Lazarus knowledge let's do a quick starting example of grids in action. Why not, let's make a traditional "hello world" example using the TStringGrid Component.
41	41
42	42		1. Create a new application.
43	43		* From the main menu select: project->New Project
44	44		* In the Create New Project dialog press the "Create Button"
45	45		* A new empty form will be shown.
46	46		2. Place a grid on the form
47	47		* From the component palette select the "additional" tab
48	48		* Click over the TStringGrid icon [![tstringgrid.png](/wiki-images/c/c4/tstringgrid.png)](</File:tstringgrid.png>)
49	49		* Click over the form, near to the top left corner. A new empty grid appears.
50	50		3. Place a button on the form
51	51		* From the component palette select the "Standard" tab
52	52		* Click over the TButton icon [![tbutton.png](/wiki-images/b/b2/tbutton.png)](</File:tbutton.png>)
53	53		* Click over a empty area of the form. A new button appears.
54	54		4. Doubleclick the button from step 3, and write down the following code in the click button handler:
55	55		*
56	56		```
57	57		StringGrid1.Cells[1,1] := 'Hi World!';
58	58		```
59	59
60	60		5. Run the program by clicking the play icon [![menu run.png](/wiki-images/0/0d/menu_run.png)](</File:menu_run.png>)
61	61		* by pressing the Button1, the hello world text should appear in cell column 1, row 1. (note that left column and top row are 0)
62	62
63	63		## Differences between Lazarus and Delphi grids
64	64
65	65		The current grid components differ from Delphi grids in several ways. When first developed the Lazarus grids were created from scratch without any attempt to make them fully Delphi-compatible.
66	66
67	67		At a later stage, compatibility with Delphi's grids became a desired objective and the Lazarus grids started to conform more closely to the Delphi grid interface. However even this was done without attempting to make every single Lazarus grid property or method match its Delphi counterpart. Also (because Lazarus grid internals are very different from Delphi grid internals) some Delphi functionality is not possible or needs to be emulated differently in a Lazarus grid from how it would be done in a Delphi grid. We have achieved greater Delphi compatibility as the Lazarus grids have evolved, and this is desirable.
68	68
69	69		### Differences
70	70
71	71		Known differences are listed below, in no special order.
72	72
73	73		* Cell Editors
74	74		* Designtime Behaviour
75	75		* Cell Drawing has some differences, see customizing grid section.
76	76
77	77		### New Functionality
78	78
79	79		* Custom Columns
80	80		* Events
81	81		* Grid Editor
82	82
83	83		### Ways in which you can make a Lazarus grid more Delphi-compatible
84	84
85	85		You can make a Lazarus grid look like and behave like a corresponding Delphi. Listed below are property settings which will achieve this. These adjustments are based in a newly created grid. Entries tagged with [Code] need to be set in code, [Design] entries can be changed at design time.
86	86
87	87		* [Design] TitleStyle := tsStandard;
88	88		* [Design] DefaultRowHeight := 24;
89	89		* [Code] EditorBorderStyle := bsNone; // this might work only on Windows.
90	90		* [Code] UseXORFeatures := true;
91	91		* [Code] AllowOutBoundEvents := False; // SVN revision 10992 or later
92	92		* [Code] FastEditing := False; // supported in dbgrid. StringGrid requires SVN revision 10992 or later
93	93		* [Design] AutoAdvance := aaNone;
94	94
95	95		## Grids Reference
96	96
97	97		### Information
98	98
99	99		The starting point for reference about TCustomGrid, TDrawGrid, TCustomDrawGrid, TCustomStringGrid and TStringGrid is the [unit Grids.pas reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/index.html>)
100	100
101	101		For TCustomDBGrid and TDBgrid it is the [unit DBGrids.pas reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/dbgrids/index.html>)
102	102
103	103		In general, any Delphi reference about the grids should help us to use Lazarus grids (but don't forget that there are several differences between Delphi and Lazarus grids that we have documented); with this in mind and as a temporary place for reference information, this place will be used to document things that don't work the same as in Delphi, as well as any new functionality.
104	104
105	105		TODO: the rest of this section will disappear; its content will be moved to [unit Grids.pas reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/index.html>)
106	106
107	107		### TCustomGrid
108	108
109	109		See the full [TCustomGrid Reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomgrid.html> "doc:lcl/grids/tcustomgrid.html")
110	110
111	111		#### property AllowOutboundEvents
112	112
113	113		Protected in TCustomGrid, public in TCustomDrawGrid and descendants. Normally when user click on a point over empty space after cells (for example if grid has three rows but user clicks on an imaginary fourth row), the currently focused cell will move to the nearest cell to the point just clicked. We call this an outbound event. The default value is true as this has been grid's behaviour since begining. This property was added to simulate Delphi behaviour where outbound events are not available, so to enable Delphi compatibility set this property to false.
114	114
115	115		#### property Columns
116	116
117	117		Lazarus includes the property columns in TStringGrid and TDrawGrid grids. This property adds what we call custom columns. Custom columns are a collection of objects that hold properties that apply to whole columns, for example column titles (for a StringGrid it will override the value specified in the corresponding Cells[ColumnIndex, RowTitle] property), text alignment, background color, preferred editor, etc.
118	118
119	119		Custom columns add extra properties or replace default property values on normal grid columns. Not only this, the grid.ColCount value may increase or decrease in order to account for the number of custom columns being attached to the grid. At this point, this means that grid.ColCount = grid.FixedCols \+ grid.Columns.Count.
120	120
121	121		For example, if to a base grid with ColCount := 5 and FixedCols := 2 we:
122	122
123	123		* Add 3 custom columns, the base grid will be exactly as before, 2 fixed cols and 3 normal cols.
124	124		* Add 1 custom column, the base grid will have ColCount := 3, that is 2 fixed cols and 1 normal cols.
125	125		* Add 4 custom columns, the base grid will have ColCount := 6, that is 2 fixed cols and 4 normal cols.
126	126
127	127		From this we can conclude that:
128	128
129	129		* Fixed column properties or count are not enhanced or modified respectively by custom columns.
130	130		* grid.ColCount is usually different from grid.Columns.Count (grid.ColCount =grid.Columns.Count only when FixedCols =0)
131	131
132	132		At design time the user can access the columns property in the Object Inspector to bring up the columns editor. From there you can add, remove or modify custom columns. The editor shows a list of current custom columns; by selecting items in this list the object inspector gets filled with the properties available for each column. The list of custom columns is also available in the Object Inspector component tree view, where columns can be added, deleted or modified. They appear on a lower level under the container grid.
133	133
134	134		At runtime, columns can be modified with code like this:
135	135		```
136	136		var
137	137		c: TGridColumn;
138	138		begin
139	139		// add a custom column a grid
140	140		c := Grid.Columns.Add;
141	141		// modify
142	142		c.title.caption := 'Price'; // Set columns caption
143	143		c.align := taRightJustify; // Align column content to the right
144	144		c.color := clMoneyGreen; // Change default color to clMoneyGreen
145	145		c.Index := 0; // Make it the first column
146	146		// access an existing column
147	147		grid.columns[0].Width := 60; // Change column 0 width to 60 pixels
148	148		// delete an existing column
149	149		grid.columns.delete(0); // Delete column 0
150	150		....
151	151		end;
152	152		```
153	153
154	154		Additionally, when using custom columns, the grids do not allow direct modification of grids.colcount ; adding or removing columns should be done using the columns property. The explanation is that there is an inconsistency on gradually removing custom columns using ColCount , when ColCount reaches FixedCols , the grid has no more custom columns. If we now increase ColCount , the new column will not be a custom column but a normal column.
155	155
156	156		Currently there are no plans to make the grids use only custom columns.
157	157
158	158		#### property AutoFillColumns
159	159
160	160		Often the grids are wider than the horizontal space needed by the columns -- this leaves an unpleasant empty area at the right of the last column. The LCL grids provide a mechanism to expand the width of specified columns such that the empty space is filled automatically.
161	161
162	162		For this purpose, Columns must be added either as described above, or by setting the `ColCount` property, and the grid property `AutoFillColumns` must be set to `true`. Each Column has a property `SizePriority`. When it has the value `0` the column width is taken from the `Width` property of the column. But when it has a non-zero value the column width is adjusted to the average available size remaining for all columns with a non-zero `SizePriority`.
163	163
164	164		#### procedure SaveToFile(AFileName: String);
165	165
166	166		Saves the grid to an XML file. The property `SaveOptions` determines what exactly is to be saved:
167	167		```
168	168		type
169	169		TGridSaveOptions = (
170	170		soDesign, // Save grid structure (col/row count and Options)
171	171		soAttributes, // Save grid attributes (Font, Brush, TextStyle)
172	172		soContent, // Save Grid Content (Text in StringGrid)
173	173		soPosition // Save Grid cursor and selection position
174	174		);
175	175		TSaveOptions = set of TGridSaveOptions;
176	176		```
177	177
178	178		#### procedure LoadFromFile(AFileName: String);
179	179
180	180		Loads the XML file created by `SaveToFile`. Again, the `SaveOptions` define what exactly is to be loaded from the file.
181	181
182	182		### TCustomDBGrid
183	183
184	184		TCustomDBGrid is the base for TDBGrid.
185	185
186	186		They do not expose Col and Row properties. To go to a certain column, use e.g. the SelectedIndex property.
187	187
188	188		An interesting public method is AutoAdjustColumns.
189	189
190	190		#### procedure AutoAdjustColumns
191	191
192	192		This procedure sets the column width to the size of the widest text it finds. It can be used after loading a dataset/setting it Active.
193	193
194	194		However, contrary to TCustomStringGrid.AutoAdjustColumns (see below), this will set your columns very wide unless you have the property dgAutoSizeColumns enabled.
195	195
196	196		#### procedure InplaceEditor
197	197
198	198		See example from bug 23103 - _and insert explanation of what it does/why it is needed. Validate input values? Change what is shown?_
199	199		```
200	200		procedure TForm1.DBGrid1KeyPress(Sender: TObject; var Key: char);
201	201		var
202	202		S: String;
203	203		begin
204	204		if (Key in [',','.']) then
205	205		begin
206	206		//unlike Delphi not all InPlaceEditors are editors for string type, so check!
207	207		if (DBGrid1.InplaceEditor is TStringCellEditor) then
208	208		begin
209	209		S := TStringCellEditor(DBGrid1.InplaceEditor).EditText;
210	210		if Pos(',',S) > 0 then
211	211		Key := #0
212	212		else
213	213		Key := ',';
214	214		end;
215	215		end;
216	216		end;
217	217		```
218	218
219	219		### TCustomStringGrid
220	220
221	221		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.
222	222
223	223		The following properties or methods are public and are also available to TStringGrid.
224	224
225	225		See the full [TCustomStringGrid Reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomstringgrid.html> "doc:lcl/grids/tcustomstringgrid.html")
226	226
227	227		#### procedure AutoSizeColumn(aCol: Integer);
228	228
229	229		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.
230	230
231	231		#### procedure AutoAdjustColumns or AutoSizeColumns
232	232
233	233		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.
234	234
235	235		#### procedure Clean; overload;
236	236
237	237		Cleans all cells in the grid, fixed or not.
238	238
239	239		#### procedure Clean(CleanOptions: TGridZoneSet); overload;
240	240
241	241		Cleans all cells in the grid subject to the given CleanOptions. See [TGridZoneSet](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tgridzoneset.html> "doc:lcl/grids/tgridzoneset.html") for more information. Some examples:
242	242
243	243		* Clean all cells: grid.Clean([]); (the same as grid.clean)
244	244		* Clean all non fixed cells: grid.Clean([gzNormal]);
245	245		* Clean all cells but don't touch grid column headers: Grid.Clean([gzNormal, gzFixedRows]);
246	246
247	247		#### procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TGridZoneSet); overload;
248	248
249	249		does the same as Clean(CleanOptions:TGridZoneSet) but restricted to the given StartCol,StartRow,EndCol and EndRow. Examples:
250	250
251	251		* 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.
252	252
253	253		#### procedure Clean(aRect: TRect; CleanOptions: TGridZoneSet); overload;
254	254
255	255		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,[]);
256	256
257	257		#### procedure SaveToCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
258	258
259	259		Save grid content to a comma separated values format (CSV) file (added in Lazarus r32179).
260	260
261	261		The AFilename argument specifies a file name where the content will be saved. If the file exists, the content will be overwritten. If it doesn't exist, the file will be created.
262	262
263	263		ADelimiter (an optional argument) is used to supply a custom separator if required. By default a CSV format is produced (that is, ADelimiter:=',';) for a TAB separated file ADelimiter should be #9.
264	264
265	265		The WithHeader parameter is used to decide if a "row header" should be included or not. The row header is a list of field names at the beginning of the output file; its content comes from the last fixed row in the grid. There is an exception to this rule: if the grid has custom columns, the row header content comes from the custom column titles and not from fixed row cell content.
266	266
267	267		If WithHeader is true and the grid does not include a fixed row or custom columns, the row header content will be taken from the first row in the grid.
268	268
269	269		Normal CSV data output will start at the first non-fixed row in the grid.
270	270
271	271		#### procedure LoadFromCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
272	272
273	273		Loads grid content from a comma separated values format (CSV) file (added in Lazarus r32179).
274	274
275	275		Columns will be added or deleted to or from the grid as needed according to the number of fields included in each line of the CSV file. Note that, in case of an empty (newly created) grid, columns will be added only if at least a single column exists already. Loading a CSV file will not modify the number of fixed rows that already existed in the grid.
276	276
277	277		The _AFileName_ argument specifies the name of the source file with the CSV content.
278	278
279	279		_ADelimiter_ optional parameter may be used to specify a different separator or delimiter. An example: for a tab-separated file, _ADelimiter_ should be #9. Another popular file format is semicolon-delimited file, where _ADelimiter_ should be ;
280	280
281	281		The _WithHeader_ parameter is used to decide if the first row in the CSV file should be considered as the "header row" or not. If the grid has fixed rows and _WithHeader_ is true, the column captions for the last fixed row will be taken from the header row. Note however that if the grid has custom columns, the header row will be used as source for the column titles and custom column titles are always shown in the grid's first fixed row or hidden if there are no fixed rows in the grid.
282	282
283	283		If the _LoadFromCSVFile_ procedure has difficulty loading your CSV file (e.g. quotes or spaces being incorrectly interpreted), you could manually load the grid using e.g. [[CsvDocument]]... and of course a patch for _LoadFromCSVFile_ is always welcome.
284	284
285	285		#### property Cols[index: Integer]: TStrings read GetCols write SetCols;
286	286
287	287		Get/set a list of strings from/to the given grid's column index starting from row index 0 to RowCount-1.
288	288
289	289		##### Examples
290	290
291	291		* Set Example: Set the content of the third column in the grid from a ListBox:
292	292
293	293		```
294	294		Grid.Cols[2] := ListBox1.Items;
295	295		```
296	296
297	297		* Get Example: Set the content of a Listbox from the grid's column index 4:
298	298
299	299		```
300	300		procedure TForm1.FillListBox1;
301	301		var
302	302		StrTempList: TStringList;
303	303		begin
304	304		StrTempList := TStringList(Grid.Cols[4]);
305	305		if StrTempList<>nil then begin
306	306		ListBox1.Items.Assign(StrTempList);
307	307		StrTempList.Free;
308	308		end;
309	309		end;
310	310		```
311	311
312	312		##### Notes.
313	313
314	314		This property works differently in Lazarus and 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.
315	315
316	316		This means also that changes in the returned list will not affect the grids content or layout.
317	317
318	318		See the Get Example.
319	319
320	320		#### property Rows[index: Integer]: TStrings read GetRows write SetRows;
321	321
322	322		Get/set a list of strings from/to the given grid's row index starting from column index 0 to column ColCount-1.
323	323
324	324		##### Notes.
325	325
326	326		This property works differently in Lazarus and 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.
327	327
328	328		This means also that changes in the returned list will not affect the grid's content or layout.
329	329
330	330		##### Examples
331	331
332	332		* Set Example: Set the content of the third row in the grid from a ListBox:
333	333
334	334		```
335	335		Grid.Rows[2] := ListBox1.Items;
336	336		```
337	337
338	338		* Get Example: Set the content of a Listbox from the grid's row index 4:
339	339
340	340		```
341	341		procedure TForm1.FillListBox1;
342	342		var
343	343		StrTempList: TStringList;
344	344		begin
345	345		StrTempList := TStringList(Grid.Rows[4]);
346	346		if StrTempList<>nil then begin
347	347		ListBox1.Items.Assign(StrTempList);
348	348		StrTempList.Free;
349	349		end;
350	350		end;
351	351		```
352	352
353	353		* An Example that doesn't work, and its Fix: Retrieved string list is read only
354	354
355	355		```
356	356		// this will not work and will cause memory leak
357	357		// because returned StringList is not being freed
358	358		Grid.Rows[1].CommaText := '1,2,3,4,5';
359	359		Grid.Rows[2].Text := 'a'+#13#10+'s'+#13#10+'d'+#13#10+'f'+#13#10+'g';
360	360
361	361		// fixing the first case
362	362		Lst:=TStringList.Create;
363	363		Lst.CommaText := '1,2,3,4,5';
364	364		Grid.Rows[1] := Lst;
365	365		Lst.Free;
366	366		```
367	367
368	368		#### property UseXORFeatures;
369	369
370	370		Boolean property, default value: False;
371	371
372	372		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]]
373	373
374	374		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.
375	375
376	376		### TValueListEditor
377	377
378	378		[[TValueListEditor]] is a control derived from TCustomStringGrid for editing Key-Value pairs.
379	379
380	380		#### Property DisplayOptions
381	381
382		-	~~Controls various aspects of the TValueListEditor's appearance.~~
	382	+	Controls various aspects of the TValueListEditor's appearance by means of a set of the following elements:
383	383
	384	+	* `doColumnTitles` : Displays column titles
	385	+	* `doAutoColResize` : Resizes column widths such that the entire client width is filled
	386	+	* `doKeyColFixed` : Keeps the width of the 1st column fixed when column widths are resized. Otherwise both columns have the same width. Requires `doAutoColSResize` to be included in the `DisplayOptions`.
	387	+
384	388		#### Property TitleCaptions
385	389
386	390		Sets the values of the title captions (if doColumnTitles is in DisplayOptions). If DisplayOptions lacks the value doColumnTitles then default captions are used.
387	391
388	392		#### Property Strings
389	393
390	394		Provides access to the list of strings that hold the Key-Value pairs.
391	395		Key-Value pairs must be in the form:
392	396		'KeyName=Value'
393	397
394	398		#### Property ItemProps
395	399
396	400		You can use this property to control how the items in the "Value" columns can be edited.
397	401		This is controlled by setting the ItemProp's EditStyle and ReadOnly properties.
398	402
399	403		#### Property KeyOptions
400	404
401	405		KeyOptions is a set of TKeyOptions controlling whether the user can modify the contents of the "Key" column.
402	406
403	407		* KeyEdit: the user can edit the name of the Key
404	408		* KeyAdd: the user can add keys (by pressing Insert in the grid). KeyAdd requires KeyEdit.
405	409		* KeyDelete: the user can delete Key-Value pairs (by pressing Ctrl+Delete).
406	410		* KeyUnique: if set, then Keys must have unique names. Attempting to enter a dulpicate Key will raise an exception.
407	411
408	412		#### Property DropDownRows
409	413
410	414		If the cell editor is a picklist (ValueEdit1.ItemProps['key1'].EditStyle=esPickList) this property sets the DropDownCount of the displayed list. The default is 8.
411	415
412	416		#### Function DeleteRow
413	417
414	418		Deletes the Key-Value pair of the indexed row removing the row entirely.
415	419
416	420		#### Function InsertRow
417	421
418	422		Inserts a row in the grid and sets the Key-Value pair. Returns the index of the newly inserted row.
419	423
420	424		#### Function IsEmptyRow
421	425
422	426		Returns true if the indexed row's cells are empty (Keys[aRow]=_; Values[aRow]=_).
423	427
424	428		#### Function FindRow
425	429
426	430		Returns the row that has the specified key name.
427	431
428	432		#### Function RestoreCurrentRow
429	433
430	434		Undoes the editing in the current row (if the editor is still focused). Happens when the user presses the Escape key.
431	435
432	436		#### Altered behaviour of some properties derived from TCustomStringGrid
433	437
434	438		##### Property Options
435	439
436	440		Due to the nature of TValueListEditor its Options property has certain restrictions
437	441
438	442		* goColMoving is not allowed in Options (you cannot set it).
439	443		* goAutoAddRows can only be set if KeyAdd is in KeyOptions. Setting KeyAdd will automatically set goAutoAddRows.
440	444		* goAutoAddRowsSkipContentCheck is not allowed (for the time being, it causes a crash in TValueListeditor: needs fixing).
441	445
442	446		##### Property FixedRows
443	447
444	448		Can only be 1 (show column titles) or 0 (don't show column titles).
445	449
446	450		##### Property ColCount
447	451
448	452		Is always 2.
449	453
450	454		##### Property Objects
451	455
452	456		It is not recommended to use this property at all.
453	457		When some (internal) code manipulates the Strings property, changes are Objects will be lost.
454	458
455	459		#### General comments on the use of TValueListEditor
456	460
457	461		When manipulating the contents of the ValueListEditor (the grid), you can manipulate the underlying Strings property directly.
458	462		Be aware however, that is you do this, you must hide the editor, otherwise the Strings may get out of sync with the contents of the grid you will see on the screen.
459	463
460	464		If you want to insert or delete rows etc. then the preferred way is to use the public methods from TValueListEditor: DeleteRow(), InsertRow(), MoveRow(), ExchangeRow() or the various Sort() methods.
461	465
462	466		Trying to use ancestor's methods to manipulate rows or columns (e.g. Columns.Add) might result in a crash.
463	467
464	468		#### Saving and loading the contenst of a TValueListEditor
465	469
466	470		##### Using the Strings property
467	471
468	472		If you just want to save and load the content of the TValueListEditor (e.g. the Key/Value pairs, not the layout) you can use Strings.SaveToFile and Strings.LoadFromFile.
469	473		In case of LoadFromFile the `RowCount` property will be autmatically adjusted.
470	474		No sanity checks are performed upon LoadFromFile (so lines that do not represent a Key/Value pair will end up as Keys without Value).
471	475
472	476		##### Using TValueList.SaveToFile and TValueList.LoadFromFile
473	477
474	478		When using SaveToFile and LoadFromFile you get the additional benefits of also being able to save and load the layout, like with other grids.
475	479		SaveToFile will also save information about wether or not the TValueListEditor uses ColumnTitles, and if so, it saves them.
476	480
477	481		In contrast to it's ancestors TValueList.LoadFromFile performs sanity checks on the file it tries to read. In particular RowCount must be specified and there cannot be a cell with RowIndex > RowCount or ColumnIndex other than 0 or 1.
478	482		If the file does not seem to be a valid TValueListEditor grid file, and exception is raised.
479	483
480	484		TValueList.SaveToFile and TValueList.LoadFromFile do not work correctly in Lazarus versions <= 2.1 r62044.
481	485
482	486		##### Using SaveToCSVFile and LoadFromCSV methods
483	487
484	488		These methods should not be used at the moment, since for a TValueListEditor they are flawed.
485	489
486	490		## Working with grids
487	491
488	492		### Customizing grids
489	493
490	494		Grid are components derived from the [TCustomControl](<http://lazarus-ccr.sourceforge.net/docs/lcl/controls/tcustomcontrol.html>) class, and don't have a native widget associated with them which means that grids are not restricted by the look of current interface theme. This can be both an advantage and a disadvantage: 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 look similar to 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 the current theme).
491	495
492	496		### Properties and Events for customizing grids
493	497
494	498		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:
495	499
496	500		* 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.
497	501		* Color. This sets the primary color used to draw non fixed cells background.
498	502		* FixedColor. This is the color used to draw fixed cells background.
499	503		* Flat. This eliminates the 3d look of fixed cells.
500	504
501	505		* TitleFont. Font used to draw the text in fixed cells.
502	506
503	507		* TitleStyle. This property changes the 3D look of fixed cells, there are 3 settings:
504	508		* _tsLazarus._ This is the default look
505	509		* _tsNative._ This tries to set a look that is conforms with the current widgetset theme.
506	510		* _tsStandard._ This style is a more contrasted look, like Delphi grids.
507	511		* 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.
508	512		* BorderColor. This sets the grid's border color used when Flat:=True and BorderStyle:=bsSingle;
509	513		* 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.
510	514
511	515		* FocusColor. The color used to draw the current focused cell if UseXORFeatures is not set, by default this is clRed.
512	516		* FocusRectVisible. Turns on/off the drawing of focused cell.
513	517		* GridLineColor. Color of grid lines in non fixed area.
514	518		* 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_.
515	519		* SelectedColor. Color used to draw cell background on selected cells.
516	520		* 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.
517	521		* DefaultDrawing. Boolean. Normally the grids prepare the grid canvas using some properties according to the kind of cell that is being painted. If the user writes an OnDrawCell event handler, a set DefaultDrawing also paints the cell background. If the user draws the cell himself, it is better to turn off this property so painting is not duplicated. In a StringGrid, a set DefaultDrawing draws the text in each cell.
518	522		* AutoAdvance. Where the cell cursor will go when pressing Enter, or after editing.
519	523		* TabAdvance. Where the cell cursor will go when pressing Tab or Shift-Tab.
520	524		* ExtendedColSizing. If true user can resize columns not just at the headers but along the columns height.
521	525
522	526		Other properties that also affect the grids look.
523	527
524	528		Options.
525	529
526	530		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.
527	531
528	532		* goFixedVertLine, goFixedHorzLine it draws a vertical or horizontal line respectively delimiting cells or columns in fixed area, active by default.
529	533		* goVertLine, goHorzLine the same as previous, but for normal browseable area. A grid can be made to simulate a listbox by unsetting both of this elements.
530	534		* 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)
531	535		* goRowSelect select the full row instead of individual cells
532	536		* goFixedRowNumbering if set, grid will do numbering of rows in first fixed column
533	537		* 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.
534	538		* goHeaderPushedLook if set, this element enables a pushed look when clicking any fixed cell. The zone of "pushable" cells is enabled using HeaderPusedZones property.
535	539
536	540		(write more)
537	541
538	542		### Description of grid's drawing process
539	543
540	544		Like other custom controls, the grid is drawn using the paint method. In general terms the grid is drawn by painting all rows, and each row by painting its individual cells.
541	545
542	546		The process is as follow:
543	547
544	548		* 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 the visible area is painted by drawing columns of each row.
545	549		* 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 the clippling region; if everything is ok, some additional properties like the cell's rectangular extent and visual state are passed as arguments to the DrawCell method.
546	550		* 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 retained in a varible of type TGridDrawState which is a set with following elements:
547	551		* _gdSelected_ The cell will have a selected look.
548	552		* _gdFocused_ The cell will have a focused look.
549	553		* _gdFixed_ Cell have to be painted with fixed cell look.
550	554		* _gdHot_ the mouse is over this cell, so paint it with hot tracking look
551	555		* _gdPushed_ the cell is being clicked, paint it with pushed look
552	556		* DrawCell. The DrawCell method is virtual and may be overriden in descendant grids to do custom drawing. The information passed to DrawCell helps to identify the particular cell is being painted, the physical area ocuppied in screen and its visible status. See DrawCell reference for details. For each cell the following occurs:
553	557		* PrepareCanvas. In this method, if the DefaultDrawing property is set, the grid canvas is setup with default properties for brush and font based on current visual state. For 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.
554	558		* OnPrepareCanvas. If the programmer wrote an event handler for OnPrepareCanvas event, it is 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 using the 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?...
555	559		* OnDrawCell. Next if no handler for OnDrawCell event was specified, the grid calls the DefaultDrawCell method which simply paints the cell background using the current canvas brush color and style. If the 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.
556	560		* Text. At this point (only for TStringGrid) if DefaultDrawing property is true, the cell's text content is painted.
557	561		* 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 the programmer elected to have a "themed" look it is done at this point also (see property TitleStyle).
558	562		* FocusRect. When all columns of current row have been painted it is time to draw the focus rectangle for the current selected cell or for the whole row if goRowSelect option is set.
559	563
560	564		#### Differences with Delphi
561	565
562	566		* In Lazarus TCustomGrid.DrawCell method is not abstract and its default implementation does basic cell background filling.
563	567		* 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>)).
564	568
565	569		### Grid's cell selection
566	570
567	571		The location of a grid's current (focused) cell (or row) can be changed using keyboard, mouse or through code. In order to change cell focus successfully to another position, we must test the target position to see if it is allowed to receive cell focus. When using keyboard, the property AutoAdvance performs part of the process by finding what should be the next focused cell. When using mouse clicks or moving by code, focus will not move from the current cell unless the target cell is permitted to receive focus.
568	572
569	573		The grid calls function SelectCell to see if a cell is focusable: if this function returns true, then the target cell identified with arguments aCol and aRow is focusable (the current implementation of 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 these characteristics is skipped automatically in the process of finding a suitable cell. The other thing the overridden method SelectCell does is to call the user configurable event OnSelectCell: this event receives the cell coordinates as arguments and always returns a default result value of true.
570	574
571	575		Once a cell is known to be focusable and we are sure a movement will take place, first the method BeforeMoveSelection is called; this in turns triggers the OnBeforeSelection event. This method's arguments are the coordinates for the new focused cell. 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.
572	576
573	577		After that, the internal focused cell coordinates are changed and then MoveSelection method is called; this method's purpose is to trigger the OnSelection event if set (this is a notification that the focused cell has, by this time, already changed and cell coordinates are now available through grid.row and grid.col properties).
574	578
575	579		Note that is not good to use OnSelectCell event to detect cell focus changes, as 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.
576	580
577	581		#### Differences with Delphi
578	582
579	583		* SelectCell and OnSelectCell behaviour is probably different - can't really comment on the differences. In Lazarus they are used in functionality like AutoAdvance which as far as I know doesn't exist in Delphi.
580	584
581	585		### When built-in properties are not enough: derived grids
582	586
583	587		Derived grids usually have to override the following methods:
584	588		DrawAllRows: Draws all visible rows.
585	589		DrawRow: Draws all cells in a row.
586	590		DrawRow draws all cells in the row by first checking if cell is within clipping region, and only draws the cell if it is.
587	591		DrawCell:
588	592		DrawCellGrid:
589	593		DrawCellText:
590	594		DrawFocusRect:
591	595		(write me).
592	596
593	597		### What happens in the `TCustomGrid.Paint` method?
594	598
595	599		The following list is to show the internal order of method calls for painting a `TCustomGrid` (or descendant). Every item in the lists represents method calls during the paint operation. This ought to help finding the right point to change behaviour when it comes to descending from `TCustomGrid`.
596	600
597	601		* `DrawEdges` : Draws the grid's outer border.
598	602		* `DrawAllRows` (virtual): Draws all rows in the visible part of the grid. This is the only method called in the painting process that is declared _`virtual`_.
599	603		* `DrawRow` (virtual): Is called for each row inside the current viewport.
600	604		* `DrawCell` (virtual): Is first called for each 'normal' (i.e. not fixed) cell in the row.
601	605		* `PrepareCanvas` (virtual): Sets the canvas's drawing styles according to the current cell's visual properties.
602	606		* `DrawFillRect` : Draws the cell's background with the styles set in `PrepareCanvas`.
603	607		* `DrawCellGrid` (virtual): Draws the cell's border lines.
604	608		* `DrawFocusRect` (virtual): In `TCustomGrid` this method does nothing. In descendent grids this method is used to draw the focus rectangle inside the active cell.
605	609		* `DrawCell` (virtual): (see above) Is called for each fixed cell in the row's visible viewport.
606	610		* `DrawColRowMoving` : only active while moving a column or row. This method draws the line that indicates the row's/column's new position.
607	611		* `DrawBorder` : If needed (`Flat=TRUE` and `BorderStyle=bsSingle`), this draws an inner border line.
608	612
609	613		#### Additional methods to draw in `TCustomGrid`
610	614
611	615		These methods are declared and (partly) implemented in `TCustomGrid`, but they are not called directly from here. They are used by descendant classes to draw the cell's content.
612	616
613	617		* `DrawCellText` (virtual): Writes/draws the text that is passes as parameter into the cell. The text is formatted by using the styles that are active in `Canvas.TextStyle` (see also `PrepareCanvas`).
614	618		* `DrawThemedCell` (virtual): Is only used for fixed cells and if `TitleStyle=tsNative`. It draws the cell's background using `ThemeServices`.
615	619		* `DrawColumnText` (virtual): Is only used for column header cells.
616	620		* `DrawColumnTitleImage` : If the grid as an assigned `TitleImageList` and `Columns.Title[x].Title.ImageIndex` contains a valid value, that image is drawn into the cell.
617	621		* `DrawCellText` : (see above)
618	622		* `DrawTextInCell` (virtual): Is used for 'normal' (i.e. not fixed) cells.In `TCustomGrid` this method does nothing. In descendent grids this method is used to draw the cells content. In `TStringGrid` theis method calls `DrawCellText` (see above).
619	623
620	624		#### Drawing methods introduced by `TCustomDrawGrid`
621	625
622	626		As you can see the base class `TCustomGrid` does not draw any content into the cells. This is done in `TCustomDrawGrid`. `TCustomDrawGrid` overrides the method `DrawCell` in the following way:
623	627
624	628		* `DrawCell` (override):
625	629		* `PrepareCanvas` : calls the inherited method from `TCustomGrid`.
626	630		* `DefaultDrawCell` (virtual): This method is only called if the event handler for `OnDrawCell` is NOT assigned.
627	631		* `DrawFillRect / DrawThemedCell` (von `TCustomGrid`): Draws the cell's background. If `TitleStyle=tsNative`, the background of fixed cells is drawn using `DrawThemedCell`.
628	632		* `DrawCellAutonumbering` (virtual): If `goFixedAutonumbering in Options`, row numbers are drawn into the first fixed column using `TCustomGrid.DrawCellText`.
629	633		* `DrawColumnText` (from `TCustomGrid`): Is only called for column header cells (see _Additional methods to draw in` TCustomGrid`_).
630	634		* `DrawTextInCell` (from `TCustomGrid`): Is only called for 'normal' (i.e. not fixed) cells (see _Additional methods to draw in` TCustomGrid`_).
631	635		* `DrawCellGrid` (virtual): Draws the cell's borders
632	636
633	637		### Save and Retrieve Grid Content
634	638
635	639		The SaveToFile and LoadFromFile methods allows a grid to save and retrieve it's layout and data to/from a XML format file. TStringGrid, as inherited from TCustomStringGrid, has also the ability to "export" and "import" its content to/from a Comma Separated Values format file, best known as CSV files. This is described in the SaveToCSVFile and LoadFromCSVFile methods reference (TODO: make links).
636	640
637	641		The kind of information that can be saved and then retrieved when using SaveToFile and LoadFromFile is determined by the SaveOptions property (of type TSaveOptions) which is a set of options described as follows:
638	642		```
639	643		soDesign: Save & load ColCount,RowCount,FixedCols,FixedRows,
640	644		ColWidths, RowHeights and Options (TCustomGrid)
641	645		soPosition: Save & load Scroll position, Row, Col and Selection (TCustomGrid)
642	646		soAttributes: Save & load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)
643	647		soContent: Save & load Text (TCustomStringGrid)
644	648		soAll: set of all options (soAll:=[soDesign,soPosition,soAttributes,soContent];)
645	649		```
646	650
647	651		Not all options apply to all kind of grids, for example, soContent do not apply to TCustomGrid derived grids like TDrawGrid as this kind of grid does not have the concept of "content". TStringGrid is a special kind of grid that "knows" how to handle strings and can use the soContent option if specified.
648	652
649	653		The soAttributes option is not used in Lazarus standard grids, is there for derived grids.
650	654
651	655		When using LoadFromFile the grid also uses the SaveOptions property in order to know what kind of information needs to retrieve from the file, so is perfectly possible to specify SaveOptions:=[soDesign,soContent] on saving and only SaveOptions:=[soContent] on loading.
652	656
653	657		For a TStringGrid the default SaveOptions value is [soContent], for other kind of grids, SaveOptions is the empty set.
654	658
655	659		Note: One common issue when saving & retrieving grid data occurs when the user specify the SaveOptions property before SaveToFile but not before LoadFromFile. When using LoadFromFile some time after SaveToFile have been used, the SaveOptions property is properly set, but if LoadFromFile is executed on next program run, the SaveOptions property might not have been properly setup, for this reason is recommended to always specify SaveOptions property just before LoadFromFile , or doing it globally at program start like in the following example:
656	660
657	661		* * *
658	662
659	663		Example:
660	664
661	665		1. First, go to menu "File -> New -> Application";
662	666		2. Put an empty TStringGrid on the form;
663	667		3. Put a TButton and TOpenDialog on the form;
664	668		4. Add the event OnCreate for the form;
665	669		5. Add the event OnClick for the button.
666	670
667	671		```
668	672		unit Unit1;
669	673
670	674		{$mode objfpc}{$H+}
671	675
672	676		interface
673	677
674	678		uses
675	679		Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, Grids,
676	680		Buttons, StdCtrls, XMLCfg;
677	681
678	682		type
679	683
680	684		{ TForm1 }
681	685		TForm1 = class(TForm)
682	686		StringGrid1: TStringGrid;
683	687		Button1: TButton;
684	688		OpenDialog1: TOpenDialog;
685	689		procedure Button1Click(Sender: TObject);
686	690		procedure Form1Create(Sender: TObject);
687	691		private
688	692		{ private declarations }
689	693		public
690	694		{ public declarations }
691	695		end;
692	696
693	697		var
694	698		Form1: TForm1;
695	699
696	700		implementation
697	701
698	702		{ TForm1 }
699	703
700	704		procedure TForm1.Form1Create(Sender: TObject);
701	705		begin
702	706		//sets the SaveOptions at creation time of the form
703	707		stringgrid1.SaveOptions := [soDesign,soPosition,soAttributes,soContent];
704	708		end;
705	709
706	710
707	711		procedure TForm1.Button1Click(Sender: TObject);
708	712		begin
709	713		//Ask if thew Execute method of the OpenDialog was launched
710	714		//when this occurs, the user selects an XML file to Load
711	715		//wich name was stored in the FileName prop.
712	716
713	717		if opendialog1.Execute then
714	718		begin
715	719		//Clear the grid
716	720		StringGrid1.Clear;
717	721		//Load the XML
718	722		StringGrid1.LoadFromFile(OpenDialog1.FileName);
719	723		//Refresh the Grid
720	724		StringGrid1.Refresh;
721	725		end;
722	726		end;
723	727
724	728		initialization
725	729		{$I unit1.lrs}
726	730
727	731		end.
728	732		```
729	733
730	734		* * *
731	735
732	736		The sample xml file: (Copy the text below into a txt file. Don't forget put the xml header :-))
733	737		```
734	738		<?xml version="1.0"?>
735	739		<CONFIG>
736	740		<grid version="3">
737	741		<saveoptions create="True" position="True" content="True"/>
738	742		<design columncount="2" rowcount="5" fixedcols="1" fixedrows="1" defaultcolwidth="64" defaultRowHeight="20">
739	743		<options>
740	744		<goFixedVertLine value="True"/>
741	745		<goFixedHorzLine value="True"/>
742	746		<goVertLine value="True"/>
743	747		<goHorzLine value="True"/>
744	748		<goRangeSelect value="True"/>
745	749		<goDrawFocusSelected value="False"/>
746	750		<goRowSizing value="False"/>
747	751		<goColSizing value="False"/>
748	752		<goRowMoving value="False"/>
749	753		<goColMoving value="False"/>
750	754		<goEditing value="False"/>
751	755		<goTabs value="False"/>
752	756		<goRowSelect value="False"/>
753	757		<goAlwaysShowEditor value="False"/>
754	758		<goThumbTracking value="False"/>
755	759		<goColSpanning value="False"/>
756	760		<goRelaxedRowSelect value="False"/>
757	761		<goDblClickAutoSize value="False"/>
758	762		<goSmoothScroll value="True"/>
759	763		</options>
760	764		</design>
761	765		<position topleftcol="1" topleftrow="1" col="1" row="1">
762	766		<selection left="1" top="1" right="1" bottom="1"/>
763	767		</position>
764	768		<content>
765	769		<cells cellcount="10">
766	770		<cell1 column="0" row="0" text="Title Col1"/>
767	771		<cell2 column="0" row="1" text="value(1.1)"/>
768	772		<cell3 column="0" row="2" text="value(2.1)"/>
769	773		<cell4 column="0" row="3" text="value(3.1)"/>
770	774		<cell5 column="0" row="4" text="value(4.1)"/>
771	775		<cell6 column="1" row="0" text="Title Col2"/>
772	776		<cell7 column="1" row="1" text="value(1.2)"/>
773	777		<cell8 column="1" row="2" text="value(2.2)"/>
774	778		<cell9 column="1" row="3" text="value(3.2)"/>
775	779		<cell10 column="1" row="4" text="value(4.2)"/>
776	780		</cells>
777	781		</content>
778	782		</grid>
779	783		</CONFIG>
780	784		```
781	785
782	786		### Grid Cell Editors
783	787
784	788		The grid uses cell editors to change the content of cells.
785	789
786	790		For a specialized grid like TStringGrid, the editor is the usual single line text editor control, but sometimes it's desirable to have other means to enter information. For example:
787	791
788	792		1. show the open file dialog to find the location of a file so the user doesn't have to type the full path manually
789	793		2. if the text in the cell represents a date, popup a calendar so we can choose a specific date easily.
790	794
791	795		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 validation routines might need to be implemented. We can avoid this by using a cell editor that presents the user with a list containing only the legal values.
792	796
793	797		This is also the case for generic grids like TDrawGrid where the user needs 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.
794	798
795	799		#### Builtin cell editors
796	800
797	801		The grids.pas unit already includes some of the most used cell editors ready for use in grids. It is also possible to create new cell editors (custom cell editors) if the built-in editors are not appropiate for a specific task.
798	802
799	803		The built-in cell editors are Button, Edit, and Picklist.
800	804
801	805		#### Using cell editors
802	806
803	807		Users can specify what editor will be used for a cell using one of two methods.
804	808
805	809		1. Using a custom column and selecting the ButtonStyle property of the column. In this method the user can select the style of the editor that will be shown. Available values are: cbsAuto, cbsEllipsis, cbsNone, cbsPickList, cbsCheckboxColumn, cbsButtonColumn.
806	810		2. Using OnSelectEditor grid event. Here the user specifies in the Editor parameter which editor to use for a cell identified 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, cbsButtonColumn. This method takes precedence over the first one using custom columns. A custom cell editor can be specified here (see chapter 5 of [this document](<http://www.freepascal.org/~michael/articles/grids/grids.pdf>) by Michaël Van Canneyt which explains how to correctly implement a custom editor). This event is also the place to setup the editor with values specific to the cell, row or column (e.g. a custom popupmenu for the cell editor).
807	811
808	812		Setting the _ButtonStyle_ property only works if a column is created with the _StringGrid1.Columns.Add;_ statement. Using expression like _StringGrid1.ColCount:=X;_ will cause an exception. Setting the ButtonStyle property can be done with a similar code:
809	813		```
810	814		if ColCB< StringGrid1.Columns.Count
811	815		then StringGrid1.Columns.Items[ColCB].ButtonStyle:=cbsCheckboxColumn;
812	816		```
813	817
814	818		#### Description of editor styles
815	819
816	820		The following is a description of the editor styles. They are enumerated values of type TColumnButtonStyle and so they are prefixed by 'cbs'. This type was used to remain compatible with Delphi's DBGrid.
817	821
818	822		* cbsAuto
819	823
820	824		This is the default editor style for TCustomGrid derived grids. The actual editor class that will be used to edit the cell content depends on several factors. For TCustomGrids it uses a TStringCellEditor class derived from TCustomMaskEdit. This editor is specialized to edit single line strings. It is then used in TStringGrid and TDrawGrid by default. When using Custom Columns, if the programmer filled the Column's PickList property, this behaves as if cbsPickList editor style was set. For a TCustomDBGrid that has a field of type boolean, it behaves as if cbsCheckBoxColumn editor style was specified. This is the recommended value for Custom Cell Editors. TODO: related OnEditingDone.
821	825
822	826		* cbsEllipsis
823	827
824	828		This editor style is the most generic one. When used, a button appears in the editing cell and programmers could use the OnEditButtonClick grid event to detect when the user has pressed the button and take any action programmed for such a cell. For example a programmer could use this editor style to pop up a calendar dialog to allow the user easily to select a specific date. Other possibilities could be to show a file open dialog to find files, a calculator so user can enter the numeric result of calcs, etc.
825	829
826	830		OnEditButtonClick is just a notification, to find out in which cell a button has been clicked by taking a look at the grid.Row and grid.Col properties.
827	831
828	832		A DBGrid has specific properties to retrieve the active column or field and because this event occurs in the active record, it could update the information in the active field.
829	833
830	834		This editor style is implemented using TButtonCellEditor, a direct descendant of TButton.
831	835
832	836		* cbsNone
833	837
834	838		This editor style instructs the grid not to use any editor for a specific cell or column; it behaves then, as if the grid were readonly for such a cell or column.
835	839
836	840		* cbsPickList
837	841
838	842		Used to present the user with a list of values that can be entered. This editor style is implemented using TPickListCellEditor, a component derived from TCustomComboBox. The list of values that are shown is filled in one of two ways depending on the method used to select the editor style.
839	843
840	844		1. 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]
841	845		2. In OnSelectEditor, programmers get the TPickListCellEditor instance using the function EditorByStyle(cbsPickList). See here for an example
842	846
843	847		The value in a TStringGrid grid will automatically reflect the value selected. If necessary the programmer could detect the moment the value is selected by writing an event handler for the grid's OnPickListSelect event, so additional steps can be taken (for example, to process the new value). TODO: related OnEditingDone.
844	848
845	849		* cbsCheckboxColumn
846	850
847	851		It can be useful when the data content associated with the column is 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 data in a StringCellEditor or to choose one from a list, cbsCheckboxColumn is used to modify the data of a column by using a checkbox representation that the user can toggle by using a mouse click or pressing the SPACE key (if the column, containing the checkbox is selected and if the StringGrid is editable).
848	852
849	853		Getting or setting the value of the checkbox in a cell is done the following way:
850	854		```
851	855		StringGrid1.Cell[x,y]:='Z';
852	856		```
853	857
854	858		where Z shall be replaced by _0_ for Unchecked, _1_ for Checked and an empty string for Grayed. Note that any value (string) different from _0_ and _1_ will be displayed as a grayed checkbox.
855	859
856	860		If a columns' ButtonStyle property is set to cbsAuto and DBGrid detects that the field associated with the column is a boolean field, then the grid uses this editor style automatically. This automatic selection can be disabled or enabled using DBGrid's OptionsExtra property; setting dgeCheckboxColumn element to false disables this feature.
857	861
858	862		The values that are used to recognize the checked or unchecked states are set in a column's properties ValueChecked and ValueUnchecked.
859	863
860	864		At any moment, the field value can be in one to three states: Unchecked, Checked or Grayed. Internally these states are identified by the following values of type TDBGridCheckBoxState: gcbpUnChecked, gcbpChecked and gcbpGrayed.
861	865
862	866		This editor style doesn't use real TCheckbox components to handle user interaction: the visual representation is given by three built-in 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 the parameter CheckedState of type TDBGridCheckboxState and a bitmap parameter that the programmer could use to specify custom bitmaps.
863	867
864	868		* cbsButtonColumn
865	869
866	870		This editor style is used to show a button on every cell on column. Like in the case of cbsCheckboxColumn this editor do not use real buttons, the appearance is defined by current widgetset theme.
867	871
868	872		The user knows what particular button was pressed by handling the grid's OnEditButtonClick and checking grid's col and row. Note that in this particular case, grid's col and row do not identify the currently selected cell, but the cell of the clicked button. Once the OnEditButtonClick event has been handled, and if the user has not modified the grid's col or row in this handler, the grid automatically resets the col and row to reflect the currently selected cell. While handling the OnEditButtonClick the current grid selection is available in grid.Selection which is a TRect property, left and right represent Column indexes, Top and Bottom are row indexes.
869	873
870	874		The button's caption is the corresponding cell string.
871	875
872	876		### Editing grids
873	877
874	878		The effect of editing is different depending on what kind of grid is used, for example, TStringGrid stores the edited text internally and TDBGrid affects records in a dataset. TDrawGrid doesn't know what to do with the edited text, if the programmer do not take control on it, it's simply discarded.
875	879		For TDrawGrid (although this should work for all grid classes) in order to access the edited text, the programmer can use the event OnSetEditText which is triggered every time the user modify something in the editor, the _aCol_ and _aRow_ parameters of this event identify the cell being edited, the parameter _value_ holds the text, this is the recommended method. Another way of access the edited text is taking it directly from the editor once the editing process has ended by using the event OnEditingDone. This could be accomplished by accessing the internal editor used for editing, in this case, the default "String Cell Editor". For this, there are two methods: The first is by using the event OnSelectEditor where the parameter _Editor_ is the instance which will be used to edit a cell, you have to store this instance in a variable, for example TheEditor (of type _TStringCellEditor_), for later use in OnEditingDone. The second alternative is using the grid's method EditorByStyle , this method accepts an "editor style" as parameter and it returns the instace of the editor corresponding to that style. In our case knowing that the style cbsAuto returns the default cell editor, in the OnEditingDone event handler we can use directly TheEditor := Grid.EditorByStyle(cbsAuto). You can then get the text with _TheEditor.Text_. If you use this method note that "with great power, comes great responsibility".
876	880
877	881		#### Options and properties that affect editing
878	882
879	883		The editing behavior is controlled by a number of properties and options, virtually any adjustment or options that affects editing requires an editable grid or such adjustment might be ignored.
880	884		At start the editable state of the grids is different, for TDrawGrid and TStringGrid editing is disabled, for TDbGrid is enabled by default.
881	885		The Options property has several items that deal with editing, they are described below:
882	886
883	887		* goEditing, dgEditing (in DbGrid). This option changes the editable state of the grid, can be changed at runtime because it is checked when editing is about to be started.
884	888		* goAlwaysShowEditor. Normally the editor is hidden and it becomes visible only when it's needed. With this option, the editor will be visible all the time, if grid is not editable, this option is ignored and editor is always hidden.
885	889
886	890		### Cell hints
887	891
888	892		In addition to the standard hint of most controls, the descendants of TCustomGrid can display a special hint for the cell over which the mouse hovers. This feature is controlled by the grid options goCellHints and goTruncCellHints (or dgCellHints and gdTruncCellHints for DBGrid, respectively):
889	893
890	894		* goCellHints evaluates the event OnGetCellHint to retrieve the displayed text for the cell specified by the passed parameters. In case of the TDrawGrid and the TStringGrid, column and row indexes are given, while in case of the TDBGrid the cell text can be extracted from the Field assigned to the specified column object.
891	895		* goTruncCellHints displays a hint only if the text does not fit into a cell and is truncated; the hint text is the untruncated cell text. In Lazarus 1.9+, this text is passed to the event OnGetCellHint for further refinement (e.g. display the entire text of a memo in the hint). In case of the truncated cell texts, it is recommended to also activate the option goCellEllipsis (or dgCellEllipsis for DBGrid) which adds a '...' to the truncated cell text.
892	896
893	897		If the grid has a value in its standard property Hint then the property HintPriority can be used to control how all these hint texts can be combined into a single popup window:
894	898
895	899		* chpAll puts the standard Hint into the first line, the hint determined by the OnGetCellHint event into the second line, and the hint for the truncated cells into the third line
896	900		* chpAllNoDefault displays only the cell hints given by the OnGetCellHint event and by the truncated cells.
897	901		* chpTruncOnly displays only hints for the truncated cells; this is the default settings.
898	902
899	903		In addition, the standard property ShowHint of the grid must be set to true in order to show cell hints.
900	904
901	905		## Grids Howto and Examples
902	906
903	907		### Focusing a cell
904	908
905	909		Focusing a cell in TStringGrid is easy. Note that counting starts from zero not 1. So to focus the cell in the 10th row and the 9th column, do:
906	910		```
907	911		StringGrid1.Row := 9;
908	912		StringGrid1.Col := 8;
909	913		```
910	914
911	915		### Example: How to set a custom cell editor
912	916
913	917		See lazarus/examples/gridexamples/gridcelleditor/gridcelleditor.lpi (from laz 1.2)
914	918
915	919		### Example: How to add a button editor
916	920		```
917	921		// Conditionally show button editor in column index 1 or 2 if
918	922		// cell in column index 1 is empty
919	923		procedure TForm1.StringGrid1SelectEditor(Sender: TObject; aCol, aRow: Integer;
920	924		var Editor: TWinControl);
921	925		begin
922	926		if (aCol = 1) or (aCol = 2) then
923	927		if StringGrid1.Cells[1,aRow] = '' then
924	928		begin
925	929		Editor := StringGrid1.EditorByStyle(cbsEllipsis);
926	930		end;
927	931		end;
928	932
929	933		// Triggering Action ...
930	934		procedure TForm1.StringGrid1EditButtonClick(Sender: TObject);
931	935		begin
932	936		if StringGrid1.Col = 1 then Showmessage('column 1 editor clicked');
933	937		if StringGrid1.Col = 2 then Showmessage('column 2 editor clicked');
934	938		end;
935	939		```
936	940
937	941		### Example: Working with Picklist, How to make it read only and How to fill it at run time
938	942
939	943		Using grid's event OnSelectEditor one can customize how PickList editor (see cbsPickList button style) behaves. In next example the picklist editor from column 1 is modified so on odd rows the user can enter values by typing, on even rows the values are limited to the ones contained in its list. Also, this example show how to fill the list with different values depending on the row being processed.
940	944		```
941	945		procedure TForm1.gridSelectEditor(Sender: TObject; aCol, aRow: Integer;
942	946		var Editor: TWinControl);
943	947		begin
944	948		if aCol=1 then begin
945	949		Editor := StringGrid1.EditorByStyle(cbsPickList);
946	950		if (Editor is TCustomComboBox) then
947	951		with Editor as TCustomComboBox do begin
948	952		if (aRow mod 2=0) then
949	953		Style := csDropDown
950	954		else
951	955		Style := csDropDownList;
952	956		case aRow of
953	957		1:
954	958		Items.CommaText := 'ONE,TWO,THREE,FOUR';
955	959		2:
956	960		Items.CommaText := 'A,B,C,D,E';
957	961		3:
958	962		Items.CommaText := 'MX,ES,NL,UK';
959	963		4:
960	964		Items.CommaText := 'RED,GREEN,BLUE,YELLOW';
961	965		end;
962	966		end;
963	967		end;
964	968		end;
965	969		```
966	970
967	971		### Aligning text in StringGrids
968	972
969	973		This code shows how to use different text alignments in columns 2 and 3.
970	974		```
971	975		procedure TForm1.StringGrid1PrepareCanvas(sender: TObject; aCol, aRow: Integer;
972	976		aState: TGridDrawState);
973	977		var
974	978		MyTextStyle: TTextStyle;
975	979		begin
976	980		if (aCol=2) or (aCol=3) then
977	981		begin
978	982		MyTextStyle := StringGrid1.Canvas.TextStyle;
979	983		if aCol=2 then
980	984		MyTextStyle.Alignment := taRightJustify
981	985		else
982	986		if aCol=3 then
983	987		MyTextStyle.Alignment := taCenter;
984	988		StringGrid1.Canvas.TextStyle := MyTextStyle;
985	989		end;
986	990		end;
987	991		```
988	992
989	993		### Multilines in Grids
990	994
991	995		This sample shows how to make multilined text in cell [3,2]. It works the same for DBGrid where OnPrepareCanvas have parameters for dealing with TColumns and from there with TFields.
992	996		```
993	997		procedure TForm1.StringGrid1PrepareCanvas(sender: TObject; aCol, aRow: Integer;
994	998		aState: TGridDrawState);
995	999		var
996	1000		MyTextStyle: TTextStyle;
997	1001		begin
998	1002		if (aRow=2) or (aCol=3) then
999	1003		begin
1000	1004		MyTextStyle := StringGrid1.Canvas.TextStyle;
1001	1005		MyTextStyle.SingleLine := false;
1002	1006		StringGrid1.Canvas.TextStyle := MyTextStyle;
1003	1007		end;
1004	1008		end;
1005	1009		```
1006	1010
1007	1011		### Validating Entered Values
1008	1012
1009	1013		Lazarus version 0.9.29 introduces the StringGrid OnValidateEntry event of type TValidateEntryEvent which has the following declaration:
1010	1014		```
1011	1015		type
1012	1016		TValidateEntryEvent = procedure(sender: TObject; aCol, aRow: Integer; const OldValue: string; var NewValue: string) of object;
1013	1017		```
1014	1018		```
1015	1019		aCol,aRow are the cell coordinates of cell being validated.
1016	1020		OldValue is the value that was in cells[aCol,aRow] before editing started.
1017	1021		NewValue is the value that will be finally inserted in cells[aCol,aRow].
1018	1022		```
1019	1023
1020	1024		Because of the way StringGrid works by setting the cell value while user is editing (see grid's OnSetEditText event and SetEditText method), when the OnValidateEntry event triggers, the cell already contains the entered value (valid or not); using the event arguments OldValue and NewValue the cell value can be validated and changed if needed.
1021	1025
1022	1026		Usually validation occurs when the user has moved to another cell. If validation then fails, it is desirable to keep the cell editor visible/focused so the entered value can be corrected by user. To let the grid know that validation has failed, an exception needs to be raised. The grid will handle the exception to Application.HandleException and any movement is cancelled.
1023	1027
1024	1028		For example, suppose that cell[1,1] should hold only values 'A' or 'B', validation could be made with:
1025	1029		```
1026	1030		procedure TForm1.GridValidateEntry(sender: TObject; aCol,
1027	1031		aRow: Integer; const OldValue: string; var NewValue: String);
1028	1032		begin
1029	1033		if (aCol=1) and (aRow=1) then begin
1030	1034		if grid.Cells[aCol,aRow]<>'A') and grid.Cells[aCol,aRow]<>'B') then begin
1031	1035		// set a new valid value so user can just press RETURN to continue for example.
1032	1036		NewValue := 'A';
1033	1037		// another option is reverting to previous cell value (which is assumed to be valid)
1034	1038		// NewValue := OldValue;
1035	1039		// Use EAbort rather than another Exception type to avoid spurious error
1036	1040		// dialog boxes and backtraces
1037	1041		raise EAbort.Create('Only A or B are allowed here');
1038	1042		end else begin
1039	1043		// if no exception is raised, it is assumed the value is valid, yet if necessary
1040	1044		// the final value can still be changed by filling NewValue with a different value
1041	1045
1042	1046		// computer knows better :)
1043	1047		if grid.Cells[1,1]='A' then
1044	1048		NewValue := 'B'
1045	1049		else
1046	1050		NewValue := 'A';
1047	1051		end;
1048	1052		end;
1049	1053		end;
1050	1054		```
1051	1055
1052	1056		### Sorting Columns or Rows
1053	1057
1054	1058		Property ColumnClickSorts allows grid to be sorted automatically when user clicks a column header. Clicking the same column many times switches the sort order. Default column sort images are shown to indicate which column was clicked.
1055	1059
1056	1060		In code you can use SortColRow() method.
1057	1061
1058	1062		The first parameter, IsColumn, is a boolean value which indicates:
1059	1063
1060	1064		* True if a column is to be sorted
1061	1065		* False if a row is to be sorted.
1062	1066
1063	1067		The second parameter, index, is an integer value:
1064	1068
1065	1069		* Index Indicates Column or Row to be sorted.
1066	1070
1067	1071		The last two parameters are optional, defines subrange of rows or columns to be sorted.
1068	1072
1069	1073		* FromIndex (From column or row)
1070	1074		* ToIndex (To column or row)
1071	1075
1072	1076		If the last two parameters are not specified, the whole column or row is sorted.
1073	1077
1074	1078		Sorting uses QuickSort algorithm, it could be changed if a descendant grid overrides the sort() method and calls doCompareCells for cell compare.
1075	1079
1076	1080		By default it sorts cell content as strings either in ascending or descending order which is selectable with property SortOrder. By default it uses ascending order.
1077	1081		```
1078	1082		// Sort column 3 in ascending order
1079	1083		grid.SortColRow(true, 3);
1080	1084
1081	1085		// Sort column 3 in descending order, skip fixed rows a top
1082	1086		grid.SortOrder := soDescending; // or soAscending
1083	1087		grid.SortColRow(true, 3, grid.FixedRows, grid.RowCount-1);
1084	1088		```
1085	1089
1086	1090		For custom sorting of numbers, dates, states, etc: StringGrid has the OnCompareCells event which users can handle for example this way:
1087	1091		```
1088	1092		procedure TForm1.GridCompareCells(Sender: TObject; ACol, ARow, BCol, BRow: Integer; var Result: integer);
1089	1093		begin
1090	1094		// Result will be either <0, =0, or >0 for normal order.
1091	1095		result := StrToIntDef(Grid.Cells[ACol,ARow],0)-StrToIntDef(Grid.Cells[BCol,BRow],0);
1092	1096		// For inverse order, just negate the result (eg. based on grid's SortOrder).
1093	1097		if StringGrid1.SortOrder = soDescending then
1094	1098		result := -result;
1095	1099		end;
1096	1100		```
1097	1101
1098	1102		You can use OnCompareCells also when automatic column sorting is enabled through ColumnClickSorts property.
1099	1103
1100	1104		### Override automatic sort (ColumnClickSorts set to False). Avoid sort of some columns. Show sort arrows in column header
1101	1105
1102	1106		(ColumnClickSorts set to False will NOT show sort arrows in column header, so we have to set the arrows.)
1103	1107		```
1104	1108		procedure TForm1.StringGrid1HeaderClick(Sender: TObject; IsColumn: Boolean;
1105	1109		Index: Integer);
1106	1110		begin
1107	1111		if isColumn then with StringGrid1 do
1108	1112		begin
1109	1113		col:=Index; // Set column to sort
1110	1114		if Tag = 0 then Tag :=-1 // Suppose data in column is Ascending
1111	1115		else Tag := Tag * -1; // Using StringGrid1.Tag to hold sortorder
1112	1116		// First click of header will sort descending
1113	1117
1114	1118		// Activate CompareCells (ativate the sort)
1115	1119		case Index of
1116	1120		0: col:=-1; // Do not sort column 0 and do not show sort arrow
1117	1121		1: SortColRow(True, Index); // The sort will take place in CompareCells as soon as statement is executed
1118	1122		2: SortColRow(True, Index);
1119	1123		3: SortColRow(True, Index);
1120	1124		4: SortColRow(True, Index);
1121	1125		5: col:=-1; // Do not sort column 5 and do not show sort arrow
1122	1126		end;
1123	1127		end;
1124	1128		end;
1125	1129
1126	1130		// Compare returns one of the following values:
1127	1131		// if A<B return: -1 ( Ascending )
1128	1132		// if A=B return: 0
1129	1133		// if A>B return: 1 ( Descending)
1130	1134
1131	1135		// How to sort: Text, Integer, Float, DateTime:
1132	1136
1133	1137		procedure TForm1.StringGrid1CompareCells(Sender: TObject; ACol, ARow, BCol,
1134	1138		BRow: Integer; var Result: integer);
1135	1139
1136	1140		function CompareTextAsText: Integer; // Text
1137	1141		begin
1138	1142		CompareText(Cells[ACol,ARow], Cells[BCol,BRow]);
1139	1143		end;
1140	1144
1141	1145		function CompareTextAsInteger: Integer;
1142	1146		var i1,i2:Integer;
1143	1147		begin
1144	1148		if TryStrToInt(StringGrid1.Cells[ACol,ARow],i1) and // Integer
1145	1149		TryStrToInt(StringGrid1.Cells[BCol,BRow],i2) then
1146	1150		Result := CompareValue(i1, i2)
1147	1151		else Exit(0);
1148	1152		end;
1149	1153
1150	1154		function CompareTextAsFloat: Integer; // Float
1151	1155		var f1,f2:Extended;
1152	1156		begin
1153	1157		if TryStrToFloat(StringGrid1.Cells[ACol,ARow],f1) and
1154	1158		TryStrToFloat(StringGrid1.Cells[BCol,BRow],f2) then
1155	1159		Result := CompareValue(f1, f2)
1156	1160		else Exit(0);
1157	1161		end;
1158	1162
1159	1163		function CompareTextAsDateTime: Integer; // DateTime
1160	1164		var
1161	1165		D1, D2 : TDateTime;
1162	1166		begin
1163	1167		if Trim(StringGrid1.Cells[ACol,ARow]) <> Trim(StringGrid1.Cells[BCol,BRow]) then
1164	1168		begin
1165	1169		if trim(StringGrid1.Cells[ACol,ARow]) = '' then Exit(1);
1166	1170		if Trim(StringGrid1.Cells[BCol,BRow]) = '' then Exit(-1);
1167	1171		end
1168	1172		else Exit(0);
1169	1173
1170	1174		if TryStrToDate(StringGrid1.Cells[ACol,ARow], D1, 'yy/mm/dd') and
1171	1175		TryStrToDate(StringGrid1.Cells[BCol,BRow], D2, 'yy/mm/dd') then
1172	1176		Result := CompareDateTime(D1, D2)
1173	1177		else Exit(0);
1174	1178		end;
1175	1179
1176	1180		begin // Don't do anything else here, sort might be done incorrect
1177	1181		With StringGrid1 do
1178	1182		begin
1179	1183		case ACol of
1180	1184		0 : ; // Do not sort column 0
1181	1185		1 : Result := CompareTextAsText; // Text
1182	1186		2 : Result := CompareTextAsInteger; // Integer
1183	1187		3 : Result := CompareTextAsFloat; // Float
1184	1188		4 : Result := CompareTextAsDateTime; // DateTime
1185	1189		end; {Case}
1186	1190		end;
1187	1191		if StringGrid1.Tag = -1 then Result := -Result; // Switch the sort order
1188	1192		end;
1189	1193
1190	1194		// DrawCell does the trick, previous arrow images are removed:
1191	1195		procedure TForm1.StringGrid1DrawCell(Sender: TObject; aCol, aRow: Integer;
1192	1196		aRect: TRect; aState: TGridDrawState);
1193	1197
1194	1198		procedure DrawArrow(ImgIndex:Integer); // Need Up/Down arrows in a ImageList
1195	1199		begin
1196	1200		with StringGrid1 do
1197	1201		TitleImageList.Draw(Canvas, // TitleImageList of StringGrid
1198	1202		ARect.Right - TitleImageList.Width,
1199	1203		(ARect.Bottom - ARect.Top - TitleImageList.Height) div 2 + 2, // Position of arrow, may be adjusted.
1200	1204		ImgIndex );
1201	1205		end;
1202	1206		begin
1203	1207		if Col > 0 then // In this demo no arrows in col 0
1204	1208		if (ARow = 0) and // Suppose Row 0 as TitleRow
1205	1209		Assigned(TitleImageList) then // Need Up/Down arrows in a ImageList
1206	1210		case Columns.Items[aCol].Tag of // Use Tag of Column as index of Ascending/Descending arrow
1207	1211		-1: DrawArrow(1); // Replace with your Index of down arrow
1208	1212		0: DrawArrow(-1); // Remove previous image
1209	1213		1: DrawArrow(2); // Replace with your Index of Up Arrow
1210	1214		end;
1211	1215		end;
1212	1216		```
1213	1217
1214	1218		### Highlighting the selected cell column and row
1215	1219
1216	1220		In Lazarus revision 40276 an option (gdRowHighlight) has been added, it works similar to goRowSelect but it uses a lighter color for selection and the focus rect is only selected cell and not in the whole row. This works fine for rows, but how about columns?.
1217	1221
1218	1222		This section presents a way to highlight columns, rows or both (an example that highlights only column and row headers can be found in lazarus/examples/gridexamples/spreadsheet, this howto is really an extension of that example). This uses two grid events: OnBeforeSelection and OnPrepareCanvas , drawing is not necessary.
1219	1223
1220	1224		The event OnBeforeSelection is triggered when the selection is about the change, in this event we can know what cell is currently selected and what cell will be selected next. We use this information to invalidate the whole row or column of both the old and the new cells. When the next paint cycle starts, the grid will be instructed to paint the cells that belong to the invalidated areas. One of the first steps for painting is calling the OnPrepareCanvas event (if it exists) to setup default canvas properties. We use this event to set up the highlighted row or column:
1221	1225		```
1222	1226		procedure TForm1.gridBeforeSelection(Sender: TObject; aCol, aRow: Integer);
1223	1227		begin
1224	1228		// we can decide here if we want highlight columns, rows or both
1225	1229		// in this example we highlight both
1226	1230		if Grid.Col<>aCol then
1227	1231		begin
1228	1232		// a change on current column is detected
1229	1233		grid.InvalidateCol(aCol); // invalidate the new selected cell column
1230	1234		grid.InvalidateCol(grid.Col); // invalidate the current (it will be the 'old') selected column
1231	1235		end;
1232	1236		if Grid.Row<>aRow then
1233	1237		begin
1234	1238		grid.InvalidateRow(aRow); // invalidate the new selected cell row
1235	1239		grid.InvalidateRow(grid.Row); // invalidate the current (it will be the 'old') selected row
1236	1240		end;
1237	1241		end;
1238	1242
1239	1243		procedure TForm1.gridPrepareCanvas(sender: TObject; aCol, aRow: Integer;
1240	1244		aState: TGridDrawState);
1241	1245		begin
1242	1246		if gdFixed in aState then
1243	1247		begin
1244	1248		if (aCol=grid.Col) or (aRow=grid.Row) then
1245	1249		grid.Canvas.Brush.Color := clInactiveCaption; // this would highlight also column or row headers
1246	1250		end else
1247	1251		if gdFocused in aState then begin
1248	1252		// we leave alone the current selected/focused cell
1249	1253		end else
1250	1254		if (aCol=Grid.Col) or (aRow=grid.Row) then
1251	1255		grid.Canvas.Brush.Color := clSkyBlue; // highlight rows and columns with clSkyBlue color
1252	1256		end;
1253	1257		```
1254	1258
1255	1259		### Avoiding the empty space at the right of the last column
1256	1260
1257	1261		The grid must be in column mode to achieve this. When the grid property `AutoFillColumns` is `true` the empty space is divided by all columns which have a non-zero `SizePriority`. Therefore, you should follow these steps to fill up all horizontal space of a grid:
1258	1262
1259	1263		* Set `AutoFillColumns` to `true`.
1260	1264		* Using the Columns editor, add as many columns as you need.
1261	1265		* Select each column in the object tree above the object inspector and set its `SizePriority` to `0`.
1262	1266		* Now decide while column is widened such that all empty space is used up. Set the `SizePriority` of this column to `1`.
1263	1267
1264	1268		### How to scroll a Grid in "realtime" (moving the scrollbar via mouse)
1265	1269
1266	1270		If you scroll a Grid by moving the scrollbar with the mouse then the Grid per default is not moved "in realtime". Only after you release the mouse, the Grid "jumps" to its new position. You can enable a scrolling in "realtime" by adding Option `goThumbTracking`.
1267	1271
1268	1272		Example:
1269	1273		```
1270	1274		StringGrid1.Options:=StringGrid1.Options + [goThumbTracking];
1271	1275		```
1272	1276
1273	1277		Unfortunately this Option is neither documented in `<lazarus-installdir>\lcl\grids.pas` (ver 2.0.6) nor in <https://lazarus-ccr.sourceforge.io/docs/lcl/grids/tgridoptions.html>
1274	1278
1275	1279		### How to resize a row based on cells content
1276	1280
1277	1281		Lacak in bug report [#38473](<https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/38473>) contributed the following code:
1278	1282		```
1279	1283		type
1280	1284		{ TStringGridHelper }
1281	1285		TStringGridHelper = class helper for TStringGrid
1282	1286		protected
1283	1287		procedure AutoSizeRow(aRow: integer);
1284	1288		end;
1285	1289
1286	1290		{ TStringGridHelper }
1287	1291		procedure TStringGridHelper.AutoSizeRow(aRow: integer);
1288	1292		var
1289	1293		aCanvas: TCanvas;
1290	1294		aCol, maxRowHeight:integer;
1291	1295		aText: String;
1292	1296		textRect: TRect;
1293	1297		begin
1294	1298		aCanvas := GetWorkingCanvas(Canvas);
1295	1299		maxRowHeight := DefaultRowHeight;
1296	1300		for aCol:=0 to ColCount-1 do begin
1297	1301		aText := Cells[aCol,aRow];
1298	1302		textRect := Rect(0, 0, ColWidths[aCol], MaxInt);
1299	1303		DrawText(aCanvas.Handle, PChar(aText), Length(aText), textRect, DT_CALCRECT or DT_WORDBREAK);
1300	1304		if maxRowHeight < textRect.Height then
1301	1305		maxRowHeight := textRect.Height
1302	1306		end;
1303	1307		if aCanvas<>Canvas then FreeWorkingCanvas(aCanvas);
1304	1308		RowHeights[aRow] := maxRowHeight+2;
1305	1309		end;
1306	1310		```
1307	1311
1308	1312		Add that somewhere in your source code and then you can resize a row as if the AutoSizeRow procedure is part of the stringgrid, example:
1309	1313		```
1310	1314		// Resize the row index 2
1311	1315		grid.AutoSizeRow(2);
1312	1316		```
1313	1317
1314	1318		## DBGrids Howto and Examples
1315	1319
1316	1320		### Example: How to set a memo editor for dbgrids
1317	1321
1318	1322		You can, of course, use another control instead of a TMemo. Adjust to taste. Adapted from [[1]](<http://forum.lazarus.freepascal.org/index.php?topic=3640.0>) (simplified to use the SelectedFieldRect property, see [[2]](<http://forum.lazarus.freepascal.org/index.php/topic,8713.msg43288.html#msg43288>))
1319	1323
1320	1324		* Place a memo control (or whatever control you want) on your form, set whatever properties you want and set visible to false. This will be used when editing a grid cell. We'll use GridCellMemo in this example.
1321	1325		* In the OnSelectEditor event put the following code - adapt if you don't want to edit logical column 3, physical column 4:
1322	1326
1323	1327		```
1324	1328		if (Column.DesignIndex = 3) then
1325	1329		begin
1326	1330		GridCellMemo.BoundsRect := DbGrid.SelectedFieldRect;
1327	1331		GridCellMemo.Text:=Column.Field.AsString;
1328	1332		Editor := GridCellMemo;
1329	1333		end;
1330	1334		```
1331	1335
1332	1336		* Suppose your datasource is called Datasource1 and DBGrid is called ResultsGrid. Then, in the OnEditingDone event for the GridCellMemo put the following:
1333	1337
1334	1338		(The original forum post used the OnChange event, which would fire each time the content is changed. Using OnEditingDone only fires after the user is finished with his edits.)
1335	1339		```
1336	1340		if not(Datasource1.State in [dsEdit, dsInsert]) then
1337	1341		Datasource1.Edit;
1338	1342
1339	1343		Datasource1.DataSet.FieldByName(ResultsGrid.SelectedField.FieldName).AsString:=GridCellMemo.Text;
1340	1344		```
1341	1345
1342	1346		Beware Using a normal control as a custom editor has many drawbacks: it won't resize or reposition itself when resizing the columns or scrolling through the grid, you have to take care yourself of modifying the data in the grid (as explained above), it doesn't work properly with DbGrids and interferes with normal grid navigation using the keyboard. The grid interacts with the editor using some special grid messages, so it's better to subclass a control in order to manage those messages, as explained in chapter five of [this document](<http://www.freepascal.org/~michael/articles/grids/grids.pdf>).
1343	1347
1344	1348		Beware If you have more than one grid in the same form use a different custom editor for each one: if you use the same control bad things will happen since both grids will try to use it at once.
1345	1349
1346	1350		### Example: Avoid displaying text fields as "(Memo)" for DBGrids
1347	1351
1348	1352		now (08/2023) exist the dbgrid option dgDisplayMemoText in object inspector - option
1349	1353
1350	1354
1351	1355		When you use SQL statements like "Select * from A" you might see "(Memo)" instead of your content in a grid cell. There are many ways to fix this, but maybe the easiest is to change your statement "Select * from A" to "Select Cast(Column as TEXT) as Column from A". This is a common problem when you use a DBGrid component.
1352	1356		```
1353	1357		var
1354	1358		sql : UTF8String;
1355	1359		Queryu : TSQLQuery;
1356	1360		.....
1357	1361		sql := 'SELECT cast(Name as TEXT) as Name FROM Client';
1358	1362		Queryu.SQL.Text:=sql;
1359	1363		```
1360	1364
1361	1365
1362	1366
1363	1367		for SQLITE3, to avoid cast function usage, just give len for fields in your sqlite database :
1364	1368
1365	1369		\- when you import from csv or create table : create table mytable (myfield TEXT (10))
1366	1370
1367	1371		\- or using sqlstudio or other to give len to fields
1368	1372
1369	1373		### Sorting columns or rows in DBGrid with sort arrows in column header
1370	1374
1371	1375		Here is an example that will sort a DBgrid using the OnTitleClick event and a TSQLQuery and indexes. This should also work for any compatible data set such as TbufDataset. The function uses the column.tag property to store the sort state for each column you click on, so when you go back to one you have already sorted it will pick the correct sort arrow to display.
1372	1376
1373	1377		Prerequisites:
1374	1378
1375	1379		* You will need an imagelist to store the up/down sort arrows. Assign your imagelist to the dbgrid's TitleImageList property.
1376	1380		* Ensure the [TSQLQuery.MaxIndexesCount](<http://lazarus-ccr.sourceforge.net/docs/fcl/sqldb/tsqlquery.maxindexescount.html> "doc:fcl/sqldb/tsqlquery.maxindexescount.html") is large enough to hold the new indexes you will be creating. For this example I had it set to 100.
1377	1381		* You will also need a private var to store the last column used to sort, for this example I have called it FLastColumn.
1378	1382
1379	1383		For this example the TSQLQuery used is called OpenQuery.
1380	1384
1381	1385		![Light bulb](https://upload.wikimedia.org/wikipedia/commons/d/d8/Nuvola_apps_ktip.png) Note: As of March 21st 2013, TSQLQuery has no way to clear indexes, but as a work around you can set unidirectional to true, then set it to false and this will clear the indexes.
1382	1386
1383	1387		In order to reuse the TSQLQuery component with another SQL statement, the indexes must be cleared after sorting or an exception will be raised when you open the TSQLQuery with a different SQL statement.
1384	1388		```
1385	1389		FLastColumn: TColumn; //store last grid column we sorted on
1386	1390
1387	1391		procedure TSQLForm.ResultsGridTitleClick(Column: TColumn);
1388	1392		const
1389	1393		ImageArrowUp=0; //should match image in imagelist
1390	1394		ImageArrowDown=1; //should match image in imagelist
1391	1395		var
1392	1396		ASC_IndexName, DESC_IndexName:string;
1393	1397		procedure UpdateIndexes;
1394	1398		begin
1395	1399		// Ensure index defs are up to date
1396	1400		OpenQuery.IndexDefs.Updated:=false; {<<<--This line is critical. IndexDefs.Update will not
1397	1401		update if already true, which will happen on the first column sorted.}
1398	1402		Openquery.IndexDefs.Update;
1399	1403		end;
1400	1404		begin
1401	1405		ASC_IndexName:='ASC_'+Column.FieldName;
1402	1406		DESC_IndexName:='DESC_'+Column.FieldName;
1403	1407		// indexes can't sort binary types such as ftMemo, ftBLOB
1404	1408		if (Column.Field.DataType in [ftBLOB,ftMemo,ftWideMemo]) then
1405	1409		exit;
1406	1410		// check if an ascending index already exists for this column.
1407	1411		// if not, create one
1408	1412		if OpenQuery.IndexDefs.IndexOf(ASC_IndexName) = -1 then
1409	1413		begin
1410	1414		OpenQuery.AddIndex(ASC_IndexName,column.FieldName,[]);
1411	1415		UpdateIndexes; //ensure index defs are up to date
1412	1416		end;
1413	1417		// Check if a descending index already exists for this column
1414	1418		// if not, create one
1415	1419		if OpenQuery.IndexDefs.IndexOf(DESC_IndexName) = -1 then
1416	1420		begin
1417	1421		OpenQuery.AddIndex(DESC_IndexName,column.FieldName,[ixDescending]);
1418	1422		UpdateIndexes; //ensure index defs are up to date
1419	1423		end;
1420	1424
1421	1425		// Use the column tag to toggle ASC/DESC
1422	1426		column.tag := not column.tag;
1423	1427		if boolean(column.tag) then
1424	1428		begin
1425	1429		Column.Title.ImageIndex:=ImageArrowUp;
1426	1430		Openquery.IndexName:=ASC_IndexName;
1427	1431		end
1428	1432		else
1429	1433		begin
1430	1434		Column.Title.ImageIndex:=ImageArrowDown;
1431	1435		OpenQuery.IndexName:=DESC_IndexName;
1432	1436		end;
1433	1437		// Remove the sort arrow from the previous column we sorted
1434	1438		if (FLastColumn <> nil) and (FlastColumn <> Column) then
1435	1439		FLastColumn.Title.ImageIndex:=-1;
1436	1440		FLastColumn:=column;
1437	1441		end;
1438	1442		```
1439	1443
1440	1444		### Selecting Records in a DBGrid using checkboxes
1441	1445
1442	1446		The objective is to be able to select arbitrary records in a dbgrid using checkboxes, the grid has the ability to show checkboxes automatically when it detects there are boolean fields, for other field types the user can manually choose the cbsCheckboxColumn ButtonStyle for the column. For this kind of columns the user just click the checkbox and the field content is modified accordingly.
1443	1447
1444	1448		But what happen if there is no such available field in our dataset? or we don't want the grid enter edit state when checking the checkbox?. Adding a fieldless column with ButtonStyle=cbsCheckboxColumn will show all checkboxes grayed and disabled because there is no field linked to this column and so nothing to modify. As we want to handle the checkbox state ourselves we need to store the state somewhere for each record. For this we can use the class TBookmarklist (defined in dbgrids.pas unit) where property CurrentRowSelected can tell if the current record is selected or not. By using dbgrid events OnCellClick and OnUserCheckboxState we can track the checkbox state.
1445	1449
1446	1450		Note this technique needs Lazarus r31148 or later which implements event OnUserCheckboxState.
1447	1451		```
1448	1452		...
1449	1453		uses ..., dbgrids, stdctrls, ...
1450	1454
1451	1455		type
1452	1456
1453	1457		{ TForm1 }
1454	1458
1455	1459		TForm1 = class(TForm)
1456	1460		...
1457	1461		procedure DBGrid1CellClick(Column: TColumn);
1458	1462		procedure DBGrid1UserCheckboxState(sender: TObject; column: TColumn; var AState: TCheckboxState);
1459	1463		procedure FormCreate(Sender: TObject);
1460	1464		procedure FormDestroy(Sender: TObject);
1461	1465		...
1462	1466		private
1463	1467		RecList: TBookmarklist;
1464	1468		...
1465	1469		end;
1466	1470
1467	1471		procedure TForm1.DBGrid1CellClick(Column: TColumn);
1468	1472		begin
1469	1473		if Column.Index=1 then
1470	1474		RecList.CurrentRowSelected := not RecList.CurrentRowSelected;
1471	1475		end;
1472	1476
1473	1477		procedure TForm1.FormCreate(Sender: TObject);
1474	1478		begin
1475	1479		RecList := TBookmarkList.Create(DbGrid1);
1476	1480		end;
1477	1481
1478	1482		procedure TForm1.FormDestroy(Sender: TObject);
1479	1483		begin
1480	1484		RecList.Free;
1481	1485		end;
1482	1486
1483	1487		procedure TForm1.DBGrid1UserCheckboxState(sender: TObject; column: TColumn; var AState: TCheckboxState);
1484	1488		begin
1485	1489		if RecList.CurrentRowSelected then
1486	1490		AState := cbChecked
1487	1491		else
1488	1492		AState := cbUnchecked;
1489	1493		end;
1490	1494		```
1491	1495
1492	1496		### Example: How to export a DBGrid to a text file
1493	1497
1494	1498		There are several ways to create a text file from the content of a DBGrid, normally people will tell you that instead of thinking of a DBGrid as a data container one should look a the linked dataset instead, but what happen when the text representation you want must match the grids appearance of the columns visibility, width or order? one solution is to use the LazReport suite that has a component specifically for producing a report from a DbGrid, this report can then be exported to several other formats including a text format. Here another simple solution is presented which can also be used as the basis for other text format exporters, for example, a simple html exporter.
1495	1499		```
1496	1500		// aGrid: The grid to be exported
1497	1501		// lpp: Lines per page. Not including the text header
1498	1502		// pageBreak: insert a page break that some printers could use for starting a new page
1499	1503		// require: uses LazUTF8
1500	1504		function GridTextExporter(aGrid: TDbGrid; lpp: Integer; pageBreak:boolean): TStringList;
1501	1505		const
1502	1506		PX_PER_CHAR = 7;
1503	1507
1504	1508		var
1505	1509		Ds: TDataset;
1506	1510		book: TBookMark;
1507	1511		recCount: Integer;
1508	1512		line: string;
1509	1513		column: TColumn;
1510	1514
1511	1515		function WidthToChar(aWidth: Integer): integer;
1512	1516		begin
1513	1517		result := trunc(aWidth/PX_PER_CHAR);
1514	1518		end;
1515	1519
1516	1520		procedure AddNext(theText: string; alignment: TAlignment);
1517	1521		var
1518	1522		width: Integer;
1519	1523		begin
1520	1524		if (line<>'') and (line<>#12) then
1521	1525		line := line + ' ';
1522	1526
1523	1527		width := WidthToChar(Column.Width);
1524	1528
1525	1529		case Alignment of
1526	1530		taRightJustify: line := line + UTF8PadLeft(theText, width);
1527	1531		taCenter: line := line + UTF8PadCenter(theText, width);
1528	1532		else line := line + UTF8PadRight(theText, width);
1529	1533		end;
1530	1534		end;
1531	1535
1532	1536		procedure CollectHeader;
1533	1537		begin
1534	1538		AddNext(Column.Title.Caption, Column.Title.Alignment);
1535	1539		end;
1536	1540
1537	1541		procedure CollectField;
1538	1542		var
1539	1543		field: TField;
1540	1544		begin
1541	1545		field := Column.Field;
1542	1546
1543	1547		if (field.DataType=ftMemo) and (dgDisplayMemoText in aGrid.Options) then
1544	1548		AddNext(field.AsString, Column.Alignment)
1545	1549		else if Field.DataType<>ftBlob then
1546	1550		AddNext(field.DisplayText, Column.Alignment)
1547	1551		else
1548	1552		AddNext('(blob)', Column.Alignment);
1549	1553		end;
1550	1554
1551	1555		procedure LoopColumns(printingRecord: boolean);
1552	1556		var
1553	1557		c: TCollectionItem;
1554	1558		begin
1555	1559		if (not printingRecord) and pageBreak and (result.count>0) then
1556	1560		line := #12
1557	1561		else
1558	1562		line := '';
1559	1563		for c in aGrid.Columns do begin
1560	1564		Column := TColumn(c);
1561	1565		if Column.Visible and (Column.Width>=PX_PER_CHAR) then begin
1562	1566		if printingRecord then CollectField
1563	1567		else CollectHeader;
1564	1568		end;
1565	1569		end;
1566	1570		result.add(line);
1567	1571		end;
1568	1572
1569	1573		begin
1570	1574		result := TStringList.create;
1571	1575		Ds := aGrid.DataSource.DataSet;
1572	1576		Ds.DisableControls;
1573	1577		book := Ds.GetBookmark;
1574	1578		try
1575	1579		Ds.First;
1576	1580		recCount := 0;
1577	1581		while not DS.EOF do begin
1578	1582		if RecCount mod lpp = 0 then
1579	1583		LoopColumns(false);
1580	1584		LoopColumns(true);
1581	1585		inc(recCount);
1582	1586		Ds.Next;
1583	1587		end;
1584	1588		finally
1585	1589		Ds.GotoBookmark(book);
1586	1590		Ds.FreeBookmark(book);
1587	1591		Ds.EnableControls;
1588	1592		end;
1589	1593		end;
1590	1594		```
1591	1595
1592	1596		To use it one simply does:
1593	1597		```
1594	1598		var
1595	1599		L: TStringList;
1596	1600		begin
1597	1601		L := GridTextExporter(grid, 80, true);
1598	1602		L.SaveToFile('grid.txt');
1599	1603		L.Free;
1600	1604		end;
1601	1605		```
1602	1606
1603	1607		---
1604		-	From the Free Pascal wiki, page "Grids Reference Page", as the Internet Archive kept it on 2024-12-09, last changed on 2024-07-10. 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).
	1608	+	From the Free Pascal wiki, page "Grids Reference Page", as the Internet Archive kept it on 2025-04-23, last changed on 2025-04-15. 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).

Back to history