Grids Reference Page: what changed

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

Old	New		Line
1		-	~~## Contents~~
2		-
3		-	* 1 Objective
4		-	* 2 Overview
5		-	* 3 Inheritance Tree
6		-	* 4 A Starting Example
7		-	* 5 Differences between Lazarus and Delphi grids
8		-	* 5.1 Differences
9		-	* 5.2 New Functionality
10		-	* 5.3 Ways in which you can make a Lazarus grid more Delphi-compatible
11		-	* 6 Grids Reference
12		-	* 6.1 Information
13		-	* 6.2 TCustomGrid
14		-	* 6.2.1 property AllowOutboundEvents
15		-	* 6.2.2 property Columns
16		-	* 6.2.3 property AutoFillColumns
17		-	* 6.2.4 procedure SaveToFile(AFileName: String);
18		-	* 6.2.5 procedure LoadFromFile(AFileName: String);
19		-	* 6.3 TCustomDBGrid
20		-	* 6.3.1 procedure AutoAdjustColumns
21		-	* 6.3.2 procedure InplaceEditor
22		-	* 6.4 TCustomStringGrid
23		-	* 6.4.1 procedure AutoSizeColumn(aCol: Integer);
24		-	* 6.4.2 procedure AutoAdjustColumns or AutoSizeColumns
25		-	* 6.4.3 procedure Clean; overload;
26		-	* 6.4.4 procedure Clean(CleanOptions: TGridZoneSet); overload;
27		-	* 6.4.5 procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TGridZoneSet); overload;
28		-	* 6.4.6 procedure Clean(aRect: TRect; CleanOptions: TGridZoneSet); overload;
29		-	* 6.4.7 procedure SaveToCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
30		-	* 6.4.8 procedure LoadFromCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
31		-	* 6.4.9 property Cols[index: Integer]: TStrings read GetCols write SetCols;
32		-	* 6.4.9.1 Examples
33		-	* 6.4.9.2 Notes.
34		-	* 6.4.10 property Rows[index: Integer]: TStrings read GetRows write SetRows;
35		-	* 6.4.10.1 Notes.
36		-	* 6.4.10.2 Examples
37		-	* 6.4.11 property UseXORFeatures;
38		-	* 6.5 TValueListEditor
39		-	* 6.5.1 Property DisplayOptions
40		-	* 6.5.2 Property TitleCaptions
41		-	* 6.5.3 Property Strings
42		-	* 6.5.4 Property ItemProps
43		-	* 6.5.5 Property KeyOptions
44		-	* 6.5.6 Property DropDownRows
45		-	* 6.5.7 Function DeleteRow
46		-	* 6.5.8 Function InsertRow
47		-	* 6.5.9 Function IsEmptyRow
48		-	* 6.5.10 Function FindRow
49		-	* 6.5.11 Function RestoreCurrentRow
50		-	* 6.5.12 Altered behaviour of some properties derived from TCustomStringGrid
51		-	* 6.5.12.1 Property Options
52		-	* 6.5.12.2 Property FixedRows
53		-	* 6.5.12.3 Property ColCount
54		-	* 6.5.12.4 Property Objects
55		-	* 6.5.13 General comments on the use of TValueListEditor
56		-	* 6.5.14 Saving and loading the contenst of a TValueListEditor
57		-	* 6.5.14.1 Using the Strings property
58		-	* 6.5.14.2 Using TValueList.SaveToFile and TValueList.LoadFromFile
59		-	* 6.5.14.3 Using SaveToCSVFile and LoadFromCSV methods
60		-	* 7 Working with grids
61		-	* 7.1 Customizing grids
62		-	* 7.2 Properties and Events for customizing grids
63		-	* 7.3 Description of grid's drawing process
64		-	* 7.3.1 Differences with Delphi
65		-	* 7.4 Grid's cell selection
66		-	* 7.4.1 Differences with Delphi
67		-	* 7.5 When built-in properties are not enough: derived grids
68		-	* 7.6 What happens in the TCustomGrid.Paint method?
69		-	* 7.6.1 Additional methods to draw in TCustomGrid
70		-	* 7.6.2 Drawing methods introduced by TCustomDrawGrid
71		-	* 7.7 Save and Retrieve Grid Content
72		-	* 7.8 Grid Cell Editors
73		-	* 7.8.1 Builtin cell editors
74		-	* 7.8.2 Using cell editors
75		-	* 7.8.3 Description of editor styles
76		-	* 7.9 Editing grids
77		-	* 7.9.1 Options and properties that affect editing
78		-	* 7.10 Cell hints
79		-	* 8 Grids Howto and Examples
80		-	* 8.1 Focusing a cell
81		-	* 8.2 Example: How to set a custom cell editor
82		-	* 8.3 Example: How to add a button editor
83		-	* 8.4 Example: Working with Picklist, How to make it read only and How to fill it at run time
84		-	* 8.5 Aligning text in StringGrids
85		-	* 8.6 Multilines in Grids
86		-	* 8.7 Validating Entered Values
87		-	* 8.8 Sorting Columns or Rows
88		-	* 8.9 Override automatic sort (ColumnClickSorts set to False). Avoid sort of some columns. Show sort arrows in column header
89		-	* 8.10 Highlighting the selected cell column and row
90		-	* 8.11 Avoiding the empty space at the right of the last column
91		-	* 8.12 How to scroll a Grid in "realtime" (moving the scrollbar via mouse)
92		-	* 8.13 How to resize a row based on cells content
93		-	* 9 DBGrids Howto and Examples
94		-	* 9.1 Example: How to set a memo editor for dbgrids
95		-	* 9.2 Example: Avoid displaying text fields as "(Memo)" for DBGrids
96		-	* 9.3 Sorting columns or rows in DBGrid with sort arrows in column header
97		-	* 9.4 Selecting Records in a DBGrid using checkboxes
98		-	* 9.5 Example: How to export a DBGrid to a text file
99		-
100	1		## Objective
101	2
102	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:
103	4
104	5		1. To introduce the grids components to people with little or no previous Delphi experience.
105	6		2. To document the differences with respect to Delphi grids components.
106	7		3. To document the new functionality in Lazarus grids.
107	8		4. Create reference and examples for the components.
108	9
109	10		## Overview
110	11
111	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.
112	13
113	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.
114	15
115	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>)
116	17
117	18		## Inheritance Tree
118	19		```
119		-	~~[TCustomControl](</index.php?title=TCustomControl&action=edit&redlink=1> "TCustomControl $page does not exist$")~~
	20	+	[[TCustomControl]]
120	21		\|
121	22		\|
122	23		TCustomGrid
123	24		\|
124	25		+-------------+------------+
125	26		\| \|
126	27		TCustomDrawGrid TCustomDbGrid
127	28		\| \|
128	29		+--------+--------+ \|
129	30		\| \| [[TDBGrid]]
130	31		[[TDrawGrid]] TCustomStringGrid
131	32		\|
132	33		---------+----------
133	34		\| \|
134	35		[[TStringGrid]] [[TValueListEditor]]
135	36		```
136	37
137	38		## A Starting Example
138	39
139	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.
140	41
141	42		1. Create a new application.
142	43		* From the main menu select: project->New Project
143	44		* In the Create New Project dialog press the "Create Button"
144	45		* A new empty form will be shown.
145	46		2. Place a grid on the form
146	47		* From the component palette select the "additional" tab
147	48		* Click over the TStringGrid icon [![tstringgrid.png](/wiki-images/c/c4/tstringgrid.png)](</File:tstringgrid.png>)
148	49		* Click over the form, near to the top left corner. A new empty grid appears.
149	50		3. Place a button on the form
150	51		* From the component palette select the "Standard" tab
151	52		* Click over the TButton icon [![tbutton.png](/wiki-images/b/b2/tbutton.png)](</File:tbutton.png>)
152	53		* Click over a empty area of the form. A new button appears.
153	54		4. Doubleclick the button from step 3, and write down the following code in the click button handler:
154	55		*
155	56		```
156	57		StringGrid1.Cells[1,1] := 'Hi World!';
157	58		```
158	59
159	60		5. Run the program by clicking the play icon [![menu run.png](/wiki-images/0/0d/menu_run.png)](</File:menu_run.png>)
160	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)
161	62
162	63		## Differences between Lazarus and Delphi grids
163	64
164	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.
165	66
166	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.
167	68
168	69		### Differences
169	70
170	71		Known differences are listed below, in no special order.
171	72
172	73		* Cell Editors
173	74		* Designtime Behaviour
174	75		* Cell Drawing has some differences, see customizing grid section.
175	76
176	77		### New Functionality
177	78
178	79		* Custom Columns
179	80		* Events
180	81		* Grid Editor
181	82
182	83		### Ways in which you can make a Lazarus grid more Delphi-compatible
183	84
184	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.
185	86
186	87		* [Design] TitleStyle := tsStandard;
187	88		* [Design] DefaultRowHeight := 24;
188	89		* [Code] EditorBorderStyle := bsNone; // this might work only on Windows.
189	90		* [Code] UseXORFeatures := true;
190	91		* [Code] AllowOutBoundEvents := False; // SVN revision 10992 or later
191	92		* [Code] FastEditing := False; // supported in dbgrid. StringGrid requires SVN revision 10992 or later
192	93		* [Design] AutoAdvance := aaNone;
193	94
194	95		## Grids Reference
195	96
196	97		### Information
197	98
198	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>)
199	100
200	101		For TCustomDBGrid and TDBgrid it is the [unit DBGrids.pas reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/dbgrids/index.html>)
201	102
202	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.
203	104
204	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>)
205	106
206	107		### TCustomGrid
207	108
208	109		See the full [TCustomGrid Reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomgrid.html> "doc:lcl/grids/tcustomgrid.html")
209	110
210	111		#### property AllowOutboundEvents
211	112
212	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.
213	114
214	115		#### property Columns
215	116
216	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.
217	118
218	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.
219	120
220	121		For example, if to a base grid with ColCount := 5 and FixedCols := 2 we:
221	122
222	123		* Add 3 custom columns, the base grid will be exactly as before, 2 fixed cols and 3 normal cols.
223	124		* Add 1 custom column, the base grid will have ColCount := 3, that is 2 fixed cols and 1 normal cols.
224	125		* Add 4 custom columns, the base grid will have ColCount := 6, that is 2 fixed cols and 4 normal cols.
225	126
226	127		From this we can conclude that:
227	128
228	129		* Fixed column properties or count are not enhanced or modified respectively by custom columns.
229	130		* grid.ColCount is usually different from grid.Columns.Count (grid.ColCount =grid.Columns.Count only when FixedCols =0)
230	131
231	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.
232	133
233	134		At runtime, columns can be modified with code like this:
234	135		```
235	136		var
236	137		c: TGridColumn;
237	138		begin
238	139		// add a custom column a grid
239	140		c := Grid.Columns.Add;
240	141		// modify
241	142		c.title.caption := 'Price'; // Set columns caption
242	143		c.align := taRightJustify; // Align column content to the right
243	144		c.color := clMoneyGreen; // Change default color to clMoneyGreen
244	145		c.Index := 0; // Make it the first column
245	146		// access an existing column
246	147		grid.columns[0].Width := 60; // Change column 0 width to 60 pixels
247	148		// delete an existing column
248	149		grid.columns.delete(0); // Delete column 0
249	150		....
250	151		end;
251	152		```
252	153
253	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.
254	155
255	156		Currently there are no plans to make the grids use only custom columns.
256	157
257	158		#### property AutoFillColumns
258	159
259	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.
260	161
261	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`.
262	163
263	164		#### procedure SaveToFile(AFileName: String);
264	165
265	166		Saves the grid to an XML file. The property `SaveOptions` determines what exactly is to be saved:
266	167		```
267	168		type
268	169		TGridSaveOptions = (
269	170		soDesign, // Save grid structure (col/row count and Options)
270	171		soAttributes, // Save grid attributes (Font, Brush, TextStyle)
271	172		soContent, // Save Grid Content (Text in StringGrid)
272	173		soPosition // Save Grid cursor and selection position
273	174		);
274	175		TSaveOptions = set of TGridSaveOptions;
275	176		```
276	177
277	178		#### procedure LoadFromFile(AFileName: String);
278	179
279	180		Loads the XML file created by `SaveToFile`. Again, the `SaveOptions` define what exactly is to be loaded from the file.
280	181
281	182		### TCustomDBGrid
282	183
283	184		TCustomDBGrid is the base for TDBGrid.
284	185
285	186		They do not expose Col and Row properties. To go to a certain column, use e.g. the SelectedIndex property.
286	187
287	188		An interesting public method is AutoAdjustColumns.
288	189
289	190		#### procedure AutoAdjustColumns
290	191
291	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.
292	193
293	194		However, contrary to TCustomStringGrid.AutoAdjustColumns (see below), this will set your columns very wide unless you have the property dgAutoSizeColumns enabled.
294	195
295	196		#### procedure InplaceEditor
296	197
297	198		See example from bug 23103 - _and insert explanation of what it does/why it is needed. Validate input values? Change what is shown?_
298	199		```
299	200		procedure TForm1.DBGrid1KeyPress(Sender: TObject; var Key: char);
300	201		var
301	202		S: String;
302	203		begin
303	204		if (Key in [',','.']) then
304	205		begin
305	206		//unlike Delphi not all InPlaceEditors are editors for string type, so check!
306	207		if (DBGrid1.InplaceEditor is TStringCellEditor) then
307	208		begin
308	209		S := TStringCellEditor(DBGrid1.InplaceEditor).EditText;
309	210		if Pos(',',S) > 0 then
310	211		Key := #0
311	212		else
312	213		Key := ',';
313	214		end;
314	215		end;
315	216		end;
316	217		```
317	218
318	219		### TCustomStringGrid
319	220
320		-	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](</index.php?title=new_intermediate_grids&action=edit&redlink=1> "new intermediate grids $page does not exist$") for more information.
	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.
321	222
322	223		The following properties or methods are public and are also available to TStringGrid.
323	224
324	225		See the full [TCustomStringGrid Reference](<http://lazarus-ccr.sourceforge.net/docs/lcl/grids/tcustomstringgrid.html> "doc:lcl/grids/tcustomstringgrid.html")
325	226
326	227		#### procedure AutoSizeColumn(aCol: Integer);
327	228
328	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.
329	230
330	231		#### procedure AutoAdjustColumns or AutoSizeColumns
331	232
332	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.
333	234
334	235		#### procedure Clean; overload;
335	236
336	237		Cleans all cells in the grid, fixed or not.
337	238
338	239		#### procedure Clean(CleanOptions: TGridZoneSet); overload;
339	240
340	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:
341	242
342	243		* Clean all cells: grid.Clean([]); (the same as grid.clean)
343	244		* Clean all non fixed cells: grid.Clean([gzNormal]);
344	245		* Clean all cells but don't touch grid column headers: Grid.Clean([gzNormal, gzFixedRows]);
345	246
346	247		#### procedure Clean(StartCol,StartRow,EndCol,EndRow: integer; CleanOptions:TGridZoneSet); overload;
347	248
348	249		does the same as Clean(CleanOptions:TGridZoneSet) but restricted to the given StartCol,StartRow,EndCol and EndRow. Examples:
349	250
350	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.
351	252
352	253		#### procedure Clean(aRect: TRect; CleanOptions: TGridZoneSet); overload;
353	254
354	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,[]);
355	256
356	257		#### procedure SaveToCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
357	258
358	259		Save grid content to a comma separated values format (CSV) file (added in Lazarus r32179).
359	260
360	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.
361	262
362	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.
363	264
364	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.
365	266
366	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.
367	268
368	269		Normal CSV data output will start at the first non-fixed row in the grid.
369	270
370	271		#### procedure LoadFromCSVFile(AFileName: string; ADelimiter:Char=','; WithHeader:boolean=true);
371	272
372	273		Loads grid content from a comma separated values format (CSV) file (added in Lazarus r32179).
373	274
374	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.
375	276
376	277		The _AFileName_ argument specifies the name of the source file with the CSV content.
377	278
378	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 ;
379	280
380	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.
381	282
382	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.
383	284
384	285		#### property Cols[index: Integer]: TStrings read GetCols write SetCols;
385	286
386	287		Get/set a list of strings from/to the given grid's column index starting from row index 0 to RowCount-1.
387	288
388	289		##### Examples
389	290
390	291		* Set Example: Set the content of the third column in the grid from a ListBox:
391	292
392	293		```
393	294		Grid.Cols[2] := ListBox1.Items;
394	295		```
395	296
396	297		* Get Example: Set the content of a Listbox from the grid's column index 4:
397	298
398	299		```
399	300		procedure TForm1.FillListBox1;
400	301		var
401	302		StrTempList: TStringList;
402	303		begin
403	304		StrTempList := TStringList(Grid.Cols[4]);
404	305		if StrTempList<>nil then begin
405	306		ListBox1.Items.Assign(StrTempList);
406	307		StrTempList.Free;
407	308		end;
408	309		end;
409	310		```
410	311
411	312		##### Notes.
412	313
413	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.
414	315
415	316		This means also that changes in the returned list will not affect the grids content or layout.
416	317
417	318		See the Get Example.
418	319
419	320		#### property Rows[index: Integer]: TStrings read GetRows write SetRows;
420	321
421	322		Get/set a list of strings from/to the given grid's row index starting from column index 0 to column ColCount-1.
422	323
423	324		##### Notes.
424	325
425	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.
426	327
427	328		This means also that changes in the returned list will not affect the grid's content or layout.
428	329
429	330		##### Examples
430	331
431	332		* Set Example: Set the content of the third row in the grid from a ListBox:
432	333
433	334		```
434	335		Grid.Rows[2] := ListBox1.Items;
435	336		```
436	337
437	338		* Get Example: Set the content of a Listbox from the grid's row index 4:
438	339
439	340		```
440	341		procedure TForm1.FillListBox1;
441	342		var
442	343		StrTempList: TStringList;
443	344		begin
444	345		StrTempList := TStringList(Grid.Rows[4]);
445	346		if StrTempList<>nil then begin
446	347		ListBox1.Items.Assign(StrTempList);
447	348		StrTempList.Free;
448	349		end;
449	350		end;
450	351		```
451	352
452	353		* An Example that doesn't work, and its Fix: Retrieved string list is read only
453	354
454	355		```
455	356		// this will not work and will cause memory leak
456	357		// because returned StringList is not being freed
457	358		Grid.Rows[1].CommaText := '1,2,3,4,5';
458	359		Grid.Rows[2].Text := 'a'+#13#10+'s'+#13#10+'d'+#13#10+'f'+#13#10+'g';
459	360
460	361		// fixing the first case
461	362		Lst:=TStringList.Create;
462	363		Lst.CommaText := '1,2,3,4,5';
463	364		Grid.Rows[1] := Lst;
464	365		Lst.Free;
465	366		```
466	367
467	368		#### property UseXORFeatures;
468	369
469	370		Boolean property, default value: False;
470	371
471		-	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](</index.php?title=FocusColor_property&action=edit&redlink=1> "FocusColor property $page does not exist$")
	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]]
472	373
473	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.
474	375
475	376		### TValueListEditor
476	377
477	378		[[TValueListEditor]] is a control derived from TCustomStringGrid for editing Key-Value pairs.
478	379
479	380		#### Property DisplayOptions
480	381
481	382		Controls various aspects of the TValueListEditor's appearance.
482	383
483	384		#### Property TitleCaptions
484	385
485	386		Sets the values of the title captions (if doColumnTitles is in DisplayOptions). If DisplayOptions lacks the value doColumnTitles then default captions are used.
486	387
487	388		#### Property Strings
488	389
489	390		Provides access to the list of strings that hold the Key-Value pairs.
490	391		Key-Value pairs must be in the form:
491	392		'KeyName=Value'
492	393
493	394		#### Property ItemProps
494	395
495	396		You can use this property to control how the items in the "Value" columns can be edited.
496	397		This is controlled by setting the ItemProp's EditStyle and ReadOnly properties.
497	398
498	399		#### Property KeyOptions
499	400
500	401		KeyOptions is a set of TKeyOptions controlling whether the user can modify the contents of the "Key" column.
501	402
502	403		* KeyEdit: the user can edit the name of the Key
503	404		* KeyAdd: the user can add keys (by pressing Insert in the grid). KeyAdd requires KeyEdit.
504	405		* KeyDelete: the user can delete Key-Value pairs (by pressing Ctrl+Delete).
505	406		* KeyUnique: if set, then Keys must have unique names. Attempting to enter a dulpicate Key will raise an exception.
506	407
507	408		#### Property DropDownRows
508	409
509	410		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.
510	411
511	412		#### Function DeleteRow
512	413
513	414		Deletes the Key-Value pair of the indexed row removing the row entirely.
514	415
515	416		#### Function InsertRow
516	417
517	418		Inserts a row in the grid and sets the Key-Value pair. Returns the index of the newly inserted row.
518	419
519	420		#### Function IsEmptyRow
520	421
521	422		Returns true if the indexed row's cells are empty (Keys[aRow]=_; Values[aRow]=_).
522	423
523	424		#### Function FindRow
524	425
525	426		Returns the row that has the specified key name.
526	427
527	428		#### Function RestoreCurrentRow
528	429
529	430		Undoes the editing in the current row (if the editor is still focused). Happens when the user presses the Escape key.
530	431
531	432		#### Altered behaviour of some properties derived from TCustomStringGrid
532	433
533	434		##### Property Options
534	435
535	436		Due to the nature of TValueListEditor its Options property has certain restrictions
536	437
537	438		* goColMoving is not allowed in Options (you cannot set it).
538	439		* goAutoAddRows can only be set if KeyAdd is in KeyOptions. Setting KeyAdd will automatically set goAutoAddRows.
539	440		* goAutoAddRowsSkipContentCheck is not allowed (for the time being, it causes a crash in TValueListeditor: needs fixing).
540	441
541	442		##### Property FixedRows
542	443
543	444		Can only be 1 (show column titles) or 0 (don't show column titles).
544	445
545	446		##### Property ColCount
546	447
547	448		Is always 2.
548	449
549	450		##### Property Objects
550	451
551	452		It is not recommended to use this property at all.
552	453		When some (internal) code manipulates the Strings property, changes are Objects will be lost.
553	454
554	455		#### General comments on the use of TValueListEditor
555	456
556	457		When manipulating the contents of the ValueListEditor (the grid), you can manipulate the underlying Strings property directly.
557	458		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.
558	459
559	460		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.
560	461
561	462		Trying to use ancestor's methods to manipulate rows or columns (e.g. Columns.Add) might result in a crash.
562	463
563	464		#### Saving and loading the contenst of a TValueListEditor
564	465
565	466		##### Using the Strings property
566	467
567	468		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.
568	469		In case of LoadFromFile the `RowCount` property will be autmatically adjusted.
569	470		No sanity checks are performed upon LoadFromFile (so lines that do not represent a Key/Value pair will end up as Keys without Value).
570	471
571	472		##### Using TValueList.SaveToFile and TValueList.LoadFromFile
572	473
573	474		When using SaveToFile and LoadFromFile you get the additional benefits of also being able to save and load the layout, like with other grids.
574	475		SaveToFile will also save information about wether or not the TValueListEditor uses ColumnTitles, and if so, it saves them.
575	476
576	477		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.
577	478		If the file does not seem to be a valid TValueListEditor grid file, and exception is raised.
578	479
579	480		TValueList.SaveToFile and TValueList.LoadFromFile do not work correctly in Lazarus versions <= 2.1 r62044.
580	481
581	482		##### Using SaveToCSVFile and LoadFromCSV methods
582	483
583	484		These methods should not be used at the moment, since for a TValueListEditor they are flawed.
584	485
585	486		## Working with grids
586	487
587	488		### Customizing grids
588	489
589	490		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).
590	491
591	492		### Properties and Events for customizing grids
592	493
593	494		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:
594	495
595	496		* 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.
596	497		* Color. This sets the primary color used to draw non fixed cells background.
597	498		* FixedColor. This is the color used to draw fixed cells background.
598	499		* Flat. This eliminates the 3d look of fixed cells.
599	500
600	501		* TitleFont. Font used to draw the text in fixed cells.
601	502
602	503		* TitleStyle. This property changes the 3D look of fixed cells, there are 3 settings:
603	504		* _tsLazarus._ This is the default look
604	505		* _tsNative._ This tries to set a look that is conforms with the current widgetset theme.
605	506		* _tsStandard._ This style is a more contrasted look, like Delphi grids.
606	507		* 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.
607	508		* BorderColor. This sets the grid's border color used when Flat:=True and BorderStyle:=bsSingle;
608	509		* 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.
609	510
610	511		* FocusColor. The color used to draw the current focused cell if UseXORFeatures is not set, by default this is clRed.
611	512		* FocusRectVisible. Turns on/off the drawing of focused cell.
612	513		* GridLineColor. Color of grid lines in non fixed area.
613	514		* 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_.
614	515		* SelectedColor. Color used to draw cell background on selected cells.
615	516		* 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.
616	517		* 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.
617	518		* AutoAdvance. Where the cell cursor will go when pressing Enter, or after editing.
618	519		* TabAdvance. Where the cell cursor will go when pressing Tab or Shift-Tab.
619	520		* ExtendedColSizing. If true user can resize columns not just at the headers but along the columns height.
620	521
621	522		Other properties that also affect the grids look.
622	523
623	524		Options.
624	525
625		-	~~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.~~
	526	+	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.
626	527
627	528		* goFixedVertLine, goFixedHorzLine it draws a vertical or horizontal line respectively delimiting cells or columns in fixed area, active by default.
628	529		* 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.
629	530		* 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)
630	531		* goRowSelect select the full row instead of individual cells
631	532		* goFixedRowNumbering if set, grid will do numbering of rows in first fixed column
632	533		* 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.
633	534		* goHeaderPushedLook if set, this element enables a pushed look when clicking any fixed cell. The zone of "pushable" cells is enabled using HeaderPusedZones property.
634	535
635	536		(write more)
636	537
637	538		### Description of grid's drawing process
638	539
639	540		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.
640	541
641	542		The process is as follow:
642	543
643	544		* 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.
644	545		* 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.
645	546		* 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:
646	547		* _gdSelected_ The cell will have a selected look.
647	548		* _gdFocused_ The cell will have a focused look.
648	549		* _gdFixed_ Cell have to be painted with fixed cell look.
649	550		* _gdHot_ the mouse is over this cell, so paint it with hot tracking look
650	551		* _gdPushed_ the cell is being clicked, paint it with pushed look
651	552		* 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:
652	553		* 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.
653	554		* 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?...
654	555		* 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.
655	556		* Text. At this point (only for TStringGrid) if DefaultDrawing property is true, the cell's text content is painted.
656	557		* 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).
657	558		* 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.
658	559
659	560		#### Differences with Delphi
660	561
661	562		* In Lazarus TCustomGrid.DrawCell method is not abstract and its default implementation does basic cell background filling.
662	563		* 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>)).
663	564
664	565		### Grid's cell selection
665	566
666	567		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.
667	568
668	569		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.
669	570
670	571		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.
671	572
672	573		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).
673	574
674	575		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.
675	576
676	577		#### Differences with Delphi
677	578
678	579		* 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.
679	580
680	581		### When built-in properties are not enough: derived grids
681	582
682	583		Derived grids usually have to override the following methods:
683	584		DrawAllRows: Draws all visible rows.
684	585		DrawRow: Draws all cells in a row.
685	586		DrawRow draws all cells in the row by first checking if cell is within clipping region, and only draws the cell if it is.
686	587		DrawCell:
687	588		DrawCellGrid:
688	589		DrawCellText:
689	590		DrawFocusRect:
690	591		(write me).
691	592
692	593		### What happens in the `TCustomGrid.Paint` method?
693	594
694	595		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`.
695	596
696	597		* `DrawEdges` : Draws the grid's outer border.
697	598		* `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`_.
698	599		* `DrawRow` (virtual): Is called for each row inside the current viewport.
699	600		* `DrawCell` (virtual): Is first called for each 'normal' (i.e. not fixed) cell in the row.
700	601		* `PrepareCanvas` (virtual): Sets the canvas's drawing styles according to the current cell's visual properties.
701	602		* `DrawFillRect` : Draws the cell's background with the styles set in `PrepareCanvas`.
702	603		* `DrawCellGrid` (virtual): Draws the cell's border lines.
703	604		* `DrawFocusRect` (virtual): In `TCustomGrid` this method does nothing. In descendent grids this method is used to draw the focus rectangle inside the active cell.
704	605		* `DrawCell` (virtual): (see above) Is called for each fixed cell in the row's visible viewport.
705	606		* `DrawColRowMoving` : only active while moving a column or row. This method draws the line that indicates the row's/column's new position.
706	607		* `DrawBorder` : If needed (`Flat=TRUE` and `BorderStyle=bsSingle`), this draws an inner border line.
707	608
708	609		#### Additional methods to draw in `TCustomGrid`
709	610
710	611		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.
711	612
712	613		* `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`).
713	614		* `DrawThemedCell` (virtual): Is only used for fixed cells and if `TitleStyle=tsNative`. It draws the cell's background using `ThemeServices`.
714	615		* `DrawColumnText` (virtual): Is only used for column header cells.
715	616		* `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.
716	617		* `DrawCellText` : (see above)
717	618		* `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).
718	619
719	620		#### Drawing methods introduced by `TCustomDrawGrid`
720	621
721	622		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:
722	623
723	624		* `DrawCell` (override):
724	625		* `PrepareCanvas` : calls the inherited method from `TCustomGrid`.
725	626		* `DefaultDrawCell` (virtual): This method is only called if the event handler for `OnDrawCell` is NOT assigned.
726	627		* `DrawFillRect / DrawThemedCell` (von `TCustomGrid`): Draws the cell's background. If `TitleStyle=tsNative`, the background of fixed cells is drawn using `DrawThemedCell`.
727	628		* `DrawCellAutonumbering` (virtual): If `goFixedAutonumbering in Options`, row numbers are drawn into the first fixed column using `TCustomGrid.DrawCellText`.
728	629		* `DrawColumnText` (from `TCustomGrid`): Is only called for column header cells (see _Additional methods to draw in` TCustomGrid`_).
729	630		* `DrawTextInCell` (from `TCustomGrid`): Is only called for 'normal' (i.e. not fixed) cells (see _Additional methods to draw in` TCustomGrid`_).
730	631		* `DrawCellGrid` (virtual): Draws the cell's borders
731	632
732	633		### Save and Retrieve Grid Content
733	634
734	635		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).
735	636
736	637		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:
737	638		```
738	639		soDesign: Save & load ColCount,RowCount,FixedCols,FixedRows,
739	640		ColWidths, RowHeights and Options (TCustomGrid)
740	641		soPosition: Save & load Scroll position, Row, Col and Selection (TCustomGrid)
741	642		soAttributes: Save & load Colors, Text Alignment & Layout, etc. (TCustomDrawGrid)
742	643		soContent: Save & load Text (TCustomStringGrid)
743	644		soAll: set of all options (soAll:=[soDesign,soPosition,soAttributes,soContent];)
744	645		```
745	646
746	647		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.
747	648
748	649		The soAttributes option is not used in Lazarus standard grids, is there for derived grids.
749	650
750	651		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.
751	652
752	653		For a TStringGrid the default SaveOptions value is [soContent], for other kind of grids, SaveOptions is the empty set.
753	654
754	655		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:
755	656
756	657		* * *
757	658
758	659		Example:
759	660
760	661		1. First, go to menu "File -> New -> Application";
761	662		2. Put an empty TStringGrid on the form;
762	663		3. Put a TButton and TOpenDialog on the form;
763	664		4. Add the event OnCreate for the form;
764	665		5. Add the event OnClick for the button.
765	666
766	667		```
767	668		unit Unit1;
768	669
769	670		{$mode objfpc}{$H+}
770	671
771	672		interface
772	673
773	674		uses
774	675		Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, Grids,
775	676		Buttons, StdCtrls, XMLCfg;
776	677
777	678		type
778	679
779	680		{ TForm1 }
780	681		TForm1 = class(TForm)
781	682		StringGrid1: TStringGrid;
782	683		Button1: TButton;
783	684		OpenDialog1: TOpenDialog;
784	685		procedure Button1Click(Sender: TObject);
785	686		procedure Form1Create(Sender: TObject);
786	687		private
787	688		{ private declarations }
788	689		public
789	690		{ public declarations }
790	691		end;
791	692
792	693		var
793	694		Form1: TForm1;
794	695
795	696		implementation
796	697
797	698		{ TForm1 }
798	699
799	700		procedure TForm1.Form1Create(Sender: TObject);
800	701		begin
801	702		//sets the SaveOptions at creation time of the form
802	703		stringgrid1.SaveOptions := [soDesign,soPosition,soAttributes,soContent];
803	704		end;
804	705
805	706
806	707		procedure TForm1.Button1Click(Sender: TObject);
807	708		begin
808	709		//Ask if thew Execute method of the OpenDialog was launched
809	710		//when this occurs, the user selects an XML file to Load
810	711		//wich name was stored in the FileName prop.
811	712
812	713		if opendialog1.Execute then
813	714		begin
814	715		//Clear the grid
815	716		StringGrid1.Clear;
816	717		//Load the XML
817	718		StringGrid1.LoadFromFile(OpenDialog1.FileName);
818	719		//Refresh the Grid
819	720		StringGrid1.Refresh;
820	721		end;
821	722		end;
822	723
823	724		initialization
824	725		{$I unit1.lrs}
825	726
826	727		end.
827	728		```
828	729
829	730		* * *
830	731
831	732		The sample xml file: (Copy the text below into a txt file. Don't forget put the xml header :-))
832	733		```
833	734		<?xml version="1.0"?>
834	735		<CONFIG>
835	736		<grid version="3">
836	737		<saveoptions create="True" position="True" content="True"/>
837	738		<design columncount="2" rowcount="5" fixedcols="1" fixedrows="1" defaultcolwidth="64" defaultRowHeight="20">
838	739		<options>
839	740		<goFixedVertLine value="True"/>
840	741		<goFixedHorzLine value="True"/>
841	742		<goVertLine value="True"/>
842	743		<goHorzLine value="True"/>
843	744		<goRangeSelect value="True"/>
844	745		<goDrawFocusSelected value="False"/>
845	746		<goRowSizing value="False"/>
846	747		<goColSizing value="False"/>
847	748		<goRowMoving value="False"/>
848	749		<goColMoving value="False"/>
849	750		<goEditing value="False"/>
850	751		<goTabs value="False"/>
851	752		<goRowSelect value="False"/>
852	753		<goAlwaysShowEditor value="False"/>
853	754		<goThumbTracking value="False"/>
854	755		<goColSpanning value="False"/>
855	756		<goRelaxedRowSelect value="False"/>
856	757		<goDblClickAutoSize value="False"/>
857	758		<goSmoothScroll value="True"/>
858	759		</options>
859	760		</design>
860	761		<position topleftcol="1" topleftrow="1" col="1" row="1">
861	762		<selection left="1" top="1" right="1" bottom="1"/>
862	763		</position>
863	764		<content>
864	765		<cells cellcount="10">
865	766		<cell1 column="0" row="0" text="Title Col1"/>
866	767		<cell2 column="0" row="1" text="value(1.1)"/>
867	768		<cell3 column="0" row="2" text="value(2.1)"/>
868	769		<cell4 column="0" row="3" text="value(3.1)"/>
869	770		<cell5 column="0" row="4" text="value(4.1)"/>
870	771		<cell6 column="1" row="0" text="Title Col2"/>
871	772		<cell7 column="1" row="1" text="value(1.2)"/>
872	773		<cell8 column="1" row="2" text="value(2.2)"/>
873	774		<cell9 column="1" row="3" text="value(3.2)"/>
874	775		<cell10 column="1" row="4" text="value(4.2)"/>
875	776		</cells>
876	777		</content>
877	778		</grid>
878	779		</CONFIG>
879	780		```
880	781
881	782		### Grid Cell Editors
882	783
883	784		The grid uses cell editors to change the content of cells.
884	785
885	786		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:
886	787
887	788		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
888	789		2. if the text in the cell represents a date, popup a calendar so we can choose a specific date easily.
889	790
890	791		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.
891	792
892	793		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.
893	794
894	795		#### Builtin cell editors
895	796
896	797		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.
897	798
898	799		The built-in cell editors are Button, Edit, and Picklist.
899	800
900	801		#### Using cell editors
901	802
902	803		Users can specify what editor will be used for a cell using one of two methods.
903	804
904	805		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.
905	806		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).
906	807
907	808		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:
908	809		```
909	810		if ColCB< StringGrid1.Columns.Count
910	811		then StringGrid1.Columns.Items[ColCB].ButtonStyle:=cbsCheckboxColumn;
911	812		```
912	813
913	814		#### Description of editor styles
914	815
915	816		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.
916	817
917	818		* cbsAuto
918	819
919		-	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.
	820	+	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.
920	821
921	822		* cbsEllipsis
922	823
923		-	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.
	824	+	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.
924	825
925		-	~~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.~~
	826	+	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.
926	827
927		-	~~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.~~
	828	+	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.
928	829
929		-	~~This editor style is implemented using TButtonCellEditor, a direct descendant of TButton.~~
	830	+	This editor style is implemented using TButtonCellEditor, a direct descendant of TButton.
930	831
931	832		* cbsNone
932	833
933		-	~~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.~~
	834	+	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.
934	835
935	836		* cbsPickList
936	837
937		-	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.
	838	+	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.
938	839
939	840		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]
940	841		2. In OnSelectEditor, programmers get the TPickListCellEditor instance using the function EditorByStyle(cbsPickList). See here for an example
941	842
942		-	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.
	843	+	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.
943	844
944	845		* cbsCheckboxColumn
945	846
946		-	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).
947		-	~~Getting or setting the value of the checkbox in a cell is done the following way:~~
	847	+	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	+
	849	+	Getting or setting the value of the checkbox in a cell is done the following way:
948	850		```
949	851		StringGrid1.Cell[x,y]:='Z';
950	852		```
951	853
952		-	~~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.~~
	854	+	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.
953	855
954		-	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.
	856	+	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.
955	857
956		-	~~The values that are used to recognize the checked or unchecked states are set in a column's properties ValueChecked and ValueUnchecked.~~
	858	+	The values that are used to recognize the checked or unchecked states are set in a column's properties ValueChecked and ValueUnchecked.
957	859
958		-	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.
	860	+	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.
959	861
960		-	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.
	862	+	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.
961	863
962	864		* cbsButtonColumn
963	865
964		-	~~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.~~
	866	+	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.
965	867
966		-	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.
	868	+	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.
967	869
968		-	~~The button's caption is the corresponding cell string.~~
	870	+	The button's caption is the corresponding cell string.
969	871
970	872		### Editing grids
971	873
972	874		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.
973	875		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".
974	876
975	877		#### Options and properties that affect editing
976	878
977	879		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.
978	880		At start the editable state of the grids is different, for TDrawGrid and TStringGrid editing is disabled, for TDbGrid is enabled by default.
979	881		The Options property has several items that deal with editing, they are described below:
980	882
981	883		* 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.
982	884		* 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.
983	885
984	886		### Cell hints
985	887
986	888		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):
987	889
988	890		* 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.
989	891		* 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.
990	892
991	893		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:
992	894
993	895		* 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
994	896		* chpAllNoDefault displays only the cell hints given by the OnGetCellHint event and by the truncated cells.
995	897		* chpTruncOnly displays only hints for the truncated cells; this is the default settings.
996	898
997	899		In addition, the standard property ShowHint of the grid must be set to true in order to show cell hints.
998	900
999	901		## Grids Howto and Examples
1000	902
1001	903		### Focusing a cell
1002	904
1003	905		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:
1004	906		```
1005	907		StringGrid1.Row := 9;
1006	908		StringGrid1.Col := 8;
1007	909		```
1008	910
1009	911		### Example: How to set a custom cell editor
1010	912
1011	913		See lazarus/examples/gridexamples/gridcelleditor/gridcelleditor.lpi (from laz 1.2)
1012	914
1013	915		### Example: How to add a button editor
1014	916		```
1015	917		// Conditionally show button editor in column index 1 or 2 if
1016	918		// cell in column index 1 is empty
1017	919		procedure TForm1.StringGrid1SelectEditor(Sender: TObject; aCol, aRow: Integer;
1018	920		var Editor: TWinControl);
1019	921		begin
1020	922		if (aCol = 1) or (aCol = 2) then
1021	923		if StringGrid1.Cells[1,aRow] = '' then
1022	924		begin
1023	925		Editor := StringGrid1.EditorByStyle(cbsEllipsis);
1024	926		end;
1025	927		end;
1026	928
1027	929		// Triggering Action ...
1028	930		procedure TForm1.StringGrid1EditButtonClick(Sender: TObject);
1029	931		begin
1030	932		if StringGrid1.Col = 1 then Showmessage('column 1 editor clicked');
1031	933		if StringGrid1.Col = 2 then Showmessage('column 2 editor clicked');
1032	934		end;
1033	935		```
1034	936
1035	937		### Example: Working with Picklist, How to make it read only and How to fill it at run time
1036	938
1037	939		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.
1038	940		```
1039	941		procedure TForm1.gridSelectEditor(Sender: TObject; aCol, aRow: Integer;
1040	942		var Editor: TWinControl);
1041	943		begin
1042	944		if aCol=1 then begin
1043	945		Editor := StringGrid1.EditorByStyle(cbsPickList);
1044	946		if (Editor is TCustomComboBox) then
1045	947		with Editor as TCustomComboBox do begin
1046	948		if (aRow mod 2=0) then
1047	949		Style := csDropDown
1048	950		else
1049	951		Style := csDropDownList;
1050	952		case aRow of
1051	953		1:
1052	954		Items.CommaText := 'ONE,TWO,THREE,FOUR';
1053	955		2:
1054	956		Items.CommaText := 'A,B,C,D,E';
1055	957		3:
1056	958		Items.CommaText := 'MX,ES,NL,UK';
1057	959		4:
1058	960		Items.CommaText := 'RED,GREEN,BLUE,YELLOW';
1059	961		end;
1060	962		end;
1061	963		end;
1062	964		end;
1063	965		```
1064	966
1065	967		### Aligning text in StringGrids
1066	968
1067	969		This code shows how to use different text alignments in columns 2 and 3.
1068	970		```
1069	971		procedure TForm1.StringGrid1PrepareCanvas(sender: TObject; aCol, aRow: Integer;
1070	972		aState: TGridDrawState);
1071	973		var
1072	974		MyTextStyle: TTextStyle;
1073	975		begin
1074	976		if (aCol=2) or (aCol=3) then
1075	977		begin
1076	978		MyTextStyle := StringGrid1.Canvas.TextStyle;
1077	979		if aCol=2 then
1078	980		MyTextStyle.Alignment := taRightJustify
1079	981		else
1080	982		if aCol=3 then
1081	983		MyTextStyle.Alignment := taCenter;
1082	984		StringGrid1.Canvas.TextStyle := MyTextStyle;
1083	985		end;
1084	986		end;
1085	987		```
1086	988
1087	989		### Multilines in Grids
1088	990
1089	991		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.
1090	992		```
1091	993		procedure TForm1.StringGrid1PrepareCanvas(sender: TObject; aCol, aRow: Integer;
1092	994		aState: TGridDrawState);
1093	995		var
1094	996		MyTextStyle: TTextStyle;
1095	997		begin
1096	998		if (aRow=2) or (aCol=3) then
1097	999		begin
1098	1000		MyTextStyle := StringGrid1.Canvas.TextStyle;
1099	1001		MyTextStyle.SingleLine := false;
1100	1002		StringGrid1.Canvas.TextStyle := MyTextStyle;
1101	1003		end;
1102	1004		end;
1103	1005		```
1104	1006
1105	1007		### Validating Entered Values
1106	1008
1107	1009		Lazarus version 0.9.29 introduces the StringGrid OnValidateEntry event of type TValidateEntryEvent which has the following declaration:
1108	1010		```
1109	1011		type
1110	1012		TValidateEntryEvent = procedure(sender: TObject; aCol, aRow: Integer; const OldValue: string; var NewValue: string) of object;
1111	1013		```
1112	1014		```
1113	1015		aCol,aRow are the cell coordinates of cell being validated.
1114	1016		OldValue is the value that was in cells[aCol,aRow] before editing started.
1115	1017		NewValue is the value that will be finally inserted in cells[aCol,aRow].
1116	1018		```
1117	1019
1118	1020		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.
1119	1021
1120	1022		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.
1121	1023
1122	1024		For example, suppose that cell[1,1] should hold only values 'A' or 'B', validation could be made with:
1123	1025		```
1124	1026		procedure TForm1.GridValidateEntry(sender: TObject; aCol,
1125	1027		aRow: Integer; const OldValue: string; var NewValue: String);
1126	1028		begin
1127	1029		if (aCol=1) and (aRow=1) then begin
1128	1030		if grid.Cells[aCol,aRow]<>'A') and grid.Cells[aCol,aRow]<>'B') then begin
1129	1031		// set a new valid value so user can just press RETURN to continue for example.
1130	1032		NewValue := 'A';
1131	1033		// another option is reverting to previous cell value (which is assumed to be valid)
1132	1034		// NewValue := OldValue;
1133	1035		// Use EAbort rather than another Exception type to avoid spurious error
1134	1036		// dialog boxes and backtraces
1135	1037		raise EAbort.Create('Only A or B are allowed here');
1136	1038		end else begin
1137	1039		// if no exception is raised, it is assumed the value is valid, yet if necessary
1138	1040		// the final value can still be changed by filling NewValue with a different value
1139	1041
1140	1042		// computer knows better :)
1141	1043		if grid.Cells[1,1]='A' then
1142	1044		NewValue := 'B'
1143	1045		else
1144	1046		NewValue := 'A';
1145	1047		end;
1146	1048		end;
1147	1049		end;
1148	1050		```
1149	1051
1150	1052		### Sorting Columns or Rows
1151	1053
1152	1054		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.
1153	1055
1154	1056		In code you can use SortColRow() method.
1155	1057
1156	1058		The first parameter, IsColumn, is a boolean value which indicates:
1157	1059
1158	1060		* True if a column is to be sorted
1159	1061		* False if a row is to be sorted.
1160	1062
1161	1063		The second parameter, index, is an integer value:
1162	1064
1163	1065		* Index Indicates Column or Row to be sorted.
1164	1066
1165	1067		The last two parameters are optional, defines subrange of rows or columns to be sorted.
1166	1068
1167	1069		* FromIndex (From column or row)
1168	1070		* ToIndex (To column or row)
1169	1071
1170	1072		If the last two parameters are not specified, the whole column or row is sorted.
1171	1073
1172	1074		Sorting uses QuickSort algorithm, it could be changed if a descendant grid overrides the sort() method and calls doCompareCells for cell compare.
1173	1075
1174	1076		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.
1175	1077		```
1176	1078		// Sort column 3 in ascending order
1177	1079		grid.SortColRow(true, 3);
1178	1080
1179	1081		// Sort column 3 in descending order, skip fixed rows a top
1180	1082		grid.SortOrder := soDescending; // or soAscending
1181	1083		grid.SortColRow(true, 3, grid.FixedRows, grid.RowCount-1);
1182	1084		```
1183	1085
1184	1086		For custom sorting of numbers, dates, states, etc: StringGrid has the OnCompareCells event which users can handle for example this way:
1185	1087		```
1186	1088		procedure TForm1.GridCompareCells(Sender: TObject; ACol, ARow, BCol, BRow: Integer; var Result: integer);
1187	1089		begin
1188	1090		// Result will be either <0, =0, or >0 for normal order.
1189	1091		result := StrToIntDef(Grid.Cells[ACol,ARow],0)-StrToIntDef(Grid.Cells[BCol,BRow],0);
1190	1092		// For inverse order, just negate the result (eg. based on grid's SortOrder).
1191	1093		if StringGrid1.SortOrder = soDescending then
1192	1094		result := -result;
1193	1095		end;
1194	1096		```
1195	1097
1196	1098		You can use OnCompareCells also when automatic column sorting is enabled through ColumnClickSorts property.
1197	1099
1198	1100		### Override automatic sort (ColumnClickSorts set to False). Avoid sort of some columns. Show sort arrows in column header
1199	1101
1200	1102		(ColumnClickSorts set to False will NOT show sort arrows in column header, so we have to set the arrows.)
1201	1103		```
1202	1104		procedure TForm1.StringGrid1HeaderClick(Sender: TObject; IsColumn: Boolean;
1203	1105		Index: Integer);
1204	1106		begin
1205	1107		if isColumn then with StringGrid1 do
1206	1108		begin
1207	1109		col:=Index; // Set column to sort
1208	1110		if Tag = 0 then Tag :=-1 // Suppose data in column is Ascending
1209	1111		else Tag := Tag * -1; // Using StringGrid1.Tag to hold sortorder
1210	1112		// First click of header will sort descending
1211	1113
1212	1114		// Activate CompareCells (ativate the sort)
1213	1115		case Index of
1214	1116		0: col:=-1; // Do not sort column 0 and do not show sort arrow
1215	1117		1: SortColRow(True, Index); // The sort will take place in CompareCells as soon as statement is executed
1216	1118		2: SortColRow(True, Index);
1217	1119		3: SortColRow(True, Index);
1218	1120		4: SortColRow(True, Index);
1219	1121		5: col:=-1; // Do not sort column 5 and do not show sort arrow
1220	1122		end;
1221	1123		end;
1222	1124		end;
1223	1125
1224	1126		// Compare returns one of the following values:
1225	1127		// if A<B return: -1 ( Ascending )
1226	1128		// if A=B return: 0
1227	1129		// if A>B return: 1 ( Descending)
1228	1130
1229	1131		// How to sort: Text, Integer, Float, DateTime:
1230	1132
1231	1133		procedure TForm1.StringGrid1CompareCells(Sender: TObject; ACol, ARow, BCol,
1232	1134		BRow: Integer; var Result: integer);
1233	1135
1234	1136		function CompareTextAsText: Integer; // Text
1235	1137		begin
1236	1138		CompareText(Cells[ACol,ARow], Cells[BCol,BRow]);
1237	1139		end;
1238	1140
1239	1141		function CompareTextAsInteger: Integer;
1240	1142		var i1,i2:Integer;
1241	1143		begin
1242	1144		if TryStrToInt(StringGrid1.Cells[ACol,ARow],i1) and // Integer
1243	1145		TryStrToInt(StringGrid1.Cells[BCol,BRow],i2) then
1244	1146		Result := CompareValue(i1, i2)
1245	1147		else Exit(0);
1246	1148		end;
1247	1149
1248	1150		function CompareTextAsFloat: Integer; // Float
1249	1151		var f1,f2:Extended;
1250	1152		begin
1251	1153		if TryStrToFloat(StringGrid1.Cells[ACol,ARow],f1) and
1252	1154		TryStrToFloat(StringGrid1.Cells[BCol,BRow],f2) then
1253	1155		Result := CompareValue(f1, f2)
1254	1156		else Exit(0);
1255	1157		end;
1256	1158
1257	1159		function CompareTextAsDateTime: Integer; // DateTime
1258	1160		var
1259	1161		D1, D2 : TDateTime;
1260	1162		begin
1261	1163		if Trim(StringGrid1.Cells[ACol,ARow]) <> Trim(StringGrid1.Cells[BCol,BRow]) then
1262	1164		begin
1263	1165		if trim(StringGrid1.Cells[ACol,ARow]) = '' then Exit(1);
1264	1166		if Trim(StringGrid1.Cells[BCol,BRow]) = '' then Exit(-1);
1265	1167		end
1266	1168		else Exit(0);
1267	1169
1268	1170		if TryStrToDate(StringGrid1.Cells[ACol,ARow], D1, 'yy/mm/dd') and
1269	1171		TryStrToDate(StringGrid1.Cells[BCol,BRow], D2, 'yy/mm/dd') then
1270	1172		Result := CompareDateTime(D1, D2)
1271	1173		else Exit(0);
1272	1174		end;
1273	1175
1274	1176		begin // Don't do anything else here, sort might be done incorrect
1275	1177		With StringGrid1 do
1276	1178		begin
1277	1179		case ACol of
1278	1180		0 : ; // Do not sort column 0
1279	1181		1 : Result := CompareTextAsText; // Text
1280	1182		2 : Result := CompareTextAsInteger; // Integer
1281	1183		3 : Result := CompareTextAsFloat; // Float
1282	1184		4 : Result := CompareTextAsDateTime; // DateTime
1283	1185		end; {Case}
1284	1186		end;
1285	1187		if StringGrid1.Tag = -1 then Result := -Result; // Switch the sort order
1286	1188		end;
1287	1189
1288	1190		// DrawCell does the trick, previous arrow images are removed:
1289	1191		procedure TForm1.StringGrid1DrawCell(Sender: TObject; aCol, aRow: Integer;
1290	1192		aRect: TRect; aState: TGridDrawState);
1291	1193
1292	1194		procedure DrawArrow(ImgIndex:Integer); // Need Up/Down arrows in a ImageList
1293	1195		begin
1294	1196		with StringGrid1 do
1295	1197		TitleImageList.Draw(Canvas, // TitleImageList of StringGrid
1296	1198		ARect.Right - TitleImageList.Width,
1297	1199		(ARect.Bottom - ARect.Top - TitleImageList.Height) div 2 + 2, // Position of arrow, may be adjusted.
1298	1200		ImgIndex );
1299	1201		end;
1300	1202		begin
1301	1203		if Col > 0 then // In this demo no arrows in col 0
1302	1204		if (ARow = 0) and // Suppose Row 0 as TitleRow
1303	1205		Assigned(TitleImageList) then // Need Up/Down arrows in a ImageList
1304	1206		case Columns.Items[aCol].Tag of // Use Tag of Column as index of Ascending/Descending arrow
1305	1207		-1: DrawArrow(1); // Replace with your Index of down arrow
1306	1208		0: DrawArrow(-1); // Remove previous image
1307	1209		1: DrawArrow(2); // Replace with your Index of Up Arrow
1308	1210		end;
1309	1211		end;
1310	1212		```
1311	1213
1312	1214		### Highlighting the selected cell column and row
1313	1215
1314	1216		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?.
1315	1217
1316	1218		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.
1317	1219
1318	1220		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:
1319	1221		```
1320	1222		procedure TForm1.gridBeforeSelection(Sender: TObject; aCol, aRow: Integer);
1321	1223		begin
1322	1224		// we can decide here if we want highlight columns, rows or both
1323	1225		// in this example we highlight both
1324	1226		if Grid.Col<>aCol then
1325	1227		begin
1326	1228		// a change on current column is detected
1327	1229		grid.InvalidateCol(aCol); // invalidate the new selected cell column
1328	1230		grid.InvalidateCol(grid.Col); // invalidate the current (it will be the 'old') selected column
1329	1231		end;
1330	1232		if Grid.Row<>aRow then
1331	1233		begin
1332	1234		grid.InvalidateRow(aRow); // invalidate the new selected cell row
1333	1235		grid.InvalidateRow(grid.Row); // invalidate the current (it will be the 'old') selected row
1334	1236		end;
1335	1237		end;
1336	1238
1337	1239		procedure TForm1.gridPrepareCanvas(sender: TObject; aCol, aRow: Integer;
1338	1240		aState: TGridDrawState);
1339	1241		begin
1340	1242		if gdFixed in aState then
1341	1243		begin
1342	1244		if (aCol=grid.Col) or (aRow=grid.Row) then
1343	1245		grid.Canvas.Brush.Color := clInactiveCaption; // this would highlight also column or row headers
1344	1246		end else
1345	1247		if gdFocused in aState then begin
1346	1248		// we leave alone the current selected/focused cell
1347	1249		end else
1348	1250		if (aCol=Grid.Col) or (aRow=grid.Row) then
1349	1251		grid.Canvas.Brush.Color := clSkyBlue; // highlight rows and columns with clSkyBlue color
1350	1252		end;
1351	1253		```
1352	1254
1353	1255		### Avoiding the empty space at the right of the last column
1354	1256
1355	1257		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:
1356	1258
1357	1259		* Set `AutoFillColumns` to `true`.
1358	1260		* Using the Columns editor, add as many columns as you need.
1359	1261		* Select each column in the object tree above the object inspector and set its `SizePriority` to `0`.
1360	1262		* Now decide while column is widened such that all empty space is used up. Set the `SizePriority` of this column to `1`.
1361	1263
1362	1264		### How to scroll a Grid in "realtime" (moving the scrollbar via mouse)
1363	1265
1364	1266		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`.
1365	1267
1366	1268		Example:
1367	1269		```
1368	1270		StringGrid1.Options:=StringGrid1.Options + [goThumbTracking];
1369	1271		```
1370	1272
1371	1273		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>
1372	1274
1373	1275		### How to resize a row based on cells content
1374	1276
1375	1277		Lacak in bug report [#38473](<https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/38473>) contributed the following code:
1376	1278		```
1377	1279		type
1378	1280		{ TStringGridHelper }
1379	1281		TStringGridHelper = class helper for TStringGrid
1380	1282		protected
1381	1283		procedure AutoSizeRow(aRow: integer);
1382	1284		end;
1383	1285
1384	1286		{ TStringGridHelper }
1385	1287		procedure TStringGridHelper.AutoSizeRow(aRow: integer);
1386	1288		var
1387	1289		aCanvas: TCanvas;
1388	1290		aCol, maxRowHeight:integer;
1389	1291		aText: String;
1390	1292		textRect: TRect;
1391	1293		begin
1392	1294		aCanvas := GetWorkingCanvas(Canvas);
1393	1295		maxRowHeight := DefaultRowHeight;
1394	1296		for aCol:=0 to ColCount-1 do begin
1395	1297		aText := Cells[aCol,aRow];
1396	1298		textRect := Rect(0, 0, ColWidths[aCol], MaxInt);
1397	1299		DrawText(aCanvas.Handle, PChar(aText), Length(aText), textRect, DT_CALCRECT or DT_WORDBREAK);
1398	1300		if maxRowHeight < textRect.Height then
1399	1301		maxRowHeight := textRect.Height
1400	1302		end;
1401	1303		if aCanvas<>Canvas then FreeWorkingCanvas(aCanvas);
1402	1304		RowHeights[aRow] := maxRowHeight+2;
1403	1305		end;
1404	1306		```
1405	1307
1406	1308		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:
1407	1309		```
1408	1310		// Resize the row index 2
1409	1311		grid.AutoSizeRow(2);
1410	1312		```
1411	1313
1412	1314		## DBGrids Howto and Examples
1413	1315
1414	1316		### Example: How to set a memo editor for dbgrids
1415	1317
1416	1318		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>))
1417	1319
1418	1320		* 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.
1419	1321		* In the OnSelectEditor event put the following code - adapt if you don't want to edit logical column 3, physical column 4:
1420	1322
1421	1323		```
1422	1324		if (Column.DesignIndex = 3) then
1423	1325		begin
1424	1326		GridCellMemo.BoundsRect := DbGrid.SelectedFieldRect;
1425	1327		GridCellMemo.Text:=Column.Field.AsString;
1426	1328		Editor := GridCellMemo;
1427	1329		end;
1428	1330		```
1429	1331
1430	1332		* Suppose your datasource is called Datasource1 and DBGrid is called ResultsGrid. Then, in the OnEditingDone event for the GridCellMemo put the following:
1431	1333
1432	1334		(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.)
1433	1335		```
1434	1336		if not(Datasource1.State in [dsEdit, dsInsert]) then
1435	1337		Datasource1.Edit;
1436	1338
1437	1339		Datasource1.DataSet.FieldByName(ResultsGrid.SelectedField.FieldName).AsString:=GridCellMemo.Text;
1438	1340		```
1439	1341
1440	1342		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>).
1441	1343
1442	1344		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.
1443	1345
1444	1346		### Example: Avoid displaying text fields as "(Memo)" for DBGrids
1445	1347
1446	1348		now (08/2023) exist the dbgrid option dgDisplayMemoText in object inspector - option
1447	1349
1448	1350
1449	1351		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.
1450	1352		```
1451	1353		var
1452	1354		sql : UTF8String;
1453	1355		Queryu : TSQLQuery;
1454	1356		.....
1455	1357		sql := 'SELECT cast(Name as TEXT) as Name FROM Client';
1456	1358		Queryu.SQL.Text:=sql;
1457	1359		```
1458	1360
1459	1361
1460	1362
1461		-	~~for SQLITE3, to avoid cast function usage, just give len for fields in your sqlite database :~~
1462		-
1463		-
	1363	+	for SQLITE3, to avoid cast function usage, just give len for fields in your sqlite database :
1464	1364
1465		-	~~\- when you import from csv or create table : create table mytable (myfield TEXT (10))~~
	1365	+	\- when you import from csv or create table : create table mytable (myfield TEXT (10))
1466	1366
1467		-	~~\- or using sqlstudio or other to give len to fields~~
	1367	+	\- or using sqlstudio or other to give len to fields
1468	1368
1469	1369		### Sorting columns or rows in DBGrid with sort arrows in column header
1470	1370
1471	1371		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.
1472	1372
1473	1373		Prerequisites:
1474	1374
1475	1375		* You will need an imagelist to store the up/down sort arrows. Assign your imagelist to the dbgrid's TitleImageList property.
1476	1376		* 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.
1477	1377		* You will also need a private var to store the last column used to sort, for this example I have called it FLastColumn.
1478	1378
1479	1379		For this example the TSQLQuery used is called OpenQuery.
1480	1380
1481	1381		![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.
1482	1382
1483	1383		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.
1484	1384		```
1485	1385		FLastColumn: TColumn; //store last grid column we sorted on
1486	1386
1487	1387		procedure TSQLForm.ResultsGridTitleClick(Column: TColumn);
1488	1388		const
1489	1389		ImageArrowUp=0; //should match image in imagelist
1490	1390		ImageArrowDown=1; //should match image in imagelist
1491	1391		var
1492	1392		ASC_IndexName, DESC_IndexName:string;
1493	1393		procedure UpdateIndexes;
1494	1394		begin
1495	1395		// Ensure index defs are up to date
1496	1396		OpenQuery.IndexDefs.Updated:=false; {<<<--This line is critical. IndexDefs.Update will not
1497	1397		update if already true, which will happen on the first column sorted.}
1498	1398		Openquery.IndexDefs.Update;
1499	1399		end;
1500	1400		begin
1501	1401		ASC_IndexName:='ASC_'+Column.FieldName;
1502	1402		DESC_IndexName:='DESC_'+Column.FieldName;
1503	1403		// indexes can't sort binary types such as ftMemo, ftBLOB
1504	1404		if (Column.Field.DataType in [ftBLOB,ftMemo,ftWideMemo]) then
1505	1405		exit;
1506	1406		// check if an ascending index already exists for this column.
1507	1407		// if not, create one
1508	1408		if OpenQuery.IndexDefs.IndexOf(ASC_IndexName) = -1 then
1509	1409		begin
1510	1410		OpenQuery.AddIndex(ASC_IndexName,column.FieldName,[]);
1511	1411		UpdateIndexes; //ensure index defs are up to date
1512	1412		end;
1513	1413		// Check if a descending index already exists for this column
1514	1414		// if not, create one
1515	1415		if OpenQuery.IndexDefs.IndexOf(DESC_IndexName) = -1 then
1516	1416		begin
1517	1417		OpenQuery.AddIndex(DESC_IndexName,column.FieldName,[ixDescending]);
1518	1418		UpdateIndexes; //ensure index defs are up to date
1519	1419		end;
1520	1420
1521	1421		// Use the column tag to toggle ASC/DESC
1522	1422		column.tag := not column.tag;
1523	1423		if boolean(column.tag) then
1524	1424		begin
1525	1425		Column.Title.ImageIndex:=ImageArrowUp;
1526	1426		Openquery.IndexName:=ASC_IndexName;
1527	1427		end
1528	1428		else
1529	1429		begin
1530	1430		Column.Title.ImageIndex:=ImageArrowDown;
1531	1431		OpenQuery.IndexName:=DESC_IndexName;
1532	1432		end;
1533	1433		// Remove the sort arrow from the previous column we sorted
1534	1434		if (FLastColumn <> nil) and (FlastColumn <> Column) then
1535	1435		FLastColumn.Title.ImageIndex:=-1;
1536	1436		FLastColumn:=column;
1537	1437		end;
1538	1438		```
1539	1439
1540	1440		### Selecting Records in a DBGrid using checkboxes
1541	1441
1542	1442		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.
1543	1443
1544	1444		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.
1545	1445
1546	1446		Note this technique needs Lazarus r31148 or later which implements event OnUserCheckboxState.
1547	1447		```
1548	1448		...
1549	1449		uses ..., dbgrids, stdctrls, ...
1550	1450
1551	1451		type
1552	1452
1553	1453		{ TForm1 }
1554	1454
1555	1455		TForm1 = class(TForm)
1556	1456		...
1557	1457		procedure DBGrid1CellClick(Column: TColumn);
1558	1458		procedure DBGrid1UserCheckboxState(sender: TObject; column: TColumn; var AState: TCheckboxState);
1559	1459		procedure FormCreate(Sender: TObject);
1560	1460		procedure FormDestroy(Sender: TObject);
1561	1461		...
1562	1462		private
1563	1463		RecList: TBookmarklist;
1564	1464		...
1565	1465		end;
1566	1466
1567	1467		procedure TForm1.DBGrid1CellClick(Column: TColumn);
1568	1468		begin
1569	1469		if Column.Index=1 then
1570	1470		RecList.CurrentRowSelected := not RecList.CurrentRowSelected;
1571	1471		end;
1572	1472
1573	1473		procedure TForm1.FormCreate(Sender: TObject);
1574	1474		begin
1575	1475		RecList := TBookmarkList.Create(DbGrid1);
1576	1476		end;
1577	1477
1578	1478		procedure TForm1.FormDestroy(Sender: TObject);
1579	1479		begin
1580	1480		RecList.Free;
1581	1481		end;
1582	1482
1583	1483		procedure TForm1.DBGrid1UserCheckboxState(sender: TObject; column: TColumn; var AState: TCheckboxState);
1584	1484		begin
1585	1485		if RecList.CurrentRowSelected then
1586	1486		AState := cbChecked
1587	1487		else
1588	1488		AState := cbUnchecked;
1589	1489		end;
1590	1490		```
1591	1491
1592	1492		### Example: How to export a DBGrid to a text file
1593	1493
1594	1494		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.
1595	1495		```
1596	1496		// aGrid: The grid to be exported
1597	1497		// lpp: Lines per page. Not including the text header
1598	1498		// pageBreak: insert a page break that some printers could use for starting a new page
1599	1499		// require: uses LazUTF8
1600	1500		function GridTextExporter(aGrid: TDbGrid; lpp: Integer; pageBreak:boolean): TStringList;
1601	1501		const
1602	1502		PX_PER_CHAR = 7;
1603	1503
1604	1504		var
1605	1505		Ds: TDataset;
1606	1506		book: TBookMark;
1607	1507		recCount: Integer;
1608	1508		line: string;
1609	1509		column: TColumn;
1610	1510
1611	1511		function WidthToChar(aWidth: Integer): integer;
1612	1512		begin
1613	1513		result := trunc(aWidth/PX_PER_CHAR);
1614	1514		end;
1615	1515
1616	1516		procedure AddNext(theText: string; alignment: TAlignment);
1617	1517		var
1618	1518		width: Integer;
1619	1519		begin
1620	1520		if (line<>'') and (line<>#12) then
1621	1521		line := line + ' ';
1622	1522
1623	1523		width := WidthToChar(Column.Width);
1624	1524
1625	1525		case Alignment of
1626	1526		taRightJustify: line := line + UTF8PadLeft(theText, width);
1627	1527		taCenter: line := line + UTF8PadCenter(theText, width);
1628	1528		else line := line + UTF8PadRight(theText, width);
1629	1529		end;
1630	1530		end;
1631	1531
1632	1532		procedure CollectHeader;
1633	1533		begin
1634	1534		AddNext(Column.Title.Caption, Column.Title.Alignment);
1635	1535		end;
1636	1536
1637	1537		procedure CollectField;
1638	1538		var
1639	1539		field: TField;
1640	1540		begin
1641	1541		field := Column.Field;
1642	1542
1643	1543		if (field.DataType=ftMemo) and (dgDisplayMemoText in aGrid.Options) then
1644	1544		AddNext(field.AsString, Column.Alignment)
1645	1545		else if Field.DataType<>ftBlob then
1646	1546		AddNext(field.DisplayText, Column.Alignment)
1647	1547		else
1648	1548		AddNext('(blob)', Column.Alignment);
1649	1549		end;
1650	1550
1651	1551		procedure LoopColumns(printingRecord: boolean);
1652	1552		var
1653	1553		c: TCollectionItem;
1654	1554		begin
1655	1555		if (not printingRecord) and pageBreak and (result.count>0) then
1656	1556		line := #12
1657	1557		else
1658	1558		line := '';
1659	1559		for c in aGrid.Columns do begin
1660	1560		Column := TColumn(c);
1661	1561		if Column.Visible and (Column.Width>=PX_PER_CHAR) then begin
1662	1562		if printingRecord then CollectField
1663	1563		else CollectHeader;
1664	1564		end;
1665	1565		end;
1666	1566		result.add(line);
1667	1567		end;
1668	1568
1669	1569		begin
1670	1570		result := TStringList.create;
1671	1571		Ds := aGrid.DataSource.DataSet;
1672	1572		Ds.DisableControls;
1673	1573		book := Ds.GetBookmark;
1674	1574		try
1675	1575		Ds.First;
1676	1576		recCount := 0;
1677	1577		while not DS.EOF do begin
1678	1578		if RecCount mod lpp = 0 then
1679	1579		LoopColumns(false);
1680	1580		LoopColumns(true);
1681	1581		inc(recCount);
1682	1582		Ds.Next;
1683	1583		end;
1684	1584		finally
1685	1585		Ds.GotoBookmark(book);
1686	1586		Ds.FreeBookmark(book);
1687	1587		Ds.EnableControls;
1688	1588		end;
1689	1589		end;
1690	1590		```
1691	1591
1692	1592		To use it one simply does:
1693	1593		```
1694	1594		var
1695	1595		L: TStringList;
1696	1596		begin
1697	1597		L := GridTextExporter(grid, 80, true);
1698	1598		L.SaveToFile('grid.txt');
1699	1599		L.Free;
1700	1600		end;
1701	1601		```
1702	1602
1703	1603		---
1704	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).

Back to history