SynEdit: what changed

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

Old	New		Line
1	1		SynEdit is a [[Syntax highlighting\|syntax highlighting]] edit/memo package available on the [[SynEdit tab]] with support for many languages/syntaxes.
2	2
3	3		The SynEdit contained in Lazarus was forked from [SynEdit 1.0.3](http://synedit.sourceforge.net/), and was adapted and extended quite a lot. Changes are listed below.
4	4
5	5		Lazarus package contains a source editor component named [[TSynEdit]], several syntax highlighters and other components used for source editing.
6	6
7	7		Licensed under the same terms as the original SynEdit (MPL or GPL).
8	8
9	9		## Original vs Lazarus version
10	10
11	11		Lazarus version is maintained mostly by Martin Friebe. Martin wrote at forum, what has been added to Lazarus version since fork appeared:
12	12
13	13		Big things added to the Lazarus version:
14	14
15	15		- folding
16	16		- configurable gutter / gutter-parts
17	17		- shared text between several editors
18	18		- utf-8 support
19	19		- sync-editing plugin
20	20		- basic RTL/LTR support
21	21		- mouse config via MouseActions
22	22		- rewrite of various highlight/markup modules
23	23
24	24		Codebases of Delphi/Lazarus versions were independently refactored. There is very few overlap left.
25	25
26	26		## SynEdit 2.0 port
27	27
28	28		An alternative port of the 2.0.x version of the original SynEdit exists. It's not actively maintained, last commit (now is Jun 2014) was at 2011.
29	29
30	30		- [[SynEdit/port]]
31	31		- [Github page](https://github.com/rnapoles/)
32	32
33	33		## SynEdit in the IDE
34	34
35	35		The SynEdit in Lazarus is a built-in package, because the IDE uses it itself. Therefore the package can not be removed from the installation list. To remove the entries from the component palette, the SynEditDsgn package can be removed from installation.
36	36
37	37		## Using SynEdit
38	38
39	39		### Highlighters
40	40
41	41		- There are several standard highlighters (see [[SynEdit tab]] in the [[Component Palette]])
42	42		- There are scriptable highlighters, which can adapt to many other file formats:
43	43		- [[TSynAnySyn]] (standard, on component palette by default)
44	44		- [[TSynPositionHighlighter]] (standard, not on component palette)
45	45		- [[TSynUniHighlighter]] (standard, not on component palette)
46	46		- SynFacilSyn ([Github](https://github.com/t-edson/SynFacilSyn))
47	47		- More 3rd-party highlighters exist: SynCacheSyn, SynGeneralSyn, SynRCSyn, SynRubySyn, SynSDDSyn, SynSMLSyn, SynSTSyn, SynTclTkSyn, SynUnrealSyn, SynURISyn, SynVBScriptSyn, SynVrml97Syn, [see here](http://bugs.freepascal.org/view.php?id=18248).
48	48		- You can write new highlighter, see info at [[SynEdit Highlighter]].
49	49
50	50		### Markup
51	51
52	52		Markup provides additional coloring [[SynEdit Markup]]
53	53
54	54		### Edit an existing highlighter
55	55
56	56		Sometimes you might want to edit existing highlighters (just like I wanted a few days ago) that already exist. In this example we're going to edit the highlighter for pascal-like code (classname: [[TSynPasSyn]]; package: SynEdit V1.0; unit: SynHighlighterPas.pas).
57	57
58	58		Say, what we want to reach is, that our application (lazarus in this case) differs between the three types of comments, which exist in Pascal:
59	59
60	60		``` pascal
61	61		(* ansi *)
62	62		{ bor }
63	63		// Slash
64	64		```
65	65
66	66		This may be helpful, if you want to differ between different types of your comments (e.g. "Description", "Note", "Reference", etc.) and want them to be e.g. colored in different ways.
67	67
68	68		> Note: Just in case you break something, I suggest to make some "NEW" and "/NEW"-comments, but you don't have to
69	69
70	70		- First, open the unit "SynHighlighterPas" which should be located in your SynEdit-directory.
71	71		- As we don't want to cause incompatibilities, we're creating a new type of enumerator which helps us to identify our comment later:
72	72
73	73		E.g. under the declaration of "tkTokenKind", write this:
74	74
75	75		``` pascal
76	76		{NEW}
77	77		TtckCommentKind = (tckAnsi, tckBor, tckSlash);
78	78		{/NEW}
79	79		```
80	80
81	81		- In the declaration of "TSynPasSyn" search for "FTokenID" and add the following between "FTokenID" and the next field
82	82
83	83		``` pascal
84	84		{NEW}
85	85		FCommentID: TtckCommentKind;
86	86		{/NEW}
87	87		//This creates a new field, where we can store the information, what kind of comment we have
88	88		```
89	89
90	90		- In the declaration of "TSynPasSyn" search for "fCommentAttri" and add the following between "fCommentAttri" and the next field
91	91
92	92		``` pascal
93	93		{NEW}
94	94		fCommentAttri_Ansi: TSynHighlighterAttributes;
95	95		fCommentAttri_Bor: TSynHighlighterAttributes;
96	96		fCommentAttri_Slash: TSynHighlighterAttributes;
97	97		{/NEW}
98	98		//This allows us, to return different Attributes, per type of comment
99	99		```
100	100
101	101		- Next, search for the constructor-definition of "TSynPasSyn", which should be "constructor TSynPasSyn.Create(AOwner: TComponent);"
102	102		- We need to Create our new Attributes, thus we add our Attributes somewhere in the constructor (I suggest, after the default "fCommentAttri")
103	103
104	104		``` pascal
105	105		(...)
106	106		AddAttribute(fCommentAttri);
107	107		{NEW}
108	108		fCommentAttri_Ansi := TSynHighlighterAttributes.Create(SYNS_AttrComment+'_Ansi', SYNS_XML_AttrComment+'_Ansi'); //The last two strings are the Caption and the stored name
109	109		//If you want to have default settings for your attribute, you can e.g. add this:
110	110		//fCommentAttri_Ansi.Background := clBlack; //Would set "Background" to "clBlack" as default
111	111		AddAttribute(fCommentAttri_Ansi);
112	112		fCommentAttri_Bor := TSynHighlighterAttributes.Create(SYNS_AttrComment+'_Bor', SYNS_XML_AttrComment+'_Bor');
113	113		AddAttribute(fCommentAttri_Bor);
114	114		fCommentAttri_Slash := TSynHighlighterAttributes.Create(SYNS_AttrComment+'_Slash', SYNS_XML_AttrComment+'_Slash');
115	115		AddAttribute(fCommentAttri_Slash);
116	116		{/NEW}
117	117		(...)
118	118		```
119	119
120	120		- The "complex" part now is, to search for the points, where "FTokenID" is set to "tkComment" and to set our "subtype", equally (of course, I've already searched them:)
121	121
122	122		``` pascal
123	123		procedure TSynPasSyn.BorProc;
124	124		(...)
125	125		fTokenID := tkComment;
126	126		{NEW}
127	127		FCommentID:=tckBor;
128	128		{/NEW}
129	129		if rsIDEDirective in fRange then
130	130		(...)
131	131		```
132	132
133	133		``` pascal
134	134		procedure TSynPasSyn.AnsiProc;
135	135		begin
136	136		fTokenID := tkComment;
137	137		{NEW}
138	138		FCommentID:=tckAnsi;
139	139		{/NEW}
140	140		(...)
141	141		```
142	142
143	143		``` pascal
144	144		procedure TSynPasSyn.RoundOpenProc;
145	145		(...)
146	146		fTokenID := tkComment;
147	147		{NEW}
148	148		FCommentID:=tckAnsi;
149	149		{/NEW}
150	150		fStringLen := 2; // length of "(*"
151	151		(...)
152	152		```
153	153
154	154		``` pascal
155	155		procedure TSynPasSyn.SlashProc;
156	156		begin
157	157		if fLine[Run+1] = '/' then begin
158	158		fTokenID := tkComment;
159	159		{NEW}
160	160		FCommentID:=tckSlash;
161	161		{/NEW}
162	162		if FAtLineStart then begin
163	163		(...)
164	164		```
165	165
166	166		``` pascal
167	167		procedure TSynPasSyn.SlashContinueProc;
168	168		(...)
169	169		fTokenID := tkComment;
170	170		{NEW}
171	171		FCommentID:=tckSlash;
172	172		{/NEW}
173	173		while not(fLine[Run] in [#0, #10, #13]) do
174	174		(...)
175	175		```
176	176
177	177		- Now, we just have to retreve the information when "GetTokenAttribute" is called and return the right Attribute, therefore we edit "GetTokenAttribute" as follows:
178	178
179	179		``` pascal
180	180		function TSynPasSyn.GetTokenAttribute: TSynHighlighterAttributes;
181	181		begin
182	182		case GetTokenID of
183	183		tkAsm: Result := fAsmAttri;
184	184		{OLD
185	185		tkComment: Result := fCommentAttri; //This is commented and just backup, so it'll be ignored
186	186		/OLD}
187	187		{NEW}
188	188		tkComment: begin
189	189		if (FCommentID = tckAnsi) then
190	190		Result := fCommentAttri_Ansi //Type is AnsiComment
191	191		else
192	192		if (FCommentID = tckBor) then
193	193		Result := fCommentAttri_Bor //Type is BorComment
194	194		else
195	195		if (FCommentID = tckSlash) then
196	196		Result := fCommentAttri_Slash //Type is SlashComment
197	197		else
198	198		Result := fCommentAttri //If our code failed somehow, fallback to default
199	199		end;
200	200		{/NEW}
201	201		tkIDEDirective: begin
202	202		(...)
203	203		```
204	204
205	205		If you do use lazarus, just reinstall the SynEdit-Package, if not, recompile your project/the package/\<similar\>.
206	206
207	207		DONE ! No seriously, you are now ready to differ between the different types of comments.
208	208
209	209		The lazarus-IDE does automatically detect, what attributes exist and shows them in the options, such as saves them, if you change them. If your application/IDE doesn't do this, you will have to set Color/Font/etc. of the new Attributes somewhere manually (e.g. in the constructor of TSynPasSyn)
210	210
211	211		### Completion plugins
212	212
213	213		There are 3 completion plug-ins for SynEdit:
214	214
215	215		[[TSynCompletion]]
216	216
217	217		- Offers a list of words in a drop-down via a shortcut key combination (default: Ctrl-Space).
218	218		- Used in the IDE for identifier completion.
219	219		- Included in examples.
220	220		- Available on the component palette (since 0.9.3x).
221	221
222	222		Example code to invoke the completion pop up programmatically (i.e. without pressing the keyboard shortcut):
223	223
224	224		``` pascal
225	225		YourSynEdit.CommandProcessor(YourSynCompletion.ExecCommandID, '', nil)
226	226		```
227	227
228	228		[[TSynAutoComplete]]
229	229
230	230		- Replaces the current token with a piece of text. Not interactive. No drop-down.
231	231		- Included in examples.
232	232		- Available on the component palette.
233	233
234	234		[[TSynEditAutoComplete]]
235	235
236	236		- Basic template module. No drop-down.
237	237		- Used by IDE for code-templates. IDE contains additional code extending the feature (drop-down and syncro macros are added by IDE).
238	238		- Not included in examples.
239	239
240	240		Todo: Differences between 2nd and 3rd need to be documented. Maybe they can be merged.
241	241
242	242		### Logical/Physical caret position
243	243
244	244		SynEdit offers position of the caret (text blinking cursor) in 2 different forms:
245	245
246	246		- Physical X/Y: Corresponds to visual (canvas) position,
247	247		- Logical X/Y: Corresponds to byte offset of the text.
248	248
249	249		Both are 1-based. Currently Y coordinates are always the same. This may change in future.
250	250
251	251		The Physical coordinate
252	252		is the position in the display grid (ignoring any scrolling). That is:
253	253
254	254		the letter "a" and "â" take both ONE cell on the grid, increasing physical x by 1. Even though in utf8 encoding "a" takes one byte, and "â" takes several bytes.
255	255
256	256		however the tab char (#9), besides being just one byte and one char, can take several cells in the grid, increasing the physical x by more than one. There are also some chars in Chinese and eastern languages, that take 2 grid positions (google full-width vs half-width char)
257	257
258	258		The Logical coordinate
259	259		is the byte offset in the string holding the line.
260	260
261	261		the letter "a" has 1 byte and increases by 1
262	262
263	263		the letter "â" has 2 (or 3) bytes, and increases by that
264	264
265	265		tab has 1 byte and increases by that.
266	266
267	267		Neither of the 2 give the position in UTF8 chars/code-points (e.g. for Utf8Copy or Utf8Length).
268	268
269	269		The physical X is always counted from the left of the text, even if this is scrolled out. To get the grid-x of the currently scrolled control do:
270	270
271	271
272	272		grid-X-in-visible-part-of-synedit := PhysicalX - SynEdit.LeftChar + 1
273	273
274	274		grid-y-in-visible-part-of-synedit := SynEdit.RowToScreenRow(PhysicalY); // includes folding
275	275
276	276		use ScreenRowToRow for reverse
277	277
278	278		### Change text from code
279	279
280		-	~~> Warning: Changing text via <u>SynEdit.Lines</u> property does <u>not work with undo/redo. </u>~~
	280	+	> Warning: Changing text via SynEdit.Lines property does not work with undo/redo.
281	281
282	282		Text can be accessed via SynEdit.Lines. This is a TStrings based property offering read/write access to each line. It is 0 based.
283	283
284	284		``` pascal
285	285		SynEdit.Lines[0] := 'Text'; // first line
286	286		```
287	287
288	288		SynEdit.Lines can be used to set the initial version of the text (e.g. loaded from file). Note that SynEdit.Lines.Add/SynEdit.Lines.Append does not support line breaks inside the added strings. You should add lines one by one.
289	289
290	290		To modify the content of a SynEdit, and allow the user to undo the action use the following methods:
291	291
292	292		``` pascal
293	293		procedure InsertTextAtCaret(aText: String; aCaretMode: TSynCaretAdjustMode = scamEnd);
294	294		property TextBetweenPoints[aStartPoint, aEndPoint: TPoint]: String // Logical Points
295	295		read GetTextBetweenPoints write SetTextBetweenPointsSimple;
296	296		property TextBetweenPointsEx[aStartPoint, aEndPoint: TPoint; CaretMode: TSynCaretAdjustMode]: String
297	297		write SetTextBetweenPointsEx;
298	298		procedure SetTextBetweenPoints(aStartPoint, aEndPoint: TPoint;
299	299		const AValue: String;
300	300		aFlags: TSynEditTextFlags = [];
301	301		aCaretMode: TSynCaretAdjustMode = scamIgnore;
302	302		aMarksMode: TSynMarksAdjustMode = smaMoveUp;
303	303		aSelectionMode: TSynSelectionMode = smNormal );
304	304		```
305	305
306	306		Examples:
307	307
308	308		``` pascal
309	309		// Insert text at caret
310	310		SynEdit.InsertTextAtCaret('Text');
311	311		// Replace text from (x=2,y=10) to (x=4,y=20) with Str
312	312		SynEdit.TextBetweenPoints[Point(2,10), Point(4,20)] := Str;
313	313		```
314	314
315	315		``` pascal
316	316		// Delete/replace single char at caret pos
317	317		var
318	318		p1, p2: TPoint;
319	319		begin
320	320		p1 := SynEdit.LogicalCaretXY;
321	321		p2 := p1;
322	322		// Calculate the byte pos of the next char
323	323		p2.x := p2.x + UTF8CharacterLength(@SynEdit.LineText[p2.x]);
324	324		// p1 points to the first byte of char to be replaced
325	325		// p2 points to the first byte of the char after the last replaceable char
326	326		// Replace with "Text" (or use empty string to delete)
327	327		SynEdit.TextBetweenPoints[p1, p2] := 'Text';
328	328		```
329	329
330	330		### Fold/Unfold from code
331	331
332	332		- This is still under construction.
333	333		- This only works if current highlighter supports folding (details at [[SynEdit Highlighter]]).
334	334		- Also note that some highlighters support several independent fold-trees. E.g. in Pascal you have folding on keywords (begin, end, class, procedure, etc) which is the primary fold, and folding on \$ifdef or \$region which is secondary.
335	335		- Folding of current selection is also different from folding on keywords.
336	336
337	337		Methods for folding:
338	338
339	339		1\) TSynEdit.CodeFoldAction
340	340
341	341		Folds at the given Line. If there are more than one, folds the inner most (right most). Note: This does not work with selection, nor with Folds that hide entirely / Need testing for 2ndary folds.
342	342
343	343		2\) TSynEdit.FindNextUnfoldedLine
344	344
345	345		3\) TSynEdit.FoldAll / TSynEdit.UnfoldAll
346	346
347	347		### Bookmarks
348	348
349	349		- [Forum topic about adding gutter-marks and colored lines](http://forum.lazarus.freepascal.org/index.php/topic,14948.msg79794.html)
350	350
351	351		### More info
352	352
353	353		Discussions on the forum, which contain info about SynEdit:
354	354
355	355		- [Search/replace; caret; position logical/physical](http://forum.lazarus.freepascal.org/index.php/topic,19520.msg111158.html#msg111158)
356	356		- [Diff between SynEdit/SynMemo](http://forum.lazarus.freepascal.org/index.php/topic,19645.msg111962.html#msg111962)
357	357		- [Mouse actions; disable paste on middle click](http://forum.lazarus.freepascal.org/index.php/topic,23997.msg144100.html#msg144100)
358	358		- [TSynEditMarkup info](http://forum.lazarus.freepascal.org/index.php?topic=24842)
359	359
360	360		### Example apps
361	361
362	362		Example applications can be found in the folder "lazarus/examples/synedit".
363	363
364	364		### Adding hotkeys for Cut/Copy/Paste/etc
365	365
366	366		Hotkeys can be implemented by using SynEdit commands.
367	367
368	368		``` pascal
369	369		uses
370	370		SynEdit, SynEditKeyCmds;
371	371
372	372		procedure TForm1.SynEdit1KeyDown(Sender: TObject; var Key: Word;
373	373		Shift: TShiftState);
374	374		begin
375	375		if (Shift = [ssCtrl]) then
376	376		case Key of
377	377		VK_C: SynEdit1.CommandProcessor(TSynEditorCommand(ecCopy), ' ', nil);
378	378		VK_V: SynEdit1.CommandProcessor(TSynEditorCommand(ecPaste), ' ', nil);
379	379		VK_X: SynEdit1.CommandProcessor(TSynEditorCommand(ecCut), ' ', nil);
380	380		end;
381	381		end;
382	382		```
383	383
384	384		## Further development, discussions
385	385
386	386		- RTL (right-to-left): started by Mazen (partly implemented on Windows)
387	387		- SynEdit only uses UTF8; an ASCII/ANSI version no longer exists. A font is pre-selected depending on the system. The user can choose another font, but must then take care to choose a monospaced font.
388	388		- automatic monospace font selection: At the moment SynEdit starts with a font 'courier'. At the moment the LCL TFont does not provide a property to filter monospaced fonts.
389	389		- automatic UTF-8 font selection: Same as above monospace, but also with an UTF-8 font, so that for example umlauts are shown correctly.
390	390		- Dead keys. Most keyboards support typing two or more keys to create one special character (like accented or umlaut characters). (This is handled by LCL widgedset)
391	391		- [[Redesign of the SynEdit component]]. The primary goal is more reliable display and navigation in the text. A more modular approach also allows for better integration of extensions, and for specialized controls, for use outside of Lazarus.
392	392		- [Word Wrapping](http://bugs.freepascal.org/view.php?id=30395). This is an experimental implementation following the idea of the TextTrimmer/TabExpansion classes. The linked bugtraker issue has the class and the explanation of changes required in other files for it to work.
393	393		- Hooks in SynEdit key/command processing. On the forum: <http://forum.lazarus-ide.org/index.php/topic,35592.msg243316.html#msg243316>
394	394
395	395		## See also
396	396
397	397		- [[SynEdit Highlighter]]
398	398		- ["Edit an existing highlighter": German forum thread at "lazarusforum.de"](http://www.lazarusforum.de/viewtopic.php?f=5&t=8723)
399	399		- [[ATSynEdit]]
400	400
401	401		---
402	402		From the Free Pascal wiki, page "SynEdit", as it stood on 2024-03-27 after a change by Wennerer, 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).
403	403		Category: Components
404	404		Category: Lazarus
405	405		Category: SynEdit

Back to history