ATSynEdit: what changed

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

Old	New		Line
1	1		# About
2	2
3	3		ATSynEdit is the multi-line editor control.
4	4
5	5		- Homepage: <https://github.com/Alexey-T/ATSynEdit>
6	6		- Support for EControl adapter: <https://github.com/Alexey-T/EControl>
7	7
8	8		Author: Alexey Torgashin
9	9
10	10		![](/wiki-images/e/eb/Atsynedit.png)
11	11
12	12		# License
13	13
14	14		ATSynEdit files licensed under MPL 2.0. You can optionally use them under LGPL if your project needs it.
15	15
16	16		EControl files licensed under special license (readme.txt), usage allowed only in open-source projects.
17	17
18	18		# Keyboard shortcuts
19	19
20	20		Run demo_editor and call menu item "Help - Commands'. You'll see all shortcuts in a dialog like this:
21	21
22	22		![](/wiki-images/d/db/Atsynedit_keymap.png)
23	23
24	24		# Mouse shortcuts
25	25
26	26		Multi-carets:
27	27
28	28		- Ctrl+click - add/delete caret
29	29		- Ctrl+drag - add caret with selection
30	30		- Ctrl+Shift+click - add carets column in several lines (from previous caret to clicked line)
31	31
32	32		Select:
33	33
34	34		- Alt+drag - select column of text (Note: it may look weird if word-wrap on, because wrap is not considered here at all. Simple rectangle of coordinates \[x1,y1\]-\[x2,y2\] is always selected, even if this gives bad looking screen)
35	35		- drag on gutter's line numbers - select by entire lines
36	36		- double-click and immediately drag - select text by words
37	37
38	38		Clicks:
39	39
40	40		- double-click - select clicked word
41	41		- triple-click - select entire line (limited by end-of-lines)
42	42		- middle-button click - start "Browser Scroll" mode: circle mark appears and mouse moving around this mark auto-scrolls text in 4 directions; speed of scrolling depends on distance of cursor from circle mark (any click to turn off)
43	43
44	44		# Multi-carets
45	45
46	46		Multi-carets are several carets at once. All carets work together for many editing commands: caret moving, text typing, deleting, selection with keyboard. See "Mouse shortcuts", how to add/remove carets.
47	47
48	48		Animation:
49	49
50	50		![](/wiki-images/c/cf/Atsynedit-carets.gif)
51	51
52	52		## Multi-selections
53	53
54	54		If you add caret with Ctrl+click, caret has no selection. If you add caret with Ctrl+drag, caret will have selection. You can add selections to carets later, by Shift+arrows, Shift+Home, Shift+End etc.
55	55
56	56		Multi-selections are handled specially on copy/paste. If you copy selections, then move carets, then paste, paste will insert clipboard lines into carets: line-1 at caret-1, line-2 at caret-2 etc (only if carets count equals to lines count in clipboard, otherwise result is different).
57	57
58	58		Animation shows this:
59	59
60	60		![](/wiki-images/6/67/Atsynedit-sel.gif)
61	61
62	62		## Clipboard commands with selections
63	63
64	64		Clipboard-related commands work with carets, both with selections and without them. Some details about this:
65	65
66	66		Command
67	67
68	68		Behaviour, when there're no selections
69	69
70	70		Behaviour, when at last one selection present
71	71
72	72		Copy to clipboard
73	73
74	74		Copies entire lines, containing carets.
75	75
76	76		` (Ignores multiple carets on same line.)`
77	77
78	78		Copies only selections text.
79	79
80	80		` (Ignores carets without selections.)`
81	81
82	82		Cut to clipboard
83	83
84	84		Similarly to "Copy" w/o selections.
85	85
86	86		Similarly to "Copy" with selections.
87	87
88	88		Paste from clipboard
89	89
90	90		First, selections are cleared (deleted). Then, command pastes text into each caret position. Special case is when clipboard lines count equals to carets count - in this case, first line is inserted at first caret, second line is inserted at 2nd caret, etc.
91	91
92	92		Delete char
93	93
94	94		Deletes one char at each caret position.
95	95
96	96		Deletes only selections text. (Ignores carets without selections.)
97	97
98	98		# Help topics
99	99
100	100		## Compilation errors
101	101
102	102		IME error on GTK2.
103	103
104	104		You may get this error:
105	105
106		-	~~`atsynedit_adapter_gtk2ime.pas(131,5) Error: Identifier not found "IM_Context_Set_Cursor_Pos"`~~
	106	+	```
	107	+	atsynedit_adapter_gtk2ime.pas(131,5) Error: Identifier not found "IM_Context_Set_Cursor_Pos"
	108	+	```
107	109
108	110		To fix it, edit the file "atsynedit/atsynedit_package.lpk" and remove this block there:
109	111
110	112		``` xml
111	113		<Other>
112	114		<CustomOptions Value="-dGTK2_IME_CODE"/>
113	115		<OtherDefines Count="1">
114	116		<Define0 Value="GTK2_IME_CODE"/>
115	117		</OtherDefines>
116	118		</Other>
117	119		```
118	120
119	121		Alternative solution when symbol "IM_Context_Set_Cursor_Pos" cannot be found: you need to open IDE dialog "Tools / Configure 'Build Lazarus'", and there enable the define: WITH_GTK2_IM; then recompile the IDE.
120	122
121	123		## What limitations it has?
122	124
123	125		- All lines have the same height
124	126		- Cannot set different fonts for different parts
125	127		- No support for right-to-left mode, only limited support for Arabic text
126	128
127	129		## What features it has?
128	130
129	131		- Fast editing of big texts (tested 10M log)
130	132		- Syntax highliting using 'adapters'
131	133		- Multi-carets from birth. All code carets aware.
132	134		- Strings object is holder of text. 2+ editors can have 1 strings obj. (Split editor.)
133	135		- Unicode (used UnicodeString in Strings obj)
134	136		- Word-wrap (wrap at control edge, wrap at column)
135	137		- Inter-line gaps (see #Gaps_object)
136	138		- Undo/redo
137	139		- Column blocks
138	140		- Gutter (line numbers, folding, colored line states)
139	141		- Bookmarks (with icons)
140	142		- Supports Win/Unix/Mac line ends
141	143		- Minimap like Sublime Text
142	144		- Micromap (owner drawn)
143	145		- Ruler (at top edge)
144	146		- Renders wrapped indent (line contains some indent, wrapped parts contain the same indent)
145	147		- Renders CJK chars with big width
146	148		- Renders some Unicode chars as "AABB" hex code
147	149		- Renders unprintable chars (space, tab, line end)
148	150		- Can highlight/activate URLs
149	151		- Can set color attributes for ranges (to highlight pair brackets or same words)
150	152		- Supports proportional fonts
151	153
152	154		## Difference from other components
153	155
154	156		- Adapters to support syntax highlighting. In theory, using adapters it's possible to support syntax files from any app: Sublime Text, Atom, EmEditor etc.
155	157		- Muti-carets, multi-selections
156	158		- Inter-line gaps, can insert pictures in it
157	159		- Minimap, Micromap (rare in others editors)
158	160		- Smooth per-pixel scrolling (option)
159	161
160	162		## Does it need to be installed?
161	163
162	164		It may be installed or not.
163	165
164	166		- Use not installed: see below "Basic example how to use".
165	167		- Use installed: in Lazarus IDE, open package file "atsynedit\atsynedit_package". Install it in Package dialog. You 'll have components installed in "Misc" page of component pallette: TATSynEdit, TATEdit (single line edit), etc.
166	168
167	169		## What parts does it have?
168	170
169	171		### Strings object
170	172
171	173		type TATStrings in unit atstrings. Storage of text lines. It includes managing of Undo/Redo too.
172	174
173	175		Methods:
174	176
175	177		- To add/delete lines: LineAdd, LineInsert, LineDelete. They automatically create/update Undo/Redo data. Methods with "Raw" word in name: ignore Undo/Redo data, usually don't use them.
176	178		- To insert/delete blocks of lines: LineBlockInsert, LineBlockDelete.
177	179		- Methods starting with "Text" support basic text operations: TextReplace, TextAppend, TextInsert etc. They operate on one caret position and get parameters AShift (shift of caret after text operation, by x/y) and APosAfter (position of caret after the operation).
178	180		- To load entire content into Strings object: LoadFromFile, LoadFromStream, LoadFromString (multi-line string).
179	181
180	182		To get/set lines, use properties:
181	183
182	184		- Lines\[i\]: text, of type UnicodeString
183	185		- LinesUTF8\[i\]: text, of type string (faster than Lines\[\])
184	186		- LinesLen\[i\]: integer: same as Length(Lines\[i\]), but faster
185	187		- LinesEnds\[i\]: enum: kind of end-of-line chars
186	188		- LinesHidden\[i\]: bool: true if line is fully hidden (inside folded block)
187	189		- LinesFoldFrom\[i\]: byte: 0 if line is not folded, \>0 if line is folded from this char-pos
188	190		- LinesState\[i\]: enum: line state, normal/changed/saved, it's shown by color on gutter
189	191		- LinesSeparator\[i\]: enum: kind of horizontal separator line to paint near text (rarely needed for apps).
190	192
191	193		Auto-adjustments of other objects when lines are added/deleted:
192	194
193	195		- Strings object updates Strings.Bookmarks, Strings.Bookmarks2 objects.
194	196		- Strings object updates Gaps (actually Strings.Gaps) object.
195	197		- If Strings.GutterDecor1 / .GutterDecor2 properties are set, Strings object updates GutterDecor object(s). Properties are not set in ATSynEdit, application must set them.
196	198		- Objects Attribs / Markers / HotSpots are updated not inside Strings object, but in main ATSynEdit code.
197	199
198	200		### Strings.Bookmarks object
199	201
200	202		type TATBookmarks in unit atsynedit_bookmarks. Holds list of bookmarks of type TATBookmarkItem. Each item has props:
201	203
202	204		- Data.LineNum: line index (in Strings object)
203	205		- Data.Kind: int kind value
204	206		- Data.Hint: tooltip string, which is shown on mouse-over for bookmark gutter icon
205	207		- Data.Tag: int value, for custom application needs
206	208		- Data.DeleteOnDelLine: bool, enables to auto delete item, when its line is deleted
207	209		- Data.ShowInBookmarkList: bool, for custom application needs
208	210
209	211		Kind specifies background color and gutter icon for bookmarks of this kind. Kind value 0 must not be used (previously value 0 meaned "no bookmark"), value 1 should be used for "usual" bookmarks, value\>1 should be used for custom application bookmarks. ATSynEdit has 2 events: to paint bookmark icon (from its kind), and to get color of bookmark (from its kind).
210	212
211	213		Bookmarks object is always sorted by line index. Duplicate bookmarks (for the same line index) are auto removed. To change bookmarks, use methods Add, Delete, DeleteForLine, Clear. Also use method Find.
212	214
213	215		### Strings.Bookmarks2 object
214	216
215	217		Same type as Strings.Bookmarks object. This list holds "background bookmarks", which have lower paint priority than usual bookmarks. So if a line has usual bookmark - it is painted, and if not - background bookmark is searched for this line and painted. Bookmarks2 allows to colorize entire lines, but not to interfere with usual bookmarks - it is "passive coloring". Additionally, marks in Bookmarks2 don't have gutter icon, and mouse-over tooltip. Marks in Bookmarks/Bookmarks2 use the same Kind values space.
216	218
217	219		### Carets object
218	220
219	221		type TATCarets in unit atsynedit_carets. Holds list of items of type TATCaretItem. Each caret item has properties:
220	222
221	223		- PosY: index of line in Strings object, 0-based
222	224		- PosX: offset of caret from line start, 0-based
223	225		- EndY, EndX: position for selection edge for this caret, or -1/-1 if no selection for this caret
224	226		- CoordY, CoordX: screen coordinates (usually you don't need these)
225	227
226	228		For forward sel, pair (PosY, PosX) is after pair (EndY, EndX); for backward sel the order is reversed. So if you want to get pos of selection start (e.g. to delete this selection), get minimal pair.
227	229
228	230		Carets object is sorted by text position, method Sort does this. Duplicate carets (they appear during work with multi-carets) are auto removed. If you try to add overlapping caret selections, they will be auto merged to one caret. To add/delete carets, use methods Add, Clear. Also ATSynEdit has methods DoCaretNNNNN, eg DoCaretSingle makes single caret.
229	231
230	232		### CaretsSel object
231	233
232	234		type TATCaretSelections in unit atsynedit_carets. It is helping object, internally it holds array of carets coordinates, sorted by text position, but only for carets with selection (carets w/o selection are not included). It is read-only, ie it's needed only to find some info about selections, not to store it. Finding some info about selections is much faster with CaretsSel object, though you can use Carets object too (slower). It uses binary search.
233	235
234	236		Note: object is updated (from contents of Carets) in Paint method, not immediately after you add/change something in Carets.
235	237
236	238		### Keymap object
237	239
238	240		type TATKeymap in unit atsynedit_keymap.
239	241
240	242		Holds list of keyboard actions of type TATKeymapItem. It's inited at start. And to init items at start, two "filling" procedures exist in code: one for TATSynEdit, and simpler one for TATEdit (single line version, less commands). And you can add more keymap items or change hotkeys for any keymap item.
241	243
242	244		Each keymap item has 2 (yet) hotkeys, second is needed for e.g.: Copy-to-clipboard (Ctrl+C and Ctrl+Ins), Paste-from-clipbd (Ctrl+V and Shift+Ins) etc.
243	245
244	246		When adding keymap item, you can set simple hotkeys (e.g. "Alt+Shift+F") or key combos (several simple hotkeys which must be pressed in order). Example adds commands with simple hotkey and combo:
245	247
246	248		``` pascal
247	249		var
248	250		M: TATKeymap;
249	251		const
250	252		cmd_My1 = 3000;
251	253		cmd_My2 = 3001;
252	254		begin
253	255		M.Add(cmd_My1, 'cmd with simple hotkey', ['Ctrl+Shift+F'], []);
254	256		M.Add(cmd_My2, 'cmd with 3 keys combo', ['Ctrl+B', 'Ctrl+B', 'Ctrl+M'], []);
255	257		```
256	258
257	259		After you added new keymap items, add reaction for them: use OnCommand event as usual.
258	260
259	261		### WrapInfo object
260	262
261	263		type TATWrapInfo in unit atsynedit_wrapinfo. Holds list of wrap items, each is info about wrapped part of line or about entire line:
262	264
263	265		- its original line index in Strings object (0-base)
264	266		- its char offset in original line (0-base)
265	267		- its length
266	268		- its indent size (if feature "wrapped indent" is on)
267	269		- its final-state: is it first/middle part of wrapped line, or final part
268	270
269	271		One wrap item renders on control as one short line. It is part of wrapped line or entire line. Also used for wrap-mode off, this is simple case - one wrap item per one line. Wrap items exist only for lines not hidden by folding feature (with Strings.LinesHidden\[i\]=true).
270	272
271	273		WrapInfo has weird property VirtualMode. This prop is set if a) no fold ranges created (ie no lexer is active, or lexer didn't create fold ranges), b) word wrapping is off. VirtualMode means that WrapInfo don't store any data in internal TList, it is empty and fast, it only reads props of Strings and returns them. Indeed, when no fold ranges, and word wrapping off, all items of WrapInfo must be simple "mirror" of Strings items props (and count is the same).
272	274
273	275		VirtualMode makes loading of huge logs (100-500Mb) ~1.5 times faster.
274	276
275	277		### Undo object
276	278
277	279		Holds list of actions for Undo/Redo. You must not touch it. Filled auto by changing-adding-deleting of lines in Strings object (by any API). Also holds end-of-lines markers (changed ends-of-lines can undo too).
278	280
279	281		Items in Undo object have 'group marker'. This means that some editor commands set this marker, and items after marked item will undo as a group (if option "Group undo" on). You can set group marker (for next editor action) by method SetGroupMark of Strings object.
280	282
281	283		### Gutter object
282	284
283	285		type TATGutter in unit atsynedit_gutter. Holds list of gutter items. Each gutter item has properties:
284	286
285	287		- Visible: gutter band is shown on gutter
286	288		- Size: width of gutter band
287	289		- Left/Right: calculated auto from Visible and Size, coordinates of band on control
288	290
289	291		To know which band of gutter does what, use properties of ATSynEdit: GutterBandNum (index of band for line numbers), GutterBandFold (index of band for folding) etc. Example shows/hides gutter column:
290	292
291	293		``` pascal
292	294		ed.Gutter[ed.GutterBandNum].Visible:= checkGutterNum.Checked;
293	295		ed.Gutter.Update;
294	296		ed.Update;
295	297		```
296	298
297	299		### GutterDecor object
298	300
299	301		type TATGutterDecor in unit atsynedit_gutter_decor. Holds list of items, which are painted over gutter, for decoration purpose. Items can hold short text strings (e.g. normal/square/curly brackets to show pair brackets in text), or icon from TImageList. If item has not empty Text, then text is shown, otherwise icon is shown. Each item has props:
300	302
301	303		- Data.LineNum: line index (in Strings object)
302	304		- Data.Tag: int value, for custom app needs
303	305		- Data.ImageIndex: icon index in TATSynEdit.ImagesGutterDecor image list
304	306		- Data.Text: short string
305	307		- Data.TextBold: bool, text font is bold
306	308		- Data.TextItalic: bool, text font is italic
307	309		- Data.TextColor: color of text
308	310		- Data.DeleteOnDelLine: bool, enables to auto delete item, when its line is deleted
309	311
310	312		Items in this object are auto adjusted when text is edited. But note: for this to work, you must assign GutterDecor object to Strings object prop GutterDecor1 or GutterDecor2.
311	313
312	314		Duplicate items (for the same line index) are auto removed. TATSynEdit.GutterBandDecor sets index of gutter band for decorations. If -1, then gutter band for bookmarks is used.
313	315
314	316		### Fold object
315	317
316	318		type TATSynRanges in unit atsynedit_ranges. Holds list of ranges which can be folded and show plus/minus on gutter. Each range is of type TATSynRange, it has properties:
317	319
318	320		- Y: starting line of range (0-based)
319	321		- Y2: ending line of range (if same as Y, plus/minus not shown on gutter)
320	322		- X: char-offset in starting line (must be \>0, 1 means fold from 1st char)
321	323		- Folded: boolean, state: folded/unfolded
322	324		- Staple: boolean, true if range has staple shown (vertical line on text area)
323	325		- Hint: string, shown in rectangle when range is folded
324	326
325	327		Example adds few ranges to text:
326	328
327	329		``` pascal
328	330		Edit1.Fold.Clear;
329	331		Edit1.Fold.Add(1, 4, 15, false, ''); //line 4 to 15, range1
330	332		Edit1.Fold.Add(1, 5, 9, false, ''); //line 5 to 9, nested into range1
331	333		Edit1.Fold.Add(1, 7, 8, false, ''); //line 7 to 8, nested into range2
332	334		```
333	335
334	336		- To fold/unfold a range, don't change Folded field, use methods of ATSynEdit: DoRangeFold, DoRangeUnfold.
335	337		- To fold/unfold all, use commands via DoCommand method: cCommand_FoldAll, cCommand_UnfoldAll.
336	338		- In Fold object, items are not sorted, but usually syntax-adapters add these ranges as sorted (by Y).
337	339		- Fold object has methods, which find ranges, e.g. all ranges which contain any line from N1 to N2, etc.
338	340
339	341		### Markers object
340	342
341	343		type TATMarkers in unit atsynedit_markers. Holds list of marker items. Each marker item has properties:
342	344
343	345		- PosX, PosY: position of marker (like caret position).
344	346		- LineLen: if not 0, render horizontal line to the left (LineLen\<0) or right (LineLen\>0).
345	347		- CoordX, CoordY: screen coordinates.
346	348		- CoordX2, CoordY2: screen coordinates of LineLen end.
347	349		- SelX, SelY: used in CudaText: when "collect marker" gets this marker, caret will be with selection.
348	350		- if SelY=0 - SelX is length of selection (single line selection)
349	351		- if SelY\>0 - SelY is Y-delta of selection end, SelX is absolute X of selection-end
350	352		- Tag (Int64): some integer value, useful for apps: e.g. CudaText holds here tabstop-index (several markers with the same index \>0 give multi-carets, when user jumps to one of markers).
351	353		- Value (Int64): some integer value, attached to marker.
352	354		- Ptr (TObject): some application-specific object. Object is freed automatically when marker item is freed.
353	355		- MicromapOnly (enum): where to render the marker: on text area, on micromap, on both text/micromap.
354	356
355	357		Markers are painted as red triangles below their positions (PosX, PosY). They are needed e.g. for making snippets, where user needs to jump over snippet's insert points and wants to see these points. Also it's good for IDE to have commands like "drop marker here", "remove last marker", "swap caret and last marker" etc (like CodeRush).
356	358
357	359		Example code from CudaText:
358	360
359	361		``` pascal
360	362		procedure EditorMarkerGotoLast(Ed: TATSynEdit; AndDelete: boolean);
361	363		var
362	364		Caret: TATCaretItem;
363	365		Mark: TATMarkerItem;
364	366		begin
365	367		if Ed.Carets.Count<>1 then exit;
366	368		if Ed.Markers.Count=0 then exit;
367	369		Caret:= Ed.Carets[0];
368	370		Mark:= Ed.Markers[Ed.Markers.Count-1];
369	371		Caret.PosX:= Mark.PosX;
370	372		Caret.PosY:= Mark.PosY;
371	373		if AndDelete then
372	374		Ed.Markers.Delete(Ed.Markers.Count-1);
373	375		Ed.DoGotoCaret(cEdgeTop);
374	376		Ed.Update;
375	377		end;
376	378		```
377	379
378	380		### Attribs object
379	381
380	382		type TATMarkers (same as for Markers). Holds list of additional color/font attribute items, these items are added to syntax hiliting and selection hiliting. Each item has properties:
381	383
382	384		- PosX, PosY: see Markers object.
383	385		- SelX, SelY: see Markers object.
384	386		- Ptr (TObject): object of type TATLinePartClass, which has Data field. This Data is record, it contains all color/font/borders properties of this attr.
385	387
386	388		Attribs object is used in CudaText: app adds attr items to hilite brackets, to hilite misspelled words, etc.
387	389
388	390		If you add attrib item, create new object of type TATLinePartClass, fill its Data, and pass object to TATMarkers.Add. This object is freed automatically if attrib item deleted or all attribs cleared.
389	391
390	392		### Colors object
391	393
392	394		Contains color properties of type TColor. For ex, Colors.TextFont is text font color, Colors.TextBG is text background color.
393	395
394	396		### Gaps object
395	397
396	398		type TATGaps in unit atsynedit_gaps. Holds list of items TATGapItem. Each item has properties:
397	399
398	400		- LineIndex: index in Strings object; and special value -1 is allowed: gap before the first line
399	401		- Size: height in pixels
400	402		- Tag: int value, to difference gaps from several plugins
401	403		- Bitmap: TBitmap which is painted on gap, when it's visible
402	404		- DeleteOnDelLine: bool, enables to auto delete item, when its line is deleted
403	405
404	406		Gap item paints as rectangle (it is owner-drawn), just between lines N and N+1, not overlapping text. When user adds/deletes lines, gaps auto-shift with their lines; gap is deleted if its line is deleted.
405	407
406	408		Use cases:
407	409
408	410		- App wants to show picture preview, when picture is linked in HTML. It creates small preview picture e.g. 100x50, and adds gap: gap size=52, picture height and 2 pixels of border.
409	411		- App runs linter on JS code, for JS errors it places bookmarks, and adds gaps with size=15 for error lines: in gaps it writes errors, maybe icons.
410	412
411	413		To add/remove gaps:
412	414
413	415		``` pascal
414	416		//to add
415	417		ed.Gaps.Add(NLine, NGapHeight, FSomeBitmap, NGapTag);
416	418		ed.Update;
417	419		//to delete this gap
418	420		ed.Gaps.DeleteForLineRange(NLine, NLine);
419	421		ed.Update;
420	422		```
421	423
422	424		Event OnDrawGap is used to paint gaps, it gets canvas, and rectangle on canvas. Note: if you add gap to the last line, you must turn on option OptLastLineOnTop, better don't turn it off later (to not scroll, when gap added/removed).
423	425
424	426		### DimRanges object
425	427
426	428		type TATDimRanges in unit atsynedit_dimranges. Holds list of ranges which shade/dim/fade text font color, ie blend font color with background color. Each range is of type TATDimRange, it has properties:
427	429
428	430		- LineFrom: range starts from this line (0-based)
429	431		- LineTo: range ends on this line (can use MaxInt)
430	432		- DimValue: dim value from 0 to 255. 0 means "no effect", 255 means "transparent text".
431	433
432	434		To dim all text except current paragraph, you must add 2 ranges: before/after paragraph, then correct line indexes in them.
433	435
434	436		There is no checking for line indexes, ranges can have any indexes, but overlapping indexes not good (first found range will give dim value).
435	437
436	438		Example adds 2 ranges and changes them later:
437	439
438	440		``` pascal
439	441		R1:= Ed.DimRanges.Add(0, 6, 100{dim value});
440	442		R2:= Ed.DimRanges.Add(20, MaxInt, 100{dim value});
441	443		Ed.Update;
442	444		//change ranges
443	445		R1.LineTo:= 10;
444	446		R2.LineFrom:= 30;
445	447		Ed.Update;
446	448		```
447	449
448	450		### Hotspots object
449	451
450	452		type TATHotspots in unit atsynedit_hotspots. Holds list of ranges, which need special tooltip on mouse-over. Each range is of type TATHotspotItem, it has props:
451	453
452	454		- PosX, PosY: start of range (text position)
453	455		- EndX, EndY: end of range
454	456		- Tag: some custom int value
455	457		- TagString: some custom string value
456	458
457	459		You can add hotspots via Add method, and find them later by Tag, by TagString, by text position - methods FindByPos, FindByTag, FindByTagString. To support mouse-over for these ranges, two events exist: OnHotspotEnter, OnHotspotExit.
458	460
459	461		Example of usage: in HTML file, app can find all HTML color tokens \#rrggbb, add hotspots for them, and store color value to Tag. Then on mouse-over app can show colored tooltip.
460	462
461	463		### Micromap object
462	464
463	465		type TATMicromap in unit atsynedit_micromap. Holds list of micromap's columns (by default only one column is added, and CudaText adds 2nd column to paint marks from plugins). The micromap is shown by ATSynEdit property OptMicromapVisible and must be painted by the app via OnDrawMicromap event. Micromap object has Columns property, "array of TATMicromapColumn".
464	466
465	467		Type TATMicromapColumn is record with the fields:
466	468
467	469		- NTag: Int64 tag value, so app can find this column by tag - app can change this
468	470		- NWidthPercents: Width of column in percents of average char width - app can change this
469	471		- NWidthPixels: Width of column in pixels - auto calculated, app must not change this
470	472		- NLeft, NRight: Control-related coordinates of column left and right edge - auto calculated, app must not change this
471	473
472	474		Micromap object holds Columns prop, and several methods to add/delete columns: ColumnAdd, ColumnDelete, and method ColumnFromTag to find columns by int tag. Application can paint anything on micromap, but it's recommented to paint small marks per editor lines. To get coordinates of such marks, use ATSynEdit method RectMicromapMark, it does calculations to get coords for all editor lines, to fill the entire micromap.
473	475
474	476		## What are the basic methods/properties?
475	477
476	478		Objects
477	479
478	480		- property Strings
479	481		- property Strings.Bookmarks
480	482		- property Strings.Bookmarks2
481	483		- property Carets
482	484		- property Gutter
483	485		- property GutterDecor
484	486		- property Keymap
485	487		- property Fold
486	488		- property Markers
487	489		- property Attribs
488	490		- property Colors
489	491		- property WrapInfo
490	492		- property Gaps
491	493		- property DimRanges
492	494		- property Hotspots
493	495		- property Micromap
494	496
495	497		Files
496	498
497	499		- procedure LoadFromFile(const AFilename: string): load text from file (filename uses utf-8)
498	500		- procedure SaveToFile(const AFilename: string): save text to file
499	501
500	502		States
501	503
502	504		- property Modified: modified state (cleared on file loading)
503	505		- property ModeOverwrite: mode insert/overwrite state (Ins key toggles it)
504	506		- property ModeReadOnly: mode read-only state
505	507
506	508		More
507	509
508	510		- procedure Update(AUpdateWrapInfo: boolean = false; AUpdateCaretsCoords: boolean = true): to repaint+invalidate; 1st param must be True to recalculate WrapInfo object (usually it's auto updated, but if text change detection don't work, e.g. Strings object changed directly, pass True here)
509	511		- procedure DoCommand(ACmd: integer; const AText: UnicodeString = ""): command runner, pass command code to run it (see file atsynedit_commands)
510	512		- property Text: unicodestring which gives entire editor text with LF separator
511	513
512	514		Caret
513	515
514	516		- procedure DoCaretSingle(AX, AY: integer): make single caret
515	517		- function CaretPosToClientPos(P: TPoint): TPoint: convert caret coords to screen coords
516	518		- function ClientPosToCaretPos(P: TPoint; out AEndOfLinePos: boolean): TPoint: convert screen coords to caret coords
517	519		- function IsLineWithCaret(ALine: integer): boolean: is line index contains any caret
518	520
519	521		Selection
520	522
521	523		(P.Y is line index, P.X is char offset in line, 0-based)
522	524
523	525		- property SelRect: for column selection, rectangle of column block
524	526		- function IsSelRectEmpty: is column selection exists
525	527		- procedure DoSelect_All: select all text (makes single caret)
526	528		- procedure DoSelect_Line(P: TPoint): select single line
527	529		- procedure DoSelect_Word(P: TPoint): select single word
528	530		- procedure DoSelect_LineRange(ALineFrom: integer; P: TPoint): select several lines from line index to given point
529	531
530	532		View
531	533
532	534		- property LineTop: index of line visible at the top of control (almost vertical scroll, though exact scroll pos is different, it considers WrapInfo object)
533	535		- property LineBottom: index of line visible at the bottom of control (because of folding you cannot simply calculate it)
534	536		- property ColumnLeft: index of left visible column (ie, horizontal scroll)
535	537		- procedure DoRangeFold(ARange: TATSynRange): fold range, which exists in the Fold object
536	538		- procedure DoRangeUnfold(ARange: TATSynRange): unfold range
537	539		- procedure DoScrollByDelta(Dx, Dy: integer): scroll editor area by Dx chars right and Dy lines down
538	540		- procedure DoGotoPos(APnt: TPoint; AIndentHorz, AIndentVert: integer): scroll editor to given caret pos
539	541
540	542		Options
541	543
542	544		I cannot post here options. See ATSynEdit properties beginning with "Opt", these are props which can change in design time in IDE. You can place on form ATSynEdit and see in IDE its "Opt" properties and see their values.
543	545
544	546		Encodings
545	547
546	548		- Strings.EncodingDetect: boolean
547	549		- Strings.Encoding: enum (cEncAnsi, cEncUTF8, cEncWideLE, cEncWideBE)
548	550		- Strings.EncodingCodepage: string (used for Encoding=cEncAnsi)
549	551		- Strings.SaveSignUtf8: boolean
550	552
551	553		## Basic example how to use?
552	554
553	555		- Add "uses ATSynEdit".
554	556		- Add variable "ed".
555	557		- Add OnCreate event to new form.
556	558		- How to load file "unit1.pas":
557	559
558	560		``` pascal
559	561		procedure TForm1.FormCreate(Sender: TObject);
560	562		begin
561	563		ed:= TATSynEdit.Create(Self);
562	564		ed.Parent:= Self;
563	565		ed.Align:= alClient;
564	566		ed.Font.Name:= 'Courier New';
565	567		ed.OptUnprintedVisible:= false;
566	568		ed.OptRulerVisible:= false;
567	569		ed.LoadFromFile(ExtractFilePath(Application.ExeName)+'unit1.pas');
568	570		end;
569	571		```
570	572
571	573		- How to save file: call "ed.SaveToFile()".
572	574
573	575		## How does it manage the coordinates?
574	576
575	577		Carets object contains list of caret items. Each caret item, e.g. Carets\[0\], has properties:
576	578
577	579		- PosY: line index in Strings object
578	580		- PosX: char offset from line start
579	581		- EndY, EndX: selection end for caret, both -1 if no selection
580	582		- CoordX, CoordY: control-relative coordinates of caret
581	583
582	584		Strings object holds UnicodeString's, where each WideChar gives offset=1, and even Tab char gives offset=1. Component auto-calculates properties CoordX/CoordY for all carets, screen coordinates. Don't touch CoordX/CoordY, change only PosX/PosY and EndX/EndY.
583	585
584	586		### Text position to/from screen coordinates
585	587
586	588		Methods allow to convert text position to/from control-relative coordinates (in pixels). Layout of gutter, ruler and other UI elements are already considered by methods.
587	589
588	590		``` pascal
589	591		function CaretPosToClientPos(P: TPoint): TPoint;
590	592		function ClientPosToCaretPos(P: TPoint;
591	593		out ADetails: TATPosDetails;
592	594		AGapCoordAction: TATGapCoordAction=cGapCoordToLineEnd): TPoint;
593	595		```
594	596
595	597		- Param ADetails: returned True if text pos is after real end-of-line, False if text pos is inside line.
596	598		- Param AGapCoordAction: you must specify here what to do if coordinates are over inter-line gap (see Gaps object).
597	599
598	600		Functions give Result.Y\<0 if cannot calculate pos. For example, if line index is too big or line with this index is fully folded.
599	601
600	602		Property OptCaretVirtual exists. If it's True, caret is allowed after end-of-line. Methods consider it.
601	603
602	604		### Text posistion to/from column index
603	605
604	606		To convert text coordinate X to/from column index (considering Tab chars), ATSynEdit has TabHelper object and methods of Strings object. Here is example, code which converts X of first caret to its column index:
605	607
606	608		``` pascal
607	609		var
608	610		ed: TATSynEdit;
609	611		caret: TATCaretItem;
610	612		//...
611	613
612	614		caret:= ed.Carets[0];
613	615		if ed.Strings.IsIndexValid(caret.PosY) then
614	616		begin
615	617		//optimized for huge lines
616	618		ColumnIndex:= ed.Strings.CharPosToColumnPos(caret.PosY, caret.PosX, ed.TabHelper)+1;
617	619		end;
618	620		```
619	621
620	622		## How to manage the caret, the selection?
621	623
622	624		See topic "Carets object". To change position of carets, get Carets property of editor, get each item Carets\[N\], and change caret items' properties PosX/PosY and/or EndX/EndY, then call editor's method Update. To change selection for any caret (each caret has own selection): get caret item, and change its propeties EndX/EndY (set both to -1 to remove selection), then call editor's method Update.
623	625
624	626		Better don't do overlapping selections (when e.g. selection of caret-2 overlaps selection of caret-3), but even here you can call Carets.Sort, which should sort carets by PosX/PosY and fix them.
625	627
626	628		You can delete and add caret items.
627	629
628	630		``` pascal
629	631		var
630	632		Caret: TATCaretItem;
631	633		i: integer;
632	634		begin
633	635		for i:= 0 to edit.Carets.Count-1 do
634	636		begin
635	637		Caret:= edit.Carets[i];
636	638		{
637	639		change here Caret.PosX and Caret.PosY
638	640		}
639	641		end;
640	642		edit.Update;
641	643		end;
642	644		```
643	645
644	646		## How to modify text?
645	647
646	648		See topic above about "Strings object". To change text, get Strings property of editor. "Strings.Count" is number of lines in object. Then access methods of Strings: LineAdd, LineInsert, LineDelete. To get/set lines by index, use properties of Strings: Strings.Lines\[i\], etc, listed above.
647	649
648	650		To do advanced changes, use TATStrings.Text* methods:
649	651
650	652		``` pascal
651	653		procedure TextInsert(AX, AY: integer; const AText: atString; AOverwrite: boolean;
652	654		out AShift, APosAfter: TPoint);
653	655		procedure TextAppend(const AText: atString; out AShift, APosAfter: TPoint);
654	656		procedure TextInsertColumnBlock(AX, AY: integer; ABlock: TATStrings;
655	657		AOverwrite: boolean);
656	658		procedure TextDeleteLeft(AX, AY: integer; ALen: integer; out AShift, APosAfter: TPoint);
657	659		procedure TextDeleteRight(AX, AY: integer; ALen: integer; out AShift,
658	660		APosAfter: TPoint; ACanDelEol: boolean=true);
659	661		function TextDeleteRange(AFromX, AFromY, AToX, AToY: integer; out AShift, APosAfter: TPoint): boolean;
660	662		procedure TextInsertEol(AX, AY: integer; AKeepCaret: boolean;
661	663		const AStrIndent: atString; out AShift, APosAfter: TPoint);
662	664		procedure TextDeleteLine(AX, AY: integer; out AShift, APosAfter: TPoint);
663	665		procedure TextReplaceInOneLine(AY, AX1, AX2: integer; const AText: atString);
664	666		procedure TextReplaceRange(AFromX, AFromY, AToX, AToY: integer;
665	667		const AText: atString; out AShift, APosAfter: TPoint);
666	668		function TextReplaceLines_UTF8(ALineFrom, ALineTo: integer; ANewLines: TStringList): boolean;
667	669		function TextSubstring(AX1, AY1, AX2, AY2: integer; const AEolString: string = #10): atString;
668	670		```
669	671
670	672		Strings.Lines\[i\] do not contain end-of-line chars. Usually not needed to change end-of-line chars. You can change them using Strings.LinesEnds\[i\].
671	673
672	674		- After changes in Strings object, always call editor.Update(true). Update(false) only repaints editor, Update(true) invalidates WrapInfo object first (must be called after changes to Strings, or after window resize).
673	675		- You can read Strings from one editor1 and set it to Strings of editor2. This will make editor2 having same strings object (needed for split-tab).
674	676
675	677		## How to highlight syntax?
676	678
677	679		There're 2 ways:
678	680
679	681		- OnCalcHilite event (better, if your code is small, e.g. colorize few tokens)
680	682		- Adapter (better, if your code is big, e.g. support for EControl lexers)
681	683
682	684		You can set handler of OnCalcHilite event. Adapter is different way to do the same. Instead of using event, you write code in the new class which is child of TATAdapterHilite. Then you link adapter to editor:
683	685
684	686		``` pascal
685	687		Adapter.AddEditor(editor1);
686	688		Adapter.AddEditor(editor2); //if 2 editors share the same text buffer
687	689		```
688	690
689	691		To unlink adapter from all editors, call:
690	692
691	693		``` pascal
692	694		Adapter.AddEditor(nil);
693	695		```
694	696
695	697		If adapter assigned, editor will call adapter's methods (first called adapter, next OnCalcHilite).
696	698
697	699		See file "atsynedit_adapters.pas". It has base class for such adapters. Main method in adapter, which is called by ATSynEdit is:
698	700
699	701		``` pascal
700	702		procedure OnEditorCalcHilite(Sender: TObject;
701	703		var AParts: TATLineParts;
702	704		ALineIndex, ACharIndex, ALineLen: integer;
703	705		var AColorAfterEol: TColor);
704	706		```
705	707
706	708		Parameters here:
707	709
708	710		- Sender: editor object.
709	711		- AParts: array of "parts": each part has Offset, Len, colors, font style. Adapter must create parts for entire string (1st part takes 1st chars of string, last part takes last chars of string). See code about TATLineParts.
710	712		- ALineIndex: index of passed line (0-based).
711	713		- ACharIndex: index of 1st char in line (it's not 0 if wrapped part of line is shown, 0-based).
712	714		- ALineLen: length of substring to hilite.
713	715		- AColorAfterEol: return here color for background of line after end-of-line. Return clNone if no color needed.
714	716
715	717		Real string which you must hilite: see example project how to get it.
716	718
717	719		## How to set same text-source to several editors?
718	720
719	721		Several editors can have same text source, text source is ATStrings object which holds
720	722
721	723		- same text for all editors
722	724		- separate folding states for each editor
723	725
724	726		Each editor holds its own WrapInfo object so wrapped states are separate. Each editor holds its own Carets object, so carets/selections are separate.
725	727
726	728		Tech details: items in ATStrings object have fields:
727	729
728	730		``` pascal
729	731		ItemHidden: packed array[0..cMaxStringsClients-1] of ByteBool;
730	732		// this line is fully hidden
731	733		ItemFoldFrom: packed array[0..cMaxStringsClients-1] of byte;
732	734		// 0: line not folded
733	735		// >0: line folded from this char-pos
734	736		```
735	737
736	738		(constant can be changed in source). These fields allow to hold separate fold-info for each "editor client" of ATStrings. Each client must have it's own EditorIndex (0 to cMaxStringsClients-1). Example, make 4 editors ed0..ed3.
737	739
738	740		- change cMaxStringsClients to 4
739	741		- set ed0.EditorIndex:=0
740	742		- set ed1.EditorIndex:=1
741	743		- set ed2.EditorIndex:=2
742	744		- set ed3.EditorIndex:=3
743	745		- set ed1.Strings:=ed0.Strings
744	746		- set ed2.Strings:=ed0.Strings
745	747		- set ed3.Strings:=ed0.Strings
746	748
747	749		If user changes text in ed3, ed3 will update but others will not: you need to force it:
748	750
749	751		- ed0.Update(true)
750	752		- ed1.Update(true)
751	753		- ed2.Update(true)
752	754
753	755		## How to add/change commands?
754	756
755	757		To change action of internal commands (file atsynedit_commands.pas) you need to use event OnCommand which can do any action for any command (and return AHandled=True to disable default code). Better use OnCommand handler for all commands, even new ones. So you can call DoCommand() and have one handler to do anything.
756	758
757	759		Example func which adds new commands to Keymap object:
758	760
759	761		``` pascal
760	762		const
761	763		cmd_FileNew = 2500;
762	764		...
763	765
764	766		procedure InitKeymapApp(M: TATKeymap);
765	767		begin
766	768		M.Add(cmd_FileNew, 'file: new file', ['Ctrl+N'], []);
767	769		M.Add(cmd_FileOpen, 'file: open file', ['Ctrl+O'], []);
768	770		M.Add(cmd_FileSave, 'file: save file', ['Ctrl+S'], []);
769	771		...
770	772		end;
771	773		```
772	774
773	775		Example handler for new commands: some close editor tabs (special case: cannot close tabs just inside OnCommand) and some commands copy something to clipboard:
774	776
775	777		``` pascal
776	778		procedure TfmMain.EditorOnCommand(Sender: TObject; Cmd: integer; var Handled: boolean);
777	779		begin
778	780		Handled:= true; //by default command marked as handled
779	781		case Cmd of
780	782		cmd_FileNew,
781	783		cmd_FileOpen,
782	784		cmd_FileClose,
783	785		cmd_FileCloseAll,
784	786		cmd_FileReopen:
785	787		begin
786	788		//these commands close tabs so cannot handle here.
787	789		//we start timer which will handle them.
788	790		TimerCmd.Tag:= Cmd;
789	791		TimerCmd.Enabled:= true;
790	792		end;
791	793
792	794		cmd_CopyLine: DoCopyLine;
793	795		cmd_CopyFilenameFull: DoCopyFilenameFull;
794	796		cmd_CopyFilenameDir: DoCopyFilenameDir;
795	797		cmd_CopyFilenameName: DoCopyFilenameName;
796	798
797	799		else
798	800		Handled:= false; //unknown command: don't mark handled
799	801		end;
800	802		end;
801	803		```
802	804
803	805		## How to emulate Edit, Combobox?
804	806
805	807		Special child of ATSynEdit exists: ATEdit. It's single line control in which all multiline text editing is disabled. And paste can give only single line. And scrollbars are disabled. And many commands (like "Move lines up/down") are removed from Keymap object.
806	808
807	809		Special child of ATEdit exists: ATComboEdit. It has micromap area which paints dropdown arrow to look like combobox. Click on this arrow gives popup-menu with entered variants.
808	810
809	811		![](/wiki-images/3/3b/Atsynedit_combo.png)
810	812
811	813		Variants must be added to history by user code, using OnCommand handler: react to command "cCommand_KeyEnter". Example of handler:
812	814
813	815		``` pascal
814	816		procedure TfmCombo.ComboCommand(Sender: TObject; ACmd: integer;
815	817		var AHandled: boolean);
816	818		var
817	819		s: string;
818	820		n: integer;
819	821		begin
820	822		if ACmd=cCommand_KeyEnter then
821	823		begin
822	824		with ed do
823	825		begin
824	826		s:= UTF8Encode(Trim(Text));
825	827
826	828		Text:= '';
827	829		DoCaretSingle(0, 0);
828	830
829	831		n:= Items.IndexOf(s);
830	832		if n>=0 then Items.Delete(n);
831	833		Items.Insert(0, s);
832	834		end;
833	835		AHandled:= true;
834	836		end;
835	837		end;
836	838		```
837	839
838	840		## What props are useful for statusbar?
839	841
840	842		- number of carets: Carets.Count
841	843		- positions of carets: Carets.Items\[i\].PosX (column), PosY (line)
842	844		- text encoding: Strings.Encoding
843	845		- cEncAnsi: then codepage is given by Strings.EncodingCodepage
844	846		- cEncUTF8: then presence of utf8 bom is given by Strings.SaveSignUtf8
845	847		- cEncWideLE, cEncWideBE: then presense of Unicode bom is given by Strings.SaveSignWide
846	848		- text line endings (win/unix/mac): Strings.Endings
847	849		- tab-char width: OptTabSize
848	850		- tab-char entered by spaces: OptTabSpaces
849	851		- index of top visible line: LineTop
850	852		- index of left visible column: ColumnLeft
851	853		- modified state: Modified
852	854		- read-only mode: ModeReadOnly
853	855		- insert/overwrite mode: ModeOverwrite
854	856		- word-wrap mode: OptWrapMode
855	857		- unprinted chars shown: OptUnprintedVisible
856	858		- selection: get Carets.Items\[i\].PosX/PosY/EndX/EndY, for state of column selection get IsSelRectEmpty, SelRect
857	859
858	860		## How to customize popup menu?
859	861
860	862		These properties allow to change all menus in control (you cannot modify default menu):
861	863
862	864		- PopupText: for text area
863	865		- PopupRuler
864	866		- PopupMinimap
865	867		- PopupMicromap
866	868		- PopupGutterBm: for bookmarks column
867	869		- PopupGutterFold: for folding column
868	870		- PopupGutterNum: for line numbers column
869	871
870	872		Prop OptMouse* exists, which allows to show menus on mouse-down or on mouse-up.
871	873
872	874		## How to know indexes of changed lines in OnChange?
873	875
874	876		You have event Strings.OnLog. It gives parameters:
875	877
876	878		- ALine: index of line at which change occurs
877	879		- ALen: len of text which is added (ALen\>0) or deleted (ALen\<0) at line start
878	880
879	881		Get the log, save it, and then parse it during OnChange.
880	882
881	883		## How to export text to HTML?
882	884
883	885		Unit atsynedit_export_html has the function which does HTML report. It has several parameters to customize output. See example of usual parameters in the demo_editor.
884	886
885	887		ATSynEdit has API which allows to make report to any format. It's function DoCalcLineHiliteEx. It returns syntax highlight info for any line. Info is stored in TATLineParts struct, see HTML exporter code how to use it.
886	888
887	889		## Short description of events?
888	890
889	891		- OnBeforeCalcHilite: Called before OnCalcHilite for first visible line.
890	892		- OnCalcBookmarkColor: Called to determine color of bookmark (background color of line with bookmark).
891	893		- OnCalcHilite: Called to calculate syntax highlight for a line (or wrapped part of line). You need to fill TATLineParts struct for this line.
892	894		- OnCalcStaple: Called to determine color of block staple (vertical line which is painted near fold-ranges).
893	895		- OnChange: Called after any command which changes text.
894	896		- OnChangeCaretPos: Called after any command which changes caret(s) position(s).
895	897		- OnChangeState: Called after any command which changes editor state, such as read-only, insert/overwrite, word-wrap etc.
896	898		- OnClickDouble: Called on double-click on text area.
897	899		- OnClickGutter: Called on click on gutter area.
898	900		- OnClickMicromap: Called on click on micromap area.
899	901		- OnClickMiddle: Called on middle button click on text area.
900	902		- OnClickTriple: Called on triple-click on text area.
901	903		- OnClickMoveCaret: Called just before changing caret pos via mouse click (you get prev caret pos, new caret pos).
902	904		- OnClickEndSelect: Called just after mouse-up, if single selection made (you get selection start pos, end pos).
903	905		- OnCommand: Called before running any command. You can disable any command processing, or perform custom processing before/instead of command.
904	906		- OnCommandAfter: Called after running command.
905	907		- OnDrawBookmarkIcon: Called on painting gutter mark for line with bookmark.
906	908		- OnDrawEditor: Called after painting entire text area.
907	909		- OnDrawLine: Called after painting line (or wrapped part of line) on canvas. You can paint some "image" over this line.
908	910		- OnDrawMicromap: Called on painting micromap area.
909	911		- OnDrawRuler: Called after painting ruler area.
910	912		- OnScroll: Called after any command which scrolls text.
911	913		- OnPaste: Called just before pasting text. App can disable/override default pasting.
912	914		- OnHotspotEnter: Called when mouse moving enters one of the ranges in Hotspots object.
913	915		- OnHotspotExit: Called when mouse moving exits hotspot.
914	916
915	917		## What is logic of grouped-undo?
916	918
917	919		There're kinds of group-marks in undo-items: hard-marks, soft-marks.
918	920
919	921		- Hard-marks are placed on undo-items if you call Strings.BeginUndoGroup, editing, Strings.EndUndoGroup. All items marked with hard-marks are undone as group, even of OptUndoGrouped=false.
920	922		- Soft-marks used only if OptUndoGrouped=true. Soft-marks are placed on one next undo-item, when user does mouse click (or some similar action); or in code by call Strings.SetGroupMark. All items beginning with last soft-marked item are undone as group.
921	923
922	924		Example 1. OptUndoGrouped=true, such undo-items exist:
923	925
924	926		- item1
925	927		- item2
926	928		- item3, soft-mark
927	929		- item4
928	930		- item5, hard-mark
929	931		- item6, hard-mark
930	932		- item7
931	933		- item8, soft-mark
932	934		- item9
933	935		- item10
934	936
935	937		Undo:
936	938
937	939		- undone: item10..8; until soft-mark.
938	940		- undone: item7..3; until soft-mark.
939	941		- undone: item2..1.
940	942
941	943		Example 2. OptUndoGrouped=false, undo-items:
942	944
943	945		- item1
944	946		- item2
945	947		- item3, hard-mark
946	948		- item4, hard-mark
947	949		- item5, hard-mark
948	950		- item6
949	951		- item7
950	952
951	953		Undo:
952	954
953	955		- Undone: item7
954	956		- Undone: item6
955	957		- Undone: item5..3
956	958		- Undone: item2
957	959		- Undone: item1
958	960
959	961		Soft-marks also used together with hard-marks. Soft-mark is placed with first hard-mark after call Strings.BeginUndoGroup. This allows to undo N groups of edits, if many items hard-marked (w/out gaps).
960	962
961	963		Example 3. Undo-items:
962	964
963	965		- item1, hard-mark
964	966		- item2, hard-mark, soft-mark
965	967		- item3, hard-mark
966	968		- item4, hard-mark, soft-mark
967	969		- item5, hard-mark
968	970		- item6, hard-mark
969	971
970	972		Undo:
971	973
972	974		- undone: item6..4
973	975		- undone: item3..2
974	976		- undone: item1
975	977
976	978		## How to record/playback macros?
977	979
978	980		Macro support must be done on app level, component does support by event OnCommand. Handle OnCommand and you get all command codes which run. Real app adds more commands in Keymap object and it must decide which of them it wants to record (e.g. don't record commands to show dialogs, and record commands which comment/uncomment lines).
979	981
980	982		To playback macro, call DoCommand for all codes in macro.
981	983
982	984		Hint. CudaText also adds 3 commands to help with macros:
983	985
984	986		- "mouse click" (command recorded in OnClick event of editor)
985	987		- "goto pos" (command recorded by GoTo dialog)
986	988		- "finder action" (command recorded when doing find/replace actions)
987	989
988	990		## How to configure modifier-keys with click?
989	991
990	992		You can configure some of mouse clicks with modifier keys: simple click, Ctrl+click, Shift+click, Ctrl+Shift+click, middle click, etc. Property MouseMap configures it, it's array, type TATMouseActions. Default code configures it in InitMouseActions like this:
991	993
992	994		``` pascal
993	995		procedure InitMouseActions(var M: TATMouseActions);
994	996		//...
995	997		begin
996	998		SetLength(M, 0);
997	999		Add(cMouseActionClickSimple, [ssLeft]);
998	1000		Add(cMouseActionClickRight, [ssRight]);
999	1001		Add(cMouseActionClickAndSelBlock, [ssLeft, ssShift]);
1000	1002		Add(cMouseActionMakeCaret, [ssLeft, ssXControl]);
1001	1003		Add(cMouseActionMakeCaretsColumn, [ssLeft, ssXControl, ssShift]);
1002	1004		Add(cMouseActionNiceScrolling, [ssMiddle]);
1003	1005		//...
1004	1006		```
1005	1007
1006	1008		## Does it use PrimarySelection on gtk?
1007	1009
1008	1010		It can use it, all methods which work with clipboard, get AClipboardObject:TClipboard, here you can pass Clipboard, PrimarySelection, SecondarySelection.
1009	1011
1010	1012		Command codes for Paste: exist for Clipboard, and for PrimarySelection. This is part which reacts to command codes:
1011	1013
1012	1014		``` pascal
1013	1015		cCommand_ClipboardCopy: Res:= DoCommand_ClipboardCopy(false, Clipboard);
1014	1016		cCommand_ClipboardCopyAdd: Res:= DoCommand_ClipboardCopy(true, Clipboard);
1015	1017		cCommand_ClipboardCut: Res:= DoCommand_ClipboardCut(Clipboard);
1016	1018
1017	1019		//use Clipboard:TClipboard
1018	1020		cCommand_ClipboardPaste: Res:= DoCommand_ClipboardPaste(false, false, Clipboard);
1019	1021		cCommand_ClipboardPaste_Select: Res:= DoCommand_ClipboardPaste(false, true, Clipboard);
1020	1022		cCommand_ClipboardPaste_KeepCaret: Res:= DoCommand_ClipboardPaste(true, false, Clipboard);
1021	1023		cCommand_ClipboardPaste_Column: Res:= DoCommand_ClipboardPasteColumnBlock(false, Clipboard);
1022	1024		cCommand_ClipboardPaste_ColumnKeepCaret: Res:= DoCommand_ClipboardPasteColumnBlock(true, Clipboard);
1023	1025
1024	1026		//same, but use PrimarySelection:TClipboard
1025	1027		cCommand_ClipboardAltPaste: Res:= DoCommand_ClipboardPaste(false, false, PrimarySelection);
1026	1028		cCommand_ClipboardAltPaste_Select: Res:= DoCommand_ClipboardPaste(false, true, PrimarySelection);
1027	1029		cCommand_ClipboardAltPaste_KeepCaret: Res:= DoCommand_ClipboardPaste(true, false, PrimarySelection);
1028	1030		cCommand_ClipboardAltPaste_Column: Res:= DoCommand_ClipboardPasteColumnBlock(false, PrimarySelection);
1029	1031		cCommand_ClipboardAltPaste_ColumnKeepCaret: Res:= DoCommand_ClipboardPasteColumnBlock(true, PrimarySelection);
1030	1032		```
1031	1033
1032	1034		Default code uses PrimarySelection in one place: on copy, it copies to Clipboard, then (under Linux/Mac) copies the same to PrimarySelection.
1033	1035
1034	1036		To make middle-button-click paste from PrimarySelection, you need to handle OnClickMiddle, here's example from CudaText:
1035	1037
1036	1038		``` pascal
1037	1039		procedure TEditorFrame.EditorOnClickMiddle(Sender: TObject; var AHandled: boolean);
1038	1040		begin
1039	1041		AHandled:= false;
1040	1042		if EditorOps.OpMouseMiddleClickPaste then
1041	1043		begin
1042	1044		AHandled:= true;
1043	1045		(Sender as TATSynEdit).DoCommand(cmd_MouseClickAtCursor);
1044	1046		(Sender as TATSynEdit).DoCommand(cCommand_ClipboardAltPaste); //uses PrimarySelection:TClipboard
1045	1047		exit;
1046	1048		end;
1047	1049		end;
1048	1050		```
1049	1051
1050	1052		## How to handle OnCalcLineHilite event
1051	1053
1052	1054		This event has type:
1053	1055
1054	1056		``` pascal
1055	1057		type
1056	1058		TATSynEditCalcHiliteEvent = procedure(Sender: TObject; var AParts: TATLineParts;
1057	1059		ALineIndex, ACharIndex, ALineLen: integer; var AColorAfterEol: TColor) of object;
1058	1060		```
1059	1061
1060	1062		Handler gets:
1061	1063
1062	1064		- ALineIndex: index of line (in Strings object)
1063	1065		- ACharIndex: offset of fragment in line (not trivial only if line is wrapped)
1064	1066		- ALineLen: length of fragment in line (in WideChars)
1065	1067
1066	1068		Handler must fill:
1067	1069
1068	1070		- AParts: array of highlighted parts, one part per one "syntax token" (e.g. one symbol, one keyword, one string const, one comment, etc). Fill all other parts with zeros.
1069	1071		- AColorAfterEol: color of background after line end (for empty area).
1070	1072
1071	1073		Handler must handle the situation of line-wrapping inside long comments (or long string constants, etc), when one fragment gives part for ALineIndex=N, and next fragment gives part for ALineIndex=N+1.
1072	1074
1073	1075		Example. Handler gets string with Pascal syntax like "procedure AB(name: word)". It must create such "parts" for this string:
1074	1076
1075	1077		- part\[0\]: for "procedure": TATLinePart properties: offset=0, len=9, etc
1076	1078		- part\[1\]: for "AB": offset=10, len=2
1077	1079		- part\[2\]: for "(": offset=12, len=1
1078	1080		- part\[3\]: for "name": offset=13, len=1
1079	1081		- part\[4\]: for ":": offset=17, len=1
1080	1082		- part\[5\]: for "word": offset=19, len=4
1081	1083		- part\[6\]: for ")": offset=23, len=1
1082	1084		- other parts must have offset=0, len=0
1083	1085
1084	1086		## Details about highlighting rendering
1085	1087
1086	1088		Central procedure is DoCalcLineHilite. For items of WrapInfo object, it calculates "line parts" (array TATLineParts of record TATLinePart). Each "part" here is one colored/styled fragment of string. After line parts are calculated, they pass to ATSynEdit_CanvasProc.CanvasTextOut to render.
1087	1089
1088	1090		DoCalcLineHilite works like this:
1089	1091
1090	1092		- Updates adapter's "dynamic hilites enabled" flag (to on/off) and calls adapter's OnCalcLineHilite. This makes initial version of line parts.
1091	1093		- Calculated line parts are added to cache (same calculation of same WrapInfo item will not happen, only cache item is used).
1092	1094		- Updates line parts via OnCalcHilite event (it's additional method to hilite, first is adapter, usually only adapter is used).
1093	1095		- Calls DoPartCalc_ApplyAttribsOver to apply Attribs object to line parts. E.g. add parts for spell-checker bad words. E.g. add parts for underlined URLs.
1094	1096		- Calls DoPartCalc_ApplySelectionOver to apply selection (for all multi-carets, or one column selection) to parts.
1095	1097
1096	1098		DoPartCalc_ApplySelectionOver is complex function. It updates TATLineParts. How it works:
1097	1099
1098	1100		- It tests entire TATLineParts - is it all selected (optimization for selected-all), or all unselected (optimization for selected-none), or partly selected.
1099	1101		- If all selected, it just marks all parts (already calc'ed) with selection color. If partly selected, it finds parts, which are all/partly selected.
1100	1102		- For parts, which are all selected, it marks them with selection color.
1101	1103		- For parts, which are partly selected, it makes slow loop over offsets in parts. This slow loop finds chars which are selected and inserts new parts (with selection color) for them.
1102	1104
1103	1105		To find/insert parts to TATLineParts, funcs DoPartFind/ DoPartInsert are used.
1104	1106
1105	1107		## How to control vert/horz scrolling?
1106	1108
1107	1109		Property LineTop is index of top visible line, it is not precise vert scroll position, if long wrapped lines present.
1108	1110
1109	1111		Public prop: WrapInfo, it's list of wrapinfo items. You can read it to get all info about wrapped lines, at which offsets they are wrapped. This allows to make smart jump of caret on wrapped lines.
1110	1112
1111	1113		Public props: ScrollVert, ScrollHorz. They are records, NPos is scroll pos. ScrollVert.NPos is index in WrapInfo list, change it to make precise scrolling (call Update() then). ScrollHorz.NPos is horz scroll pos, now it's the same as prop ColumnLeft.
1112	1114
1113	1115		Method DoScrollByDelta(Dx, Dy) allows to increment/decrement horz (Dx) and vert (Dy) scroll positions.
1114	1116
1115	1117		## When Update call is needed?
1116	1118
1117	1119		First param of Update() method is boolean: force updating the WrapInfo object.
1118	1120
1119	1121		- Update(true): needed if you changed Strings contents - directly via Strings object; or changed Fold ranges - directly via Fold object. Ie, if WrapInfo object needs update (and component cannot detect this automatically).
1120	1122		- Update(false): needed if you only changed look, ie carets, scroll position, bookmarks, markers, etc.
1121	1123		- no Update() call is needed, if you only called DoCommand(). DoCommand does it automatically.
1122	1124
1123	1125		## Behaviour of column selection
1124	1126
1125	1127		ATSynEdit gives two modes of column selection, which have differences when you select over wrapped lines, or lines with full-width characters. This is controlled by property OptCaretsPrimitiveColumnSelection.
1126	1128
1127	1129		- Value True: "pritimive mode" which behaves much like Sublime Text. In this mode editor places multi-selections over visual rectangle of characters. In this mode, one line can have 6 chars selected, and another line can have 8 chars selected. This depends on visual positions of chars in those lines.
1128	1130
1129	1131		- Value False: in this mode, all affected lines have the same number of selected chars. But when full-width chars (e.g. CJK) are present in text, selection may look weird. Here is an example picture where starting lines are ASCII and ending lines have full-width chars.
1130	1132
1131	1133		![](/wiki-images/5/5b/Cudatext-column-sel-cjk.png)
1132	1134
1133	1135		It is not a bug. In this example, user selected column block from column 7 (at line 1) until column 20 (at line 6), so column block takes columns 7...20 from all lines. On first ASCII lines, columns 7...20 take different visual area, than columns on last lines. When you copy/paste that block to another program, block may look differently. But that block contains equal number of chars on each line.
1134	1136
1135	1137		Even more weird look happens when user selects column block over word-wrapped lines.
1136	1138
1137	1139		![](/wiki-images/b/ba/Cudatext-column-sel-weird.png)
1138	1140
1139	1141		Here is the code's logic in all these cases (with full-width characters and with word-wrapped lines). Code calculates (line1, column1) text position of column block left-top edge. Then code calculates (line2, column2) text position of column block right-bottom edge. Then code selects characters in range column1...column2 in all those affected lines line1...line2. And this code logic produces so weird look in word-wrapped mode.
1140	1142
1141	1143		## Horizontal scrollbar only increases but never shrinks?
1142	1144
1143	1145		Horizontal scrollbar has unusual behaviour: its width only increases (when long lines appear in the visible area). It never shrinks when we scroll to shorter lines. It was made as a workaround to GTK2 widgetset freezes - it freezes when scrollbar shows/hides/shows/hides/etc on scrolling.
1144	1146
1145	1147		You can try to disable this workaround in file atsynedit_defines.inc:
1146	1148
1147	1149		``` pascal
1148	1150		{$define fix_horzscroll} //workaround for gtk2 widgetset unstable: it freezes app
1149	1151		//when horz-scroll hides/shows/hides/...
1150	1152		//ok also for win32
1151	1153		```
1152	1154
1153	1155		## more
1154	1156
1155	1157		# Auto-completion lists
1156	1158
1157	1159		## General auto-completion API
1158	1160
1159	1161		You need to install package ATSynEdit_Cmp, from repo <https://github.com/Alexey-T/ATSynEdit_Cmp> .
1160	1162
1161	1163		Unit atsynedit_cmp_form (from ATSynEdit_Cmp package) has the function to show completion listbox in the editor. This listbox is not modal, it only emulates modality of some degree. It keeps editor caret blinking. While completion listbox is shown, editor doesn't get keyboard input, but listbox passes typing letters/Backspace/Left/Right to the editor, so it looks like editor gets some part of keyboard input. Listbox performs insertion of chosen item on Enter/Tab keys, and it hides on Esc-key or clicking outside of the listbox.
1162	1164
1163	1165		``` pascal
1164	1166		type
1165	1167		TATCompletionPropEvent = procedure (Sender: TObject;
1166	1168		AContent: TStringList; out ACharsLeft, ACharsRight: integer) of object;
1167	1169		TATCompletionResultEvent = procedure (Sender: TObject;
1168	1170		const ASnippetId: string; ASnippetIndex: integer) of object;
1169	1171
1170	1172		procedure EditorShowCompletionListbox(AEd: TATSynEdit;
1171	1173		AOnGetProp: TATCompletionPropEvent;
1172	1174		AOnResult: TATCompletionResultEvent = nil;
1173	1175		AOnChoose: TATCompletionResultEvent = nil;
1174	1176		const ASnippetId: string = '';
1175	1177		ASelectedIndex: integer = 0;
1176	1178		AAllowCarets: boolean = false);
1177	1179		```
1178	1180
1179	1181		Callback AOnGetProp params:
1180	1182
1181	1183		- AContent: list of lines, each line is S_id+'\\|'+S_text+'\\|'+S_desc. S_id is a prefix before actual text (good to pass here short texts: "var", "func"). S_text (it is usually second item) is text which is inserted into editor on closing listbox. After id/text several items may exist, all '\\|'-separated, they will show in additional listbox columns. For example, this TStringList line makes the listbox line of 3 columns:
1182	1184
1183	1185		``` pascal
1184	1186		'func\|FuncName\|(param1, param2)'#9'Func description';
1185	1187		```
1186	1188
1187	1189		- - If you need to insert not only S_text but also additional substring (showing in the listbox only S_text), use such S_text: S_text+#1+S_before_caret+#1+S_after_caret (also substrings will be added before and after caret). This is used by HTML autocompletion: here S_before_caret is "\>" and S_after_caret is "\</tag\>".
1188	1190		- At the end of lines, you may add Chr(9)+S_tooltip: string S_tooltip will show outside of listbox, in a tooltip, when user selects its line. To show multi-line tooltip, separate it with Chr(2).
1189	1191
1190	1192		- ACharsLeft, ACharsRight: count of chars, to the left and right of the caret, which will be replaced by selected listbox item. These counts must be detected by app. Some app may need to count only word chars, some may need spaces/brackets.
1191	1193
1192	1194		Notes:
1193	1195
1194	1196		- Function EditorShowCompletionListbox doesn't work for a) read-only editor, b) multi-carets.
1195	1197		- You can change colors/sizes/font of listbox: see unit source, it gives the global variable (record with many fields).
1196	1198
1197	1199		## Auto-completion using acp-files
1198	1200
1199	1201		Unit atsynedit_cmp_acpfiles has the function to show auto-completion listbox, from CudaText/SynWrite .acp files. Acp file must be in the format described in the SynWrite help file. You may copy acp files from CudaText distro, or from additional lexers, ie from CudaText lexers on CudaText.SF.net.
1200	1202
1201	1203		![](/wiki-images/a/a3/Cudatext-php-complete.png)
1202	1204
1203	1205		## Auto-completion for CSS
1204	1206
1205	1207		Unit atsynedit_cmp_css has the function to show auto-completion listbox, for CSS syntax. You must pass path of the file "data/autocompletespec/css_list.ini" from CudaText distro. CSS completion supports several modes:
1206	1208
1207	1209		- caret is on css attrib before ":" char - then list of css attribs is shown (which match the substring under caret),
1208	1210		- caret is after css attrib and ":" char (before closing ";") - then list of values for this attrib is shown.
1209	1211		- and more
1210	1212
1211	1213		![](/wiki-images/5/55/Cudatext-css-complete.png)
1212	1214
1213	1215		## Auto-completion for HTML
1214	1216
1215	1217		Unit atsynedit_cmp_html has the function to show auto-completion listbox, for HTML syntax. You must pass path of the file "data/autocompletespec/html_list.ini" from CudaText distro. HTML completion supports several modes:
1216	1218
1217	1219		- caret on opening/closing tag name: list of tags shown
1218	1220		- caret after tag, on attribute place before "=": list of attribs for found tag shown
1219	1221		- caret after tag, after attribute, after "=": list of values of found tag+attrib shown
1220	1222		- and more
1221	1223
1222	1224		![](/wiki-images/7/7b/Cudatext-html-complete.png)
1223	1225
1224	1226		# Finder
1225	1227
1226	1228		Finder class TATEditorFinder is in unit atsynedit_finder. To use it, create Finder object and set its props:
1227	1229
1228	1230		- Editor: editor object (text will be read automatically)
1229	1231		- StrFind: search-string (simple string or regex)
1230	1232		- StrReplace: replace-string (simple string or some regex, eg with "\$0", "\$1")
1231	1233		- boolean search flags:
1232	1234		- OptRegex: treat StrFind/StrReplace as regex
1233	1235		- OptCase: case-sensitive (for normal and regex modes)
1234	1236		- OptWords: whole-words search (for non-regex mode, for regex you must use "\b" specifier in search-string)
1235	1237		- OptBack: backward search (for non-regex mode)
1236	1238		- OptWrapped: continue search from top, if bottom reached (for back-search: continue from bottom, if top reached)
1237	1239		- OptInSelection: do search/replace in selection only (limitation exists: only 1st selection used)
1238	1240		- OptFromCaret: search goes from position of first caret (else: from start/end of text)
1239	1241		- OptConfirmReplace: each replace will occur after event OnConfirmReplace
1240	1242
1241	1243		Dialog of demo:
1242	1244
1243	1245		![](/wiki-images/b/b3/Atsynedit_finder.png)
1244	1246
1245	1247		Methods to find/replace text (they will place selection on found match, and scroll editor to caret, except method CountAll):
1246	1248
1247	1249		``` pascal
1248	1250		function DoAction_FindSimple(const APosStart: TPoint): boolean;
1249	1251		function DoAction_FindOrReplace(AReplace, AForMany: boolean; out AChanged: boolean;
1250	1252		AUpdateCaret: boolean): boolean;
1251	1253		function DoAction_ReplaceSelected(AUpdateCaret: boolean): boolean;
1252	1254		procedure DoAction_FindAll(AResults: TATFinderResults; AWithEvent: boolean);
1253	1255		function DoAction_CountAll(AWithEvent: boolean): integer;
1254	1256		procedure DoAction_ExtractAll(AWithEvent: boolean; AMatches: TStringList; ASorted: boolean;
1255	1257		ADuplicates: TDuplicates);
1256	1258		function DoAction_ReplaceAll: integer;
1257	1259		```
1258	1260
1259	1261		Found position and len are saved in props: MatchPos, MatchLen. Internally Finder object uses ATStringBuffer to read editor lines into buffer and search inside buffer. Then ATStringBuffer methods used to calculate caret position (from buffer offset) and place caret/selection. Note for regex search: buffer contains only "\n" line ends, other ends don't happen (original file may have any ends).
1260	1262
1261	1263		Finder has events:
1262	1264
1263	1265		- OnProgress: allows to show progressbar during search
1264	1266		- OnFound: called when result found
1265	1267		- OnConfirmReplace: called before replacing text (to show confirmation) if OptConfirmReplace set
1266	1268
1267	1269		Finder can handle multi-selections, by option OptInSelection. Selections are handled by CountAll, ReplaceAll. For other actions, selections don't make sense, because find-next makes new smaller selection (for found fragment) so prev big selection is lost. Tech note for replace-all: selections are looked from top to bottom, if they don't have common lines, and looked from bottom to top, if they have. This is done to not break lines, which are touched by 2+ selections. Count-all handles selections from top to bottom.
1268	1270
1269	1271		# Adapters
1270	1272
1271	1273		## Adapters description
1272	1274
1273	1275		To support syntax-highlighting in some way, you need
1274	1276
1275	1277		- Add event OnCalcHilite handler, which must fill the TATLineParts array with needed highlighting, or
1276	1278		- Create the unit with adapter class, child of TATAdapterHilite (unit atsynedit_adapters), which must fill the TATLineParts array, again. Partial code of the adapter class:
1277	1279
1278	1280		``` pascal
1279	1281		type
1280	1282		TATAdapterHilite = class(TComponent)
1281	1283		...
1282	1284		public
1283	1285		constructor Create(AOwner: TComponent); override;
1284	1286		//
1285	1287		procedure OnEditorChange(Sender: TObject); virtual;
1286	1288		//called when editor's text changes.
1287	1289
1288	1290		procedure OnEditorChangeEx(Sender: TObject; AChange: TATLineChangeKind; ALine, AItemCount: integer); virtual;
1289	1291		//detailed version of OnEditorChange
1290	1292
1291	1293		procedure OnEditorIdle(Sender: TObject); virtual;
1292	1294		//called after text is changed, and pause passed (OptIdleInterval)
1293	1295		//fast changes (faster than OptIdleInterval): called only after last change
1294	1296
1295	1297		procedure OnEditorCalcHilite(Sender: TObject;
1296	1298		var AParts: TATLineParts;
1297	1299		ALineIndex, ACharIndex, ALineLen: integer;
1298	1300		var AColorAfterEol: TColor;
1299	1301		AMainText: boolean); virtual;
1300	1302		//called to calculate hilite of entire line.
1301	1303		//ACharIndex is starting offset in this line, >0 if editor scrolled horizontally.
1302	1304		//ALineLen is len of line part, starting from ACharIndex.
1303	1305		...
1304	1306		```
1305	1307
1306	1308		You need your custom adapter class, child of TATAdapterHilite, which must implement some of methods. You don't have to implement all of them, if your adapter doesn't need that. Then you must create an object of your adapter class, and assign this object to editor's AdapterForHilite property.
1307	1309
1308	1310		The package ATSynEdit_Ex contains 2 ready adapter classes: for complex EControl .lcf lexers, and for CudaText simplified "lite" lexers. The lexer files are distributed in the CudaText repos on SourceForge.
1309	1311
1310	1312		## Adapter for EControl lexers
1311	1313
1312	1314		See [[ATSynEdit EControl adapter]]
1313	1315
1314	1316		# How to adapt TRegExpr upstream for ATSynEdit
1315	1317
1316	1318		TRegExpr upstream is <https://github.com/andgineer/TRegExpr> . How to convert it to atsynedit_regexpr unit.
1317	1319
1318	1320		- rename unit
1319	1321		- change "uses regexpr_unicodedata" to "uses ATSynEdit_UnicodeData"
1320	1322		- comment line {\$I regexpr_compilers.inc}
1321	1323		- set define on: UniCode
1322	1324		- set define on: FastUnicodeData
1323	1325		- set defines off: UseSpaceChars, UseWordChars
1324	1326		- fix vars:
1325	1327
1326	1328		``` pascal
1327	1329		RegExprModifierI: boolean = False; // default value for ModifierI
1328	1330		RegExprModifierR: boolean = True; // default value for ModifierR
1329	1331		RegExprModifierS: boolean = False; // default value for ModifierS
1330	1332		RegExprModifierG: boolean = True; // default value for ModifierG
1331	1333		RegExprModifierM: boolean = True; // default value for ModifierM
1332	1334		RegExprModifierX: boolean = False; // default value for ModifierX
1333	1335
1334	1336		RegExprLineSeparators: RegExprString = #$a#$b#$c
1335	1337		{$IFDEF UniCode}
1336	1338		+ #$2028#$2029#$85
1337	1339		{$ENDIF};
1338	1340		RegExprLinePairedSeparator: RegExprString = ''; //#$d#$a;
1339	1341
1340	1342		FUseOsLineEndOnReplace := False;
1341	1343		FReplaceLineEnd := #10; //not sLineBreak, it is CR LF on Windows
1342	1344		```
1343	1345
1344	1346		---
1345	1347		From the Free Pascal wiki, page "ATSynEdit", as it stood on 2024-04-04 after a change by Alextp, 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).
1346	1348		Category: ATSynEdit
1347	1349		Category: Components

Back to history