TECGrid: what changed

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

Old	New		Line
1	1		## Overview
2	2
3	3		TECGrid ![](/wiki-images/8/8c/Ecgrid.png) is a lightweight grid component. It does not contain any strings, it has no [[TDataSource\|DataSource]] connection and its is not possible to custom-draw each cell. Therefore it's not alternative to [[TStringGrid]], [[TDBGrid]] nor [[TDrawGrid]]. It is designed to show content of any data structure and all displayed strings are taken from OnGetHeaderText and OnGetDataCellText events. It features bi-directional mode, fixed columns, fixed rows, column moving, column sizing, various fixed-cell styles and many others, described below.
4	4
5		-	~~<figure>~~
6		-	~~<img src="tecgrid.png" title="tecgrid.png" />~~
7		-	~~<figcaption>tecgrid.png</figcaption>~~
8		-	~~</figure>~~
	5	+	![](/wiki-images/1/19/Tecgrid.png)
9	6
10	7		TECGrid is part of [[Eye-Candy Controls]] (shortly ECControls or EC-Controls) set of visual controls written for Lazarus. Their design is based on Themes, therefore its look is very native everywhere, no matter what widgetset you use.
11	8
12	9		TECGrid is installed to the tab EC-C on the Lazarus component palette.
13	10
14	11		Each release is announced on Lazarus Forum in section Third Party Announcements. There are always attached files `README.txt` (list of all known issues) and `CHANGELOG.txt` (list of all changes from previous release).
15	12
16	13		### License
17	14
18	15		GNU Lesser General Public License 2.0 with linking exception (a.k.a. Modified LGPL). File ectabctrl.pas contains license header. Also, files `COPYING.modifiedLGPL.txt` and `COPYING.LGPL.txt` are bundled to each archive.
19	16
20	17		### Author
21	18
22	19		This component is written by Blaazen. Copyright notice and real name is mentioned in the header of the unit. You can contact author on Lazarus Forum (nickname: Blaazen) in any thread about EC-Controls. If you are logged in to forum, you can get author's e-mail or send him private message.
23	20
24	21		### Download and Install
25	22
26	23		See [[Eye-Candy Controls\|Eye-Candy Controls#Install]]
27	24
28	25		## Options
29	26
30	27		### Property Options
31	28
32	29		\| Option \| Description \|
33	30		\|----\|----\|
34	31		\| egoAlwaysShowEditor \| Editor is shown always; Grid and Column must not be egoReadOnly/ecoReadOnly \|
35	32		\| egoColMoving \| Columns can be moved by mouse; 1) Except fixed columns 2) Columns can be always moved by code \|
36	33		\| egoColSizing \| Columns can be resized by mouse; Column must be ecoSizing \|
37	34		\| egoDottedGrid \| Grid line is dotted \|
38	35		\| egoEnlargeAlways \| Column is enlarged even if Editor is not opened \|
39	36		\| egoHeaderPushedLook \| Column header has pushed look when clicked \|
40	37		\| egoHilightCol \| Whole column is highlighted \|
41	38		\| egoHilightRow \| Whole row is highlighted \|
42	39		\| egoHorizontalLines \| Show horizontal lines of grid \|
43	40		\| egoReadOnly \| Grid is ReadOnly, it never opens Editor \|
44	41		\| egoScrollKeepVisible \| Selection remains visible while scrolling (scrollbars/mouse wheel) \|
45	42		\| egoSortArrow \| Sorting arrow in title is visible; 1) Column must be ecoSorting 2) Grid must have FixedRows\>=1 \|
46	43		\| egoTabs \| Tab key goes through cells instead of other components \|
47	44		\| egoUseOrder \| Array OrderedCols is defined; flag excfOrder for Load/SaveColumnsToXML is available \|
48	45		\| egoVerticalLines \| Show vertical lines of grid \|
49	46		\| egoWheelScrollsGrid \| Mouse wheel scrolls the grid, selection does not change (i.e. it rolls away) \|
50	47
51	48		### Other Grid Properties
52	49
53	50		\| \| \|
54	51		\|----\|----\|
55	52		\| AlternateColor \| Color of even data rows \|
56	53		\| AlternateTint \| Tint of even data rows in percents, 0 = normal color, 100 = AlternateColor \|
57	54		\| Columns \| Collection of columns \|
58	55		\| FixedCols \| Number of fixed columns \|
59	56		\| FixedRowHeight \| Height of fixed (header) rows \|
60	57		\| FixedRows \| Number of fixed (header) rows \|
61	58		\| GridLineColor \| Color of grid lines (data area only) \|
62	59		\| GridLineWidth \| Width of grid lines (data area only) \|
63	60		\| Images \| ImageList for column headers; see Column.Title.ImageIndex property \|
64	61		\| RowHeight \| Height of data rows \|
65	62		\| Style \| Style of cells of fixed rows and/or fixed columns \|
66	63
67	64		### Property Column.Option
68	65
69	66		\| Option \| Description \|
70	67		\|----\|----\|
71	68		\| ecoCellToHint \| Content of data cell is shown as a Hint (tooltip) \|
72	69		\| ecoEnlargePixels \| Property EnlargeWidth means pixels, otherwise means percents \|
73	70		\| ecoReadOnly \| Column is ReadOnly (never shows editor) \|
74	71		\| ecoSizing \| Column can be resized by mouse; Grid must be egoColSizing \|
75	72		\| ecoSorting \| Sorting arrow in title is visible; Grid must be egoSortArrow and must have FixedRows\>=1 \|
76	73		\| ecoVisible \| Column is visible \|
77	74
78	75		### Property Column.Title
79	76
80	77		\| Option \| Description \|
81	78		\|----\|----\|
82	79		\| Alignment \| Text alignment of the column header; bi-directional mode is respected \|
83	80		\| FontOptions \| Font differences of the column header to Grid.Font \|
84	81		\| ImageIndex \| Image displayed in the column header; taken from Grid.Images \|
85	82		\| Text \| Caption of the column header; the only text that is not taken from events \|
86	83
87	84		### Other Column Properties
88	85
89	86		\| Option \| Description \|
90	87		\|----\|----\|
91	88		\| Alignment \| Text alignment of the column; bi-directional mode is respected \|
92	89		\| Color \| Background color of the column \|
93	90		\| ColorTint \| Tint of background color in percents, 0 = Grid.Color/Grid.AlternateColor, 100 = Column.Color \|
94	91		\| EnlargeWidth \| Increment to the column width; value means pixels or percents, depend on option ecoEnlargePixels \|
95	92		\| FontOptions \| Font differences to Grid.Font \|
96	93		\| MaxWidth \| Maximal width of the resizable column \|
97	94		\| MinWidth \| Minimal width of the resizable column \|
98	95
99	96		## Using the Component
100	97
101	98		### Mouse
102	99
103	100		Left button
104	101
105	102		Click on a data-cell always selects it and possibly opens editor (depends on options egoAlwaysShowEditor, egoReadOnly, ecoReadOnly and implementation of OnSelectEditor event).
106	103
107	104		Click on a cell of fixed columns changes row, which in turn changes selection and possibly opens editor (see above).
108	105
109	106		Click on a cell of fixed rows changes SortIndex if option ecoSorting of Column is set. It happens even if option egoSortArrow is not set (arrow is invisibe).
110	107
111	108		Middle button
112	109
113	110		Does nothing.
114	111
115	112		Right button
116	113
117	114		Opens context menu. Note that Grid, Column and Column.Title can have different context menu.
118	115
119	116		Dragging and Resizing
120	117
121	118		Dragging is realized by left mouse button. Dragging moves column on the new position (egoColMoving must be set). Fixed columns cannot be moved. Data columns cannot be moved in front of fixed columns. Shape of the mouse cursor shows if the column can be moved to the new position or not.
122	119
123	120		Resizing is realized by left mouse button. Mouse must be pushed on the right edge of the column header (or the left edge in right-to-left BiDiMode) - when mouse cursor changes its shape. Column width can be resized between MinWidth and MaxWidth. Both Options egoColSizing and ecoSizing must be set.
124	121
125	122		Mouse Wheel
126	123
127	124		Wheel moves selection up/down.
128	125
129	126		Wheel + CTRL key (exactly ssModifier) scrolls grid.
130	127
131	128		Option egoWheelScrollsGrid reverses this behaviour.
132	129
133	130		### Keyboard
134	131
135	132		(Grid must be focused).
136	133
137	134		Arrow keys change selection.
138	135
139	136		Arrow keys + CTRL key (exactly ssModifier) scroll grid.
140	137
141	138		Home/End keys skip to the first/last data column.
142	139
143	140		Home/End keys + CTRL key (exactly ssModifier) skip to the first/last data row.
144	141
145	142		PageUp/PageDown keys skip up/down by the number of visible rows.
146	143
147	144		PageUp/PageDown keys + CTRL key (exactly ssModifier) scroll up/down by the number of visible rows.
148	145
149	146		If option egoTabs is set, Tab key skips to the next data cell. If selection reaches the last column, it skips to the first column and the next row. Shift + Tab skips in the opposite direction.
150	147
151	148		Enter, Space, F2, BackSpace and Delete keys open Editor (Grid/Column must not be egoReadOnly/ecoReadOnly).
152	149
153	150		Keys 0..9 and A..Z also open Editor.
154	151
155	152		CTRL+C copies content of the selection to the clipboard.
156	153
157	154		### Code
158	155
159	156		`procedure BeginUpdate; override;`
160	157
161	158		Reduces number of calculations and repaints when multiple properties change.
162	159
163	160		`function CellRect(ACol, ARow: Integer): TRect;`
164	161
165	162		Returns rectangle of the specified cell.
166	163
167	164		`function CellRectEditor(ACol, ADataRow: Integer): TRect;`
168	165
169	166		Returns corrected rectangle of the specified cell, it takes care of the GridLineWidth. Recommended for opening Editor.
170	167
171	168		`procedure EndUpdate; override;`
172	169
173	170		Each call of BeginUpdate; must be followed by EndUpdate. All changes will be processed.
174	171
175	172		`function IsCellFullyVisible(ACol, ARow: Integer): Boolean;`
176	173
177	174		Returns True if specified cell is fully visible.
178	175
179	176		`function IsCellVisible(ACol, ARow: Integer): Boolean;`
180	177
181	178		Returns True if specified cell is at least partially visible.
182	179
183	180		`function IsColFullyVisible(ACol: Integer): Boolean;`
184	181
185	182		Returns True if AColl is fully visible.
186	183
187	184		`function IsColVisible(ACol: Integer): Boolean;`
188	185
189	186		Returns True if ACol is at least partially visible.
190	187
191	188		`function IsRowFullyVisible(ARow: Integer): Boolean;`
192	189
193	190		Returns True if ARow is fully visible.
194	191
195	192		`function IsRowVisible(ARow: Integer): Boolean;`
196	193
197	194		Returns True if ARow is at least partially visible.
198	195
199	196		`procedure LoadColumnsFromXML(AColumnsNode: TDOMNode; AXMLFlags: TXMLColFlags = cXMLColFlagsAll); overload;`\
200	197		`procedure LoadColumnsFromXML(AFileName: string; AColumnsNode: DOMString; AXMLFlags: TXMLColFlags = cXMLColFlagsAll); overload;`
201	198
202	199		Loads parameters of columns. Option egoUseOrder must be set for using the Order properties.
203	200
204	201		`function MakeCellFullyVisible(ACol, ARow: Integer; AForceColVisible: Boolean): Boolean;`
205	202
206	203		Makes specified cell visible (without selecting it). If column is invisible, it can be forced to show by AForce parameter.
207	204
208	205		`procedure MouseToCell(AMouse: TPoint; out ACol, ARow: Integer);`
209	206
210	207		Returns indexes of a cell placed on the coordinates AMouse.
211	208
212	209		`procedure SaveColumnsToXML(AXMLDoc: TXMLDocument; AColumnsNode: TDOMNode; AXMLFlags: TXMLColFlags = cXMLColFlagsAll); overload;`\
213	210		`procedure SaveColumnsToXML(AFileName: string; AColumnsNode: DOMString; AXMLFlags: TXMLColFlags = cXMLColFlagsAll); overload;`
214	211
215	212		Saves parameters of columns.
216	213
217	214		`procedure SaveToCSVFile(AFileName: string; ADelimiter: Char = ','; AHeaders: Boolean = True; AVisibleColsOnly: Boolean = False);`
218	215
219	216		Saves content of the grid to the text file.
220	217
221	218		`procedure SelectCell(ACol, ARow: Integer; ASelectEditor: TEditorSelection; AForce: Boolean = False);`
222	219
223	220		Changes selection to the cell specified by ACol and ARow. If column is invisible, it can be forced to show by AForce parameter. ASelectEditor specifies whether Editor will be opened (esNative depends on the egoAlwaysShowEditor).
224	221
225	222		`procedure UpdateCell(ACol, ARow: Integer);`
226	223
227	224		Updates single cell.
228	225
229	226		`procedure UpdateColumn(ACol: Integer; AHeader: Boolean = False; AData: Boolean = True);`
230	227
231	228		Updates cells in column.
232	229
233	230		`procedure UpdateRow(ARow: Integer; AFixedCols: Boolean = False; AData: Boolean = True);`
234	231
235	232		Updates visible cells in row.
236	233
237	234		`procedure UpdateRowCount;`
238	235
239	236		Call if you need to change number of data rows immediately. That's because RowCount is taken from OnGetDataRowCount event.
240	237
241	238		## Workflow
242	239
243	240		ECGrid itself does not contain any data (except column titles) and does not provide any built-in editor. All columns must be defined, setting ColCount (as it is with TStringGrid and TDrawGrid) is not enough, this property is read-only here.
244	241
245	242		### Displaying data
246	243
247	244		Lets assume that data are stored in any general structure, for example TFPGObjectList. For displaying all desired data is necessary:
248	245
249	246		- Create corresponding number of columns
250	247		- Implement OnGetDataCellText event for each cell (for fixed columns too)
251	248		- Implement OnGetDataRowCount event. Implementation of this event will return TFPGObjectList.Count (ADataRowCount parameter)
252	249
253	250		Note: It is also possible to implement only one OnGetDataCellText event and assign it to all columns. This event has parameter AColumn, so it is possible to use `case`` AColumn.Index ``of` construction.
254	251
255	252		### Editing data
256	253
257	254		- Create corresponding editors
258	255		- Implement OnSelectEditor event
259	256		- Implement OnChange or OnEditingDone events of the editors
260	257
261	258		Editing:
262	259
263	260		- Select cell and open editor (TEdit, TSpinEdit etc.). Example of implementation of the OnSelectEditor event:
264	261
265	262		`procedure TForm1.SelectEditor(Sender: TObject; ACol, ARow: Integer; var AEditor: TWinControl; AKey: Word);`\
266	263		`begin`\
267		-	~~` SpinEdit1.Value:=`<span style="color: blue">`{ fill appropriate value here }`</span>`;`\~~
	264	+	` SpinEdit1.Value:=``{ fill appropriate value here }``;`\
268	265		` SpinEdit1.BoundsRect:=TECGrid(Sender).CellRectEditor(ACol, ARow);`\
269	266		` AEditor:=SpinEdit1;`\
270	267		`end;`
271	268
272	269		- Change value of the editor (text, number)
273	270		- Editor triggers OnChange or OnEditingDone event
274	271		- Event will change the data
275	272		- Call Grid.Invalidate to repaint, new data will appear
276	273
277	274		Note: If number of items in list is changed (some items was added or deleted), it is necessary to call Grid.UpdateRows to display changes.
278	275
279	276		### Order of columns
280	277
281	278		Important: Option egoUseOrder must be enabled for proper use of Orders. Do not change egoUseOrder during lifetime of the component.
282	279
283	280		There are properties to get the relation of Indexes and Orders.
284	281
285	282		Property
286	283
287	284		`Columns[i].Order;`
288	285
289	286		stores initial order of each column (column with Index=i in this case), while property
290	287
291	288		`ColOrd[i];`
292	289
293	290		returns Index of column with Order=i.
294	291
295	292		`CellOrd[i, j];`
296	293
297	294		is the same as
298	295
299	296		`Cell[ColOrd[i], j];.`
300	297
301	298		Example
302	299
303	300		Lets assume that grid has three columns and their are movable (option egoColMoving is enabled).
304	301
305	302		\| Index \| 0 \| 1 \| 2 \|
306	303		\|-------\|------\|----------\|-------\|
307	304		\| Title \| Name \| Category \| Count \|
308	305		\| Order \| 0 \| 1 \| 2 \|
309	306
310	307		If the first column (Name) is edited, grid will trigger event OnSelectEditor with parameter ACol=0.
311	308
312	309		Now assume that user will move the first column to the third position.
313	310
314	311		\| Index \| 0 \| 1 \| 2 \|
315	312		\|-------\|----------\|-------\|------\|
316	313		\| Title \| Category \| Count \| Name \|
317	314		\| Order \| 1 \| 2 \| 0 \|
318	315
319	316		If the same column is edited again, grid will trigger event OnSelectEditor, but parameter ACol=2 now, which may be difficult to maintain.
320	317
321	318		Even more, user wants to save defined order of columns when session is over and load it back in the next session (for example restart of an application).
322	319
323	320		For this use case, there are properties ColOrd and CellOrd.
324	321
325	322		If we use:
326	323
327	324		`procedure TForm1.SelectEditor(Sender: TObject; ACol, ARow: Integer; var AEditor: TWinControl; AKey: Word);`\
328	325		`begin`\
329	326		` case ACol of`\
330		-	~~` 0: `<span style="color: blue">`{ set editor for column Name }`</span>`;`\~~
331		-	~~` 1: `<span style="color: blue">`{ set editor for column Category }`</span>`;`\~~
332		-	~~` 2: `<span style="color: blue">`{ set editor for column Count }`</span>`;`\~~
	327	+	` 0: ``{ set editor for column Name }``;`\
	328	+	` 1: ``{ set editor for column Category }``;`\
	329	+	` 2: ``{ set editor for column Count }``;`\
333	330		` end;`\
334	331		`end;`
335	332
336	333		This code works well as long as the columns are in their initial order.
337	334
338	335		But we need to select the right editors for all columns, regardless of their new poitions. We must modify the code:
339	336
340	337		`procedure TForm1.SelectEditor(Sender: TObject; ACol, ARow: Integer; var AEditor: TWinControl; AKey: Word);`\
341	338		`begin`\
342	339		` case ColOrd[ACol] of`\
343		-	~~` 0: `<span style="color: blue">`{ set editor for column Name }`</span>`;`\~~
344		-	~~` 1: `<span style="color: blue">`{ set editor for column Category }`</span>`;`\~~
345		-	~~` 2: `<span style="color: blue">`{ set editor for column Count }`</span>`;`\~~
	340	+	` 0: ``{ set editor for column Name }``;`\
	341	+	` 1: ``{ set editor for column Category }``;`\
	342	+	` 2: ``{ set editor for column Count }``;`\
346	343		` end;`\
347	344		`end; `
348	345
349	346		There are methods LoadColumnsFromXML and SaveColumnsToXML which can store and refresh previous order of columns, but also their width and visibility (property Width and option ecoVisible).
350	347
351	348		Note: When option egoUseOrder is disabled it reduces some calculations. Switch this property off if you extensively add and delete columns and/or if you disabled moving of columns (egoColMoving).
352	349
353	350		---
354	351		From the Free Pascal wiki, page "TECGrid", as it stood on 2017-03-29 after a change by Blaazen, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
355	352		Category: Components

Back to history