RichMemo: what changed

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

Old	New		Line
1		-	~~<figure>~~
2		-	~~<img src="richmemosample.png" title="RichMemo macOS screenshot (thanks to Dominique Louis)" />~~
3		-	~~<figcaption>RichMemo macOS screenshot (thanks to Dominique Louis)</figcaption>~~
4		-	~~</figure>~~
	1	+	![](/wiki-images/5/54/Richmemosample.png)
5	2
6	3		## Introduction
7	4
8	5		RichMemo is a package that includes a component to replace the Delphi TRichEdit component. It's designed in cross-platform way, so implementation is possible for the following platforms: Win32, MacOSX and Linux. Since, being cross-platform is the primary target, the native RichMemo API can be extended to make it Delphi's RichEdit compatible.
9	6
10	7		Its main characteristics are
11	8
12	9		- Text highlight
13	10		- System based Unicode edit support
14	11
15	12		Planned: (patches are welcomed)
16	13
17	14		- Adding images into text
18	15		- Embedding LCL Controls?
19	16
20	17		The download contains the component, an installation package and a demo application, that illustrates the features of the component along with some instrumentation for evaluating the chart on a given system.
21	18
22	19		Please add your bugreports, feature requests, pull request on [GitHub](https://github.com/skalogryz/richmemo/issues).
23	20
24	21		## Licensing
25	22
26	23		Author: Dmitry 'skalogryz' Boyarintsev
27	24
28	25		License: [modified](http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL) [LGPL](http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL) (the same as the FPC RTL and the Lazarus LCL). You can contact the author if the modified LGPL doesn't work with your project licensing.
29	26
30	27		## Download
31	28
32	29		The easiest way to install the stable version of the component is via the [[Online Package Manager]] included in current Lazarus versions.
33	30
34	31		The latest trunk is available on GitHub: <https://github.com/skalogryz/richmemo/> . The latest sources can be downloaded by [this GitHub link](https://github.com/skalogryz/richmemo/archive/refs/heads/master.zip).
35	32
36	33		## Installation
37	34
38	35		- Download the package set.
39	36		- Open richmemo_design.lpk package, and install it, rebuilding the IDE.
40	37		- TRichMemo is added to the 'Common Controls' component page.
41	38
42		-	~~<figure>~~
43		-	~~<img src="RichMemoPalette.PNG" title="RichMemoPalette.PNG" />~~
44		-	~~<figcaption>RichMemoPalette.PNG</figcaption>~~
45		-	~~</figure>~~
	39	+	![](/wiki-images/8/80/RichMemoPalette.PNG)
46	40
47	41		Originally richmemopackage was a single file, containing IDE specific and run-time needed classes. However, that meant that IDEIntf package would be a requirement for any project using RichMemo. In order to mitigate that the package was split into to separate packages:
48	42
49	43		- richmemopackage - run-time rich memo component.
50	44		- richmemo_design - IDE extensions to support for RichMemo component.
51	45
52	46		## Font Parameters
53	47
54	48		Font parameters are generally represented by TFontParams record. The type is used to describe rich attributes of the font. Some attributes goes beyond the scope of TFont class, thus an extra type was necessary. However, most of the TFont related data types are reused (i.e. TFontStyles).
55	49
56	50		- Name - name of the font (family).
57	51		- Size - size of the font in points (passing a negative value might produce unexpected results).
58	52		- Color - color of the font.
59	53		- Style - font styles, including Bold, italic, strike-through, underline.
60	54		- HasBkClr - boolean flag, if the text for the should have background color (if true, BkColor field is used, otherwise BkColor is ignored). Transparency is not supported.
61	55		- BkColor - background (aka highlight) color for the text.
62	56		- VScriptPos - vertical adjustment for the text ![](/wiki-images/c/c1/Richmemo_Subsuper.png).
63	57		- vpNormal - no special position.
64	58		- vpSubscript - the text is subscript.
65	59		- vpSuperscript - the text is superscript.
66	60
67	61
68	62		The actual vertical offset of super/sub scripts depends on OS implementation and currently cannot be controlled.
69	63
70	64		You can assign FontParams from TFont structure. For that you'll need to use `GetFontParams(afont: TFont)` function. Note, most of LCL controls have TFont set to "default" values. These are not actual values, but rather an indication that control's default font should be used (similar to crDefault for TColor).
71	65
72	66		GetFontParams function resolves "Default" font name and returns the actual font family name.
73	67
74	68		## Methods
75	69
76	70		### SetTextAttributes
77	71
78	72		```delphi
79	73		procedure SetTextAttributes(TextStart, TextLen: Integer; AFont: TFont);
80	74		```
81	75
82	76		- TextStart : Integer - the first character to be modified
83	77		- TextLen : Integer - number of characters to be modified
84	78		- AFont : TFont - a font that should be applied to the part of the text
85	79
86	80		```delphi
87	81		procedure SetTextAttributes(TextStart, TextLen: Integer; const TextParams: TFontParams);
88	82		```
89	83
90	84		- TextStart : Integer - the first character to be modified
91	85		- TextLen : Integer - number of characters to be modified
92	86		- TextParams : TFontParams - font parameters to be set
93	87
94	88		SetTextureAttributes methods are changing specified text range style. Font parameters is passed in both methods, by AFont parameter (LCL TFont object) or by TFontParams (declared at RichMemo).
95	89
96	90		Setting text attributes does not change current selection. If it's necessary to modify the style of currently selected text, you should SelStart and SelLength as a text range values:
97	91
98	92		```delphi
99	93		RichMemo1.SetTextAttributes(RichMemo1.SelStart, RichMemo1.SelLength, FontDialog1.Font);
100	94		```
101	95
102	96		### GetTextAttributes
103	97
104	98		```delphi
105	99		function GetTextAttributes(TextStart: Integer; var TextParams: TFontParams): Boolean; virtual;
106	100		```
107	101
108	102		- TextStart : Integer - the character position to be queried for font parameters
109	103		- var TextParams : TFontParams - output value, filled with charachter's font attributes. If the method fails and returns false, record's field values is undefined.
110	104
111	105		Fill font params of the character, at TextStart position. Method returns True if textstart is valid character position, and False overwise.
112	106
113	107		### GetStyleRange
114	108
115	109		```delphi
116	110		function GetStyleRange(CharPos: Integer; var RangeStart, RangeLen: Integer): Boolean; virtual;
117	111		```
118	112
119	113		Returns a range of characters that share the same font parameters, i.e. all characters in the range has the same font name, size, color and styles.
120	114
121	115		- CharPos : Integer - a character that belongs to the style range. It's not necessary for this position to be at the begining on the style range. It can be in the middle on in the end of the style range. The first character position is returned by RangeStart parameter.
122	116		- var RangeStart : Integer - the first character in the range
123	117		- var RangeLen : Integer - number of characthers in the range
124	118
125	119		The method returns true if successed. the method returns false, if CharPos is incorrect value - more than available characters or some other error.
126	120
127	121		### CharAtPos
128	122
129	123		```delphi
130	124		function CharAtPos(x,y: Integer): Integer; virtual;
131	125		```
132	126
133	127		Returns zero-based character offset (not UTF8 position). Returns -1 if fails.
134	128
135	129		- x, y - is a point in the client area of the RichMemo control.
136	130
137	131		The method is aware of scrolling state of the control. Thus two calls to CharAtPos(0,0) might return different values if scroll positions is changed between calls. See "examples/hittest" for the sample of usage.
138	132
139	133		If specified x,y would be out of the content of RichMemo the return value is undefined. It is left up to widgetset to either return -1 or closes character available.
140	134
141	135		### SetRangeColor
142	136
143	137		```delphi
144	138		procedure SetRangeColor(TextStart, TextLength: Integer; FontColor: TColor);
145	139		```
146	140
147	141		The method sets color of characters in the specified range to the FontColor. Other font parameters (name, size, styles) are left unchanged.
148	142
149	143		- TextStart: Integer - the first character in the range
150	144		- TextLength: Integer - number of characters in the range
151	145		- FontColor: TColor - color that should be set
152	146
153	147		### SetRangeParams
154	148
155	149		```delphi
156	150		procedure SetRangeParams(TextStart, TextLength: Integer; ModifyMask: TTextModifyMask;
157	151		const fnt: TFontParams; AddFontStyle, RemoveFontStyle: TFontStyles); overload;
158	152		```
159	153
160	154		The method changes font parameters in the specified range.
161	155
162	156		- TextStart - the first character in the range
163	157		- TextLength - number of characters in the range
164	158		- ModifyMask - shows what exact font attributes must be updated The mask accepts any combination of the following values:
165	159		- tmm_Color - font color would be modified (fnt.Color field must be populated)
166	160		- tmm_Name - font name would be modified (fnt.Name field must be populated)
167	161		- tmm_Size - font size would be modified (fnt.Size field must be populated)
168	162		- tmm_Styles - font styles would be modified as specified by AddFontStyle, RemoveFontStyle parameters
169	163		- tmm_BackColor - text highlight (background) color would be modified. (fnt.HasBkClr and fnt.BkColor fields must be populated )
170	164		- Sending an empty mask will cause the method to return without making any changes.
171	165		- fnt - font parameters that are going to be used, depending on the ModifyMask values.
172	166		- AddFontStyle - set of styles that should be applied to the range (used only if tmm_Styles in ModifyMask, otherwise ignored)
173	167		- RemoveFontStyle - set of font style should should be removed from the range (used only if tmm_Styles in ModifyMask, otherwise ignored)
174	168
175	169		```delphi
176	170		procedure SetRangeParams(TextStart, TextLength: Integer;
177	171		ModifyMask: TTextModifyMask; const FontName: String;
178	172		FontSize: Integer; FontColor: TColor;
179	173		AddFontStyle, RemoveFontStyle: TFontStyles);
180	174		```
181	175
182	176		The overloaded version of the method. It's just a wrapper around the parameter using TFontParams structure. The method doesn't support changing of background color, you should use the TFontParams version
183	177
184	178		- FontName - font name that should set (used only if tmm_Name in ModifyMask, otherwise ignored)
185	179		- FontColor - font color that should set (used only if tmm_Color in ModifyMask, otherwise ignored)
186	180
187	181		For example, if the following code is used
188	182
189	183		```delphi
190	184		RichMemo1.SetRangeParams (
191	185		RichMemo1.SelStart, RichMemo1.SelLength,
192	186		[tmm_Styles, tmm_Color], // changing Color and Styles only
193	187		'', // this is font name - it's not used, thus we can leave it empty
194	188		0, // this is font size - it's font size, we can leave it empty
195	189		clGreen, // making all the text in the selected region green color
196	190		[fsBold, fsItalic], // adding Bold and Italic Styles
197	191		[]
198	192		);
199	193		```
200	194
201	195		### GetParaAlignment
202	196
203	197		Gets paragraph alignment
204	198
205	199		```delphi
206	200		function GetParaAlignment(TextStart: Integer; var AAlign: TParaAlignment): Boolean;
207	201		```
208	202
209	203		- TextStart - the position of the character that's belongs to the paragraph
210	204		- AAlign - gets alignment of a paragraph.
211	205
212	206		Note:
213	207
214	208		- Win32 - full-width Justification doesn't work on Windows XP and earlier.
215	209		- OSX - due to Carbon limitation, this is not working in Carbon, but works for Cocoa widgetset.
216	210
217	211		### SetParaAlignment
218	212
219	213		Sets paragraph alignent
220	214
221	215		```delphi
222	216		procedure SetParaAlignment(TextStart, TextLen: Integer; AAlign: TParaAlignment);
223	217		```
224	218
225	219		Note:
226	220
227	221		- Win32 - full-width Justification doesn't work on Windows XP and earlier.
228	222		- OSX - due to Carbon limitation, this is not working in Carbon, but works for Cocoa widgetset. It's also need to loaded that the correct alignment would be loaded from RTF file
229	223
230	224		### GetParaMetric
231	225
232	226		Returns paragraph metrics for a given paragraph ![](/wiki-images/b/be/Richmemo_parametric.PNG)
233	227
234	228		- FirstLine - an offset for the first line (in points), of the paragraph from the beginning of control
235	229		- TailIndent - an offset for each line (in points), except for the first line, of the paragraph from the end of the control
236	230		- HeadIndent - an offset for each line (in points) of the paragraph from the end of the control
237	231		- SpaceBefore - additional space before paragraph (in points)
238	232		- SpaceAfter - additional space after paragraph (in points)
239	233		- LineSpacing - a factor used to calculate line spacing between lines in the paragraph. The factor is applied to Font size (tallest in the line), not the line height. Thus it's matching CSS's line-height property. Note that normal line-spacing is 1.2. I.e. font of 12 pt size, an actual lines spacing set to 1.2, would result in 14pt line height.
240	234		- not supported in WinXP or earlier
241	235		- most of the system would not allow if linespacing is set to less than 1.2. The value would be ignored and they'd default to 1.2
242	236
243	237		Note
244	238
245	239		- RichEdit paragraph settings are specified in pixels, not points, so you'll need to either convert these sizes yourself or use RichMemoHelper methods
246	240		- the notation of "Left"/"Right" offsets is avoided to prevent confusion for RTL.
247	241
248	242		```delphi
249	243		function GetParaMetric(TextStart: Integer; var AMetric: TParaMetric): Boolean;
250	244		```
251	245
252	246		procedure SetParaMetric(TextStart, TextLen: Integer; const AMetric: TParaMetric);
253	247
254		-	~~</source>~~
255		-
256	248		It's recommended to use InitParaMetric function in order to initialize TParaMetric structure. Otherwise zeroing structure out is by it size (i.e. FillChar(m, sizeof(TParaMetric), 0) is sufficient. If TParaMetric values are received from GetParaMetric call, then the structure is considered to be initialized properly.
257	249
258	250		### GetParaRange
259	251
260	252		Returns character range for a paragraph. The paragraph is identified by a character.
261	253
262	254		```delphi
263	255		function GetParaRange(CharOfs: Integer; var ParaRange: TParaRange): Boolean;
264	256		function GetParaRange(CharOfs: Integer; var TextStart, TextLength: Integer): Boolean;
265	257		```
266	258
267	259		CharOfs - is a character that belongs to a paragraph which range is returned. TParaRange - is a structure that returns 3 fields
268	260
269	261		- start - the first character in the paragraph
270	262		- lengthNoBr - the length of the paragraph, excluding the line break character
271	263		- length - the length of the paragrpah, including the line break, if present the last line in the control doesn't contain a line break character, thus length = lengthNoBr value.
272	264
273	265		### SetParaTabs
274	266
275	267		Sets the set of tab stops to paragraphs in the specified length.
276	268
277	269		```delphi
278	270		procedure SetParaTabs(TextStart, TextLen: Integer; const AStopList: TTabStopList);
279	271		```
280	272
281	273		- TextStart
282	274		- TextLen
283	275		- AStopList - the structure that contains an array of tab stops.
284	276		- Count - specifies the number of initialized elements.
285	277		- Tabs - array contains the description of each tab stop, consisting of an Offset and Alignment.
286	278		- Offset - the tab point offset in points (from the left side of the control)
287	279		- Align - the alignment of the tab stop (tabLeft - default one, tabCenter, tabRight, tabDecimal).
288	280
289	281		Notes
290	282
291	283		Renamefest
292	284		Prior to r4140 TTabAlignment enum values were taLeft, taCenter, taRight, taDecimal,but it did collide with Classes.TAlignment declarations. Thus the suffix was changed.
293	285
294	286		win32
295	287		allows no more that 32 tabs
296	288
297	289		gtk2
298	290		only tabLeft align is supported
299	291
300	292		carbon
301	293		not implemented
302	294
303	295		### GetParaTabs
304	296
305	297		Gets the tab stops array. If no specific tabs were specified (widget default tab stops) AStopList count would be set to 0.
306	298
307	299		```delphi
308	300		function GetParaTabs(CharOfs: Integer; var AStopList: TTabStopList): Boolean;
309	301		```
310	302
311	303		### SetParaNumbering
312	304
313	305		Sets paragraphs automatic numbering and styles, such as bullets
314	306
315	307		```delphi
316	308		procedure SetParaNumbering(TextStart, TextLen: Integer; const ANumber: TParaNumbering); virtual;
317	309		```
318	310
319	311		- TextStart - the character of the the first paragraph to apply the style too
320	312		- TextLength - the number of characters that paragraph properties should be modified
321	313		- TParaNumbering - the structure describing the paragraph numbering information
322	314
323	315		:* style - the style of numbering
324	316
325	317
326	318
327	319		Note: for cross-platform compatibility, it's recommended to use either pnNone, pnBullet, pnNumber or pnCustomChar. RTF provides more support for numbering, yet not every platform rich-text widgetset supports them
328	320
329	321		for initializing the structure you can use InitParaNumbering() or InitParaNumber() functions. Also using Default() would work too
330	322
331	323		### SetRangeParaParams
332	324
333	325		Sets paragraph metrics selectively
334	326
335	327		```delphi
336	328		procedure SetRangeParaParams(TextStart, TextLength: Integer; ModifyMask: TParaModifyMask; const ParaMetric: TParaMetric);
337	329		```
338	330
339	331		- TextStart - the character of the the first paragraph to apply the style too
340	332		- TextLength - the number of characters that paragraph properties should be modified
341	333		- ModifyMask - masks the identifies what para metric should be set for each paragraph within TextStart..TextLength block. Other characters will be left unmodified. Members of the set are
342	334		- pmm_FirstLine - changes the first line indentation. FirstLine field of ParaMetric must be initialized
343	335		- pmm_HeadIndent - changes the heading paragraph indentation. HeadIndent field of ParaMetric must be initialized
344	336		- pmm_TailIndent - changes the trail paragraph indentation. TailIndent field of ParaMetric must be initialized
345	337		- pmm_SpaceBefore - changes the space preceding . SpaceBefore field of ParaMetric must be initialized
346	338		- pmm_SpaceAfter - changes the space after (below) the paragraph. SpaceAfter field of ParaMetric must be initialized
347	339		- pmm_LineSpacing - line spacing within paragraph. LineSpace field of ParaMetric must be initialized
348	340		- ParaMetric - the structure containing the values to be set. Only fields specified by ModifyMask should be initialized
349	341
350	342		### LoadRichText
351	343
352	344		```delphi
353	345		function LoadRichText(Source: TStream): Boolean; virtual;
354	346		```
355	347
356	348		- Source: TStream - a stream to read richtext data from
357	349
358	350		The method loads RTF enocded data from the specified stream. Returns true if success, and false otherwise. If source is nil, the method returns false
359	351
360	352		The content of TRichMemo is completely replaced by the content on the source stream. Current text selection is reset.
361	353
362	354		### SaveRichText
363	355
364	356		```delphi
365	357		function SaveRichText(Dest: TStream): Boolean; virtual;
366	358		```
367	359
368	360		- Source: TStream - a stream to read richtext data from
369	361
370	362		The method saves RTF enocded data to the specified stream. Returns true if success, and false otherwise. If source is nil, the method returns false
371	363
372	364		Current state of TRichMemo is unchanged after the method returns
373	365
374	366		### Search
375	367
376	368		```delphi
377	369		function Search(const ANiddle: string; Start, Len: Integer; const SearchOpt: TSearchOptions): Integer;
378	370		```
379	371
380	372		- ANiddle: string - a text to search for
381	373		- Start: Integer - a character position to start search from, if -1 or 0 search from the start
382	374		- Len: Integer - length (in characters, not bytes) of the text to search for the niddle.
383	375		- SearchOpt: TSearchOptions
384	376		- soMatchCase - case sensitive search
385	377		- soBackward - searching from the end of the document to the character identified by "Start" parameter
386	378		- soWholeWord - searching for the whole word
387	379
388	380		The method returns the character position of the found sub-string. The position is suitable for use in SelStart property. However, might not be usable for the direct Copy operation, if Unicode characters are present in the code. Instead UTF8Copy should be used.
389	381
390	382		If the ANiddle was not found in the text, -1 is returned
391	383
392	384		```delphi
393	385		function Search(const ANiddle: string; Start, Len: Integer; const SearchOpt: TSearchOptions;
394	386		var TextStart, TextLength: Integer): Boolean;
395	387		```
396	388
397	389		(The method is introduced with r5115)
398	390
399	391		- ANiddle: string - a text to search for
400	392		- Start: Integer - a character position to start search from, if -1 or 0 search from the start
401	393		- Len: Integer - length (in characters, not bytes) of the text to search for the niddle.
402	394		- SearchOpt: TSearchOptions
403	395		- soMatchCase - case sensitive search
404	396		- soBackward - searching from the end of the document to the character identified by "Start" parameter
405	397		- soWholeWord - searching for the whole word
406	398		- (output) ATextStart - a position of the text found (in characters)
407	399		- (output) ATextLength - length of the text found (in characters (cursor positions!))
408	400
409	401		The method returns the true if searched sub-string is found, false otherwise.
410	402
411	403		The returned ATextStart and ATextLength values are suitable for use in SelStart and SelLength properties.
412	404
413	405		Note: for complex scripts, the found text might be exactly the same as the sub-string searched. The search behavior (on complex scripts) is widgetset specific. Thus searching for the same string on different widgetsets (i.e. win32 or gtk2) might produce different results. If you need the same results and don't get them, please create a bug report.
414	406
415	407		If you need to extract the found text, you should use GetText() method (passing ATextStart and ATextLength values).
416	408
417	409		### GetText, GetUText
418	410
419	411		```delphi
420	412		function GetText(TextStart, TextLength: Integer): String;
421	413		function GetUText(TextStart, TextLength: Integer): UnicodeString;
422	414		```
423	415
424	416		- TextStart: Integer - a character position to start extract from. (0 - is the first character in the text).
425	417		- TextLength: Integer - length (in characters, not bytes) of the text to extract
426	418
427	419		GetText() returns UTF8 sub-string
428	420
429	421		GetUText() returns UTF16 sub-string
430	422
431	423		Current selection would not be affected by the operation. (If you see the selection affected, please report as an issue).
432	424
433	425		You should not consider the efficiency of either method. For example, WinAPI internally operates with UTF16 characters, thus GetUText() might be more efficient for it. While Gtk2 operates UTF8 and calling GetText() might be more efficient for it. Instead of thinking about underlying system, you should be considering the needs of your task.
434	426
435	427		### Redo
436	428
437	429		```delphi
438	430		procedure Redo;
439	431		```
440	432
441	433		The method redos the last change [undone](http://lazarus-ccr.sourceforge.net/docs/lcl/stdctrls/tcustomedit.undo.html) previously.
442	434
443	435		You can always call CanRedo to check, if there're any actions can be redone.
444	436
445	437		## Properties
446	438
447	439		### ZoomFactor
448	440
449	441		```delphi
450	442		property ZoomFactor: double
451	443		```
452	444
453	445		Read/Write property. Controls zooming of the RichMemo content. 1.0 - is no-zoom. Less than \< 1.0 - decrease zoom, more than 1.0 - increasing zooming. If 0 is set - value defaults to 1.0 zoom factor (no zoom).
454	446
455	447		### HideSelection
456	448
457	449		```delphi
458	450		property HideSelection: Boolean default false
459	451		```
460	452
461	453		Read/Write property. If True RichMemo selection is hidden if the control is not focused. If False, the selection is shown all the time.
462	454
463	455		### CanRedo
464	456
465	457		```delphi
466	458		property CanRedo: Boolean
467	459		```
468	460
469	461		If True, there're actions in Undo queue that can be redone. If False, there are no actions in Undo queue that can be redone. Calling to Redo won't have any effect.
470	462
471	463		### Transparent
472	464
473		-	~~<figure>~~
474	465		<img src="richmemo_transparent.png" title="richmemo_transparent.png" width="400" />
475		-	~~<figcaption>richmemo_transparent.png</figcaption>~~
476		-	~~</figure>~~
477	466
478	467		```delphi
479	468		property Transparent: Boolean
480	469		```
481	470
482	471		If True, the background of richmemo is not filled with any color, leaving any underlying controls or windows to be visible. (Suggested to be used with TImage that would provide the background) If False, (default) the background is filled with a solid color
483	472
484	473		Note that the property might not affect "border" style of the the richmemo. You need to set BorderStyle to bsNone in order to disable it. For macOS this also hides the focus ring (when the control is focused)
485	474
486	475		- Supported by Win32, Qt5 and Cocoa
487	476
488	477		### Rtf
489	478
490	479		```delphi
491	480		property Rtf: String
492	481		```
493	482
494		-	~~<figure>~~
495	483		<img src="RtfEditor.PNG" title="RtfEditor.PNG" width="400" />
496		-	~~<figcaption>RtfEditor.PNG</figcaption>~~
497		-	~~</figure>~~
498	484
499	485		Read/Write property that allows to read or write Rich-Text Formatted (RTF) text to the whole control. The intent of the property is to have an ability to set Rich-Text in design time, however the property would work in run-time as well.
500	486
501	487		If then property value is an empty string then Lines property is used as a plain text to initialize control value in load-time.
502	488
503	489		Note: The property is available in TRichMemo class only, it's not available (or even implemented in anyway) in TCustomRichMemo class. It is recommended to use LoadRichText/SaveRichText in order to modify the content of the page, just because they could consume less memory, than copying the whole rich-text into the memory.
504	490
505	491		Cross-platform and Forward Compatibility Note: - currently the property is implemented based on the widgetset providede Rich-text read/write routines. It is very likely that in near future it would be changed to used RichMemo read/write RTF stream code only. The issue is with older systems might not support the latest version of RTF.
506	492
507	493		So right now, you might run into an issue, If you create a project in Gtk2 and save the richmemo is design time containing Unicode characters. Then if you try to load it on the XP machine and would use widgetset native loader, you might see characters missing or rendered improperly. Changing to the usage of RichMemo RTF loader/saver will prevent this issue from happening. Currently you can also avoid it by registering RichMemo loaders (call RegisterRTFLoader, RegisterRTFSaver procedures in project initialization, before any RichMemo is loaded)
508	494
509	495		## Events
510	496
511	497		### OnSelectionChange
512	498
513	499		```delphi
514	500		property OnSelectionChange: TNotifyEvent
515	501		TNotifyEvent = procedure (Sender: TObject) of object;
516	502		```
517	503
518	504		The event is fired whenever, selection is changed within RichMemo, either programmatically or due to the user action.
519	505
520	506		## TRichEditForMemo
521	507
522	508		The class helper that implements RichEdit programmatic interface. The helper is declared at RichEditHelpers unit, so you have to add it to the uses section. Helpers are available in FPC 2.6.0 or later.
523	509
524	510		### Methods
525	511
526	512		#### FindText
527	513
528	514		Searches a given range in the text for a target string
529	515
530	516		### Properties
531	517
532	518		#### SelAttributes
533	519
534	520		Reads/Modifies character attributes of the current selection.
535	521
536	522		### Paragraph
537	523
538	524		Reads/Modifies paragraph attributes of the current selection.
539	525
540	526		### RichMemoUtils
541	527
542	528		The unit is introduced to add some useful OS-specific features for handling working with RichMemo
543	529
544	530		#### InsertImageFromFile
545	531
546	532		```delphi
547	533		function InsertImageFromFile (const ARichMemo: TCustomRichMemo; APos: Integer;
548	534		const FileNameUTF8: string;
549	535		const AImgSize: TSize
550	536		): Boolean = nil;
551	537		```
552	538
553	539		Disclaimer: the function would insert an image file into RichMemo (if implemented by the widgetset) But in a very inefficient way. The image would be read again and the memory would be re-allocated for the image every time. So please, don't use it for smileys in your chat instant messaging. A better API (with data caching) is considered. (That's why this method is not part of TCustomRichMemo class).
554	540
555	541		- APos - position in the text
556	542		- AImgSize - size to be inserted in POINTS, not pixels!. If both cx and cy are 0, the image would not be resized at all. If only one cx, cy is zero results are undefined.
557	543
558	544		There's also an utility function InsertImageFromFileNoResize that calls InsertImageFromFile, passing size as 0.
559	545
560	546		An example of use
561	547
562	548		```delphi
563	549		procedure TForm1.Button1Click(Sender: TObject);
564	550		begin
565	551		// running a dialog to select a picture to insert
566	552		if OpenDialog1.Execute then
567	553		// inserting the picture at the current RichMemo cursor position
568	554		InsertImageFromFileNoResize(RichMemo1, RichMemo1.SelStart, OpenDialog1.FileName);
569	555		end;
570	556		```
571	557
572	558		### InsertStyledText,InsertColorStyledText,InsertFontText
573	559
574	560		The set of functions that simplify appending and replacing of styled text. The specified style of the text is applied on the insertion. The common rule for all functions, if InsPos (insertion position) is negative - the text is appended to the end. In order to insert the text in the beginning of the test InsPos should set to 0.
575	561
576	562		The inserted text is not forced to be on a new line or add a new line. You might want to add LineFeed character to TestUTF8 parameter, if you want the inserted text to cause a new line to be started.
577	563
578	564		```delphi
579	565		procedure InsertStyledText(
580	566		const ARichMemo: TCustomRichMemo;
581	567		const TextUTF8: String;
582	568		AStyle: TFontStyles;
583	569		InsPos : Integer = -1 )
584	570		```
585	571
586	572		InsertStyledText inserts the styled text at the specified position.
587	573
588	574		```delphi
589	575		procedure InsertColorStyledText(
590	576		const ARichMemo: TCustomRichMemo;
591	577		const TextUTF8: String;
592	578		AColor: TColor;
593	579		AStyle: TFontStyles;
594	580		InsPos : Integer = -1 )
595	581		```
596	582
597	583		InsertColorStyledText inserts the text with specified style and color at the specified position. to the end of the RichMemo
598	584
599	585		```delphi
600	586		procedure InsertFontText(
601	587		const ARichMemo: TCustomRichMemo;
602	588		const TextUTF8: String;
603	589		const prms: TFontParams;
604	590		InsPos : Integer = -1 )
605	591		```
606	592
607	593		InsertFontText inserts the text and applies specified FontParams to it.
608	594
609	595		You might want to create a class helper to implement these functions as methods for RichMemo. Beware, if you're using Delphi-compatibility helper - you might right into a conflict.
610	596
611	597		## Frequently Asked Questions
612	598
613	599		### Using RichMemo in Shared Libraries
614	600
615	601		[Issue \#17412](http://bugs.freepascal.org/view.php?id=17412) If you need to use the component in a shared library, you might need to add -fPIC key to the compiler option of "the package" and the "project".
616	602
617	603		## (Delphi) RichEdit like interface
618	604
619	605		[Issue \#14632](http://bugs.freepascal.org/view.php?id=14632) A typical problem is porting an existing code that's using RichEdit from Delphi. RichMemo interface doesn't match RichEdit in many ways. But there're two ways to handle that:
620	606
621	607		- you can either create a sub-class from TCustomRichMemo (or RichMemo) and implement Delphi RichEdit methods;
622	608		- you can use RichMemoHelpers unit (fpc 2.6.0 or later required) and use methods provided by class Helpers that should; Currently SelAttributes and Paragraph properties are implemented.
623	609
624	610		`uses ... RichMemo, RichMemoHelpers;`\
625		-	\
	611	+
626	612		`TForm = class`\
627	613		` RichMemo1 : TRichMemo;`\
628	614		` `\
629	615		` // SelAttributes property is not available in the base class`\
630	616		` // but added by a helper defined at RichMemoHelpers unit`\
631	617		`RichMemo1.SelAttributes.Name := 'Courier New';`
632	618
633	619		## Append mixed color text at the end of the RichMemo
634	620
635	621		If you just need simple coloring then here is an example that will each time add a new line with random color (tested on Windows):
636	622
637	623		```delphi
638	624		procedure TForm1.Button1Click(Sender: TObject);
639	625		var
640	626		i, j: integer;
641	627		str: string;
642	628		begin
643	629		with Richmemo1 do
644	630		begin
645	631		str := 'Newline text';
646	632		i := Length(Lines.Text) - Lines.Count; // cr as #10#13 is counted only once so subtract it once
647	633		j := Length(str) + 1; // +1 to make the cr the same format
648	634		Lines.Add(str);
649	635		SetRangeColor(i, j, Round(random * $FFFFFF));
650	636		end;
651	637		end;
652	638		```
653	639
654		-	~~` `<span style="color:#0140FF">`Newline text`</span>\~~
655		-	~~` `<span style="color:#507FAF">`NewLine text`</span>\~~
656		-	~~` `<span style="color:#C04A90">`NewLine text`</span>~~
	640	+	` ``Newline text`\
	641	+	` ``NewLine text`\
	642	+	` ``NewLine text`
657	643
658	644		Alternative example for simple coloring (tested on Windows):
659	645
660	646		```delphi
661	647		procedure TForm1.Button2Click(Sender: TObject);
662	648		begin
663	649		with RichMemo1 do
664	650		begin
665	651		Lines.Add('Line in red');
666	652		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clRed);
667	653
668	654		Lines.Add('Line in blue');
669	655		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clBlue);
670	656
671	657		Lines.Add('Normal line.');
672	658		Lines.Add('Normal line.');
673	659
674	660		Lines.Add('Line in green ');
675	661		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clGreen);
676	662		end;
677	663		end;
678	664		```
679	665
680		-	~~` `<span style="color:#FF0000">`Line in red`</span>\~~
681		-	~~` `<span style="color:#0000FF">`Line in blue`</span>\~~
682		-	~~` `<span style="color:#000000">`Normal line.`</span>\~~
683		-	~~` `<span style="color:#000000">`Normal line.`</span>\~~
684		-	~~` `<span style="color:#008000">`Line in green`</span>~~
	666	+	` ``Line in red`\
	667	+	` ``Line in blue`\
	668	+	` ``Normal line.`\
	669	+	` ``Normal line.`\
	670	+	` ``Line in green`
685	671
686	672		If you need mixed coloring then this is an example that will add a new line with several different colored words (tested on Windows):
687	673
688	674		```delphi
689	675		procedure TForm1.Button3Click(Sender: TObject);
690	676		procedure AddColorStr(s: string; const col: TColor = clBlack; const NewLine: boolean = true);
691	677		begin
692	678		with RichMemo1 do
693	679		begin
694	680		if NewLine then
695	681		begin
696	682		Lines.Add('');
697	683		Lines.Delete(Lines.Count - 1); // avoid double line spacing
698	684		end;
699	685
700	686		SelStart := Length(Text);
701	687		SelText := s;
702	688		SelLength := Length(s);
703	689		SetRangeColor(SelStart, SelLength, col);
704	690
705	691		// deselect inserted string and position cursor at the end of the text
706	692		SelStart := Length(Text);
707	693		SelText := '';
708	694		end;
709	695		end;
710	696		begin
711	697		AddColorStr('Black, ');
712	698		AddColorStr('Green, ', clGReen, false);
713	699		AddColorStr('Blue, ', clBlue, false);
714	700		AddColorStr('Red', clRed, false);
715	701		end;
716	702		```
717	703
718		-	~~` `<span style="color:#000000">`Black, `</span><span style="color:#008000">`Green, `</span><span style="color:#0000FF">`Blue, `</span><span style="color:#FF0000">`Red`</span>\~~
719		-	~~` `<span style="color:#000000">`Black, `</span><span style="color:#008000">`Green, `</span><span style="color:#0000FF">`Blue, `</span><span style="color:#FF0000">`Red`</span>\~~
720		-	~~` `<span style="color:#000000">`Black, `</span><span style="color:#008000">`Green, `</span><span style="color:#0000FF">`Blue, `</span><span style="color:#FF0000">`Red`</span>~~
	704	+	` ``Black, ``Green, ``Blue, ``Red`\
	705	+	` ``Black, ``Green, ``Blue, ``Red`\
	706	+	` ``Black, ``Green, ``Blue, ``Red`
721	707
722	708		## Markup Language Parsing
723	709
724	710		![mlparse example](/wiki-images/8/8c/Mlparse.png) The native rich-edit controls do not support a markup-language parsing.
725	711
726	712		You'll need to write it yourself as shown in mlparse example
727	713
728	714		## Internals
729	715
730	716		### Platform Support Matrix
731	717
732	718		Values in the matrix are not expected to be static (except for "carbon" column), each system is planned to support all features declared by RichMemo.
733	719
734	720		Note that the table contains more features than published above. That means that the APIs are already available in RichMemo, but since they're unstable (on some platforms) it's considered "experimental" rather than promised.
735	721
736	722		\| Feature \| Win32 \| Gtk2 \| Qt \| Cocoa \| Carbon \|
737	723		\|--------------------------------\|-------\|------------\|-----\|-------\|-------------------\|
738	724		\| Font color and style selection \| Yes \| Yes \| Yes \| Yes \| Yes \|
739	725		\| Font background color \| Yes \| Yes \| Yes \| Yes \| No \|
740	726		\| Subscript,Superscript \| Yes \| Yes \| No \| No \| No \|
741	727		\| GetStyleRange \| Yes \| Yes \| No \| Yes \| Yes \|
742	728		\| Paragraph Alignment \| Yes \| Yes \| Yes \| Yes \| Almost Impossible \|
743	729		\| Paragraph Metrics \| Yes \| Yes \| No \| Yes \| Almost Impossible \|
744	730		\| Paragraph Tabs \| Yes \| Yes \| No \| Yes \| No \|
745	731		\| Zoom \| Yes \| Incomplete \| No \| Yes \| No \|
746	732		\| Printing \| Yes \| No \| No \| No \| No \|
747	733		\| RTF Load/Save \| OS \| RichMemo \| No \| OS \| OS \|
748	734		\| Insertables \| Yes \| Yes \| No \| No \| No \|
749	735		\| Transparent \| Yes \| No \| Yes \| Yes \| No \|
750	736
751	737		### Win32
752	738
753	739		![RichMemo without Theme patch](/wiki-images/e/e9/Rm_win32_notheme.PNG) ![RichMemo with Theme](/wiki-images/1/19/Rm_win32_theme.PNG)
754	740
755	741		- [RichEdit](https://msdn.microsoft.com/en-us/library/windows/desktop/bb787605%28v=vs.85%29.aspx) is used as system widgetset. The latest known .dll is loaded and initialized on start. Please note that RichEdit 1.0 would not support most of the features.
756	742		- The internal wrapper of RichEditManager is provided in order to be compatible with Win 9x. However, it was never tried or tested. It's also expected that TOM object could be wrapped as one of the RichEditManager implementation. However, having the "manager" in place could be removed completely.
757	743		- According to the internet, RichEdit control was not updated by Microsoft to support Theme drawing (since XP and up to Windows 8.1). Thus, RichEdit might always look like an old Win9x 3d-framed control. Based on the patch provided at the [issue](http://bugs.freepascal.org/view.php?id=25111%7Creported) a way to override [WM_NCPAINT](https://msdn.microsoft.com/en-us/library/windows/desktop/dd145212%28v=vs.85%29.aspx) method was introduced in r4153.
758	744
759	745		Win32RichMemo provides a global variable NCPaint. It's a handler of non-client area drawing. By default, it attempts to draw themed border (see Win32RichMemo.ThemedNCPaint for implementation). It provides good results on Windows XP themes, but later themes (where animations are used), the results are not so great and should be updated.
760	746
761	747		In order to let system do NCPaint only (i.e. LCL implementation is causing issues or new windows updated RichEdit to draw borders properly), you can change NCPaint value at runtime, resetting it to nil
762	748
763	749		`uses`\
764	750		` RichMemo, ..{$ifdef WINDOWS}Win32RichMemo{$endif}`\
765		-	\
	751	+
766	752		`initialization`\
767	753		` {$ifdef WINDOWS}`\
768	754		` Win32RichMemo.NCPaint:=nil;`\
769	755		` {$endif}`\
770	756
771	757		You can also provide your own implementation of NCPaint. However, if you implement proper animated theme drawing, please provide patch.
772	758
773	759		The behavior is Windows implementation specific and should not (and will not be) part of RichMemo interface.
774	760
775	761		There's additional information about Windows RICHEDIT that can be found at:
776	762
777	763		- MSDN blog by "Murray Sargent: Math in Office" (https://docs.microsoft.com/en-us/archive/blogs/murrays/).
778	764
779	765		### Gtk2
780	766
781	767		- [GtkTextView](https://developer.gnome.org/gtk2/stable/GtkTextView.html) is used as system widgetset
782	768		- Sub and Superscript are not supported natively, an extra code is implemented in gtk2richmemo in order to implement them.
783	769		- Bulletin and numbered lists are emulated.
784	770
785	771		#### 2.1.0 (trunk/later)
786	772
787	773		Gtk2 internal functions got changes. Specifically function GetWidgetInfo was modified, making RichMemo to fail on compilation.
788	774
789	775		in order to adapt the change RMLCLTRUNK must be defined. It can be easily specified using richmemopackage compiler options.
790	776
791		-	~~<figure>~~
792		-	~~<img src="rmlcltrunkdefine.png" title="rmlcltrunkdefine.png" />~~
793		-	~~<figcaption>rmlcltrunkdefine.png</figcaption>~~
794		-	~~</figure>~~
	777	+	![](/wiki-images/0/05/Rmlcltrunkdefine.png)
795	778
796	779		### Gtk3
797	780
798	781		The APIs between Gtk2 and [Gtk3](https://developer.gnome.org/gtk3/stable/GtkTextView.html) are not really different. The major difference is in painting. For Gtk3 Cairo canvas is heavily used. The only area it affects is "Internals". IF any one wants to contribute Gtk2 implementation - please create separate gtk3richmemoXXX units. No {\$ifdefs} should be created in gtk2 units.
799	782
800	783		### Cocoa
801	784
802	785		- [NSTextView](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSTextView_Class/index.html) is used for Cocoa as system widgetset
803	786		- Not every font-family provides italic font. Thus even if you pass fsItalic as part of Style for a font, it might be ignored.
804	787
805	788		#### Lazarus 1.8 and earlier
806	789
807	790		You need to add a define RMLCL18 for the package compilation.
808	791
809	792		### Qt
810	793
811	794		- [QTextEdit](http://doc.qt.io/qt-4.8/qtextedit.html) widget is used. Current C-mappings for Qt are missing a lot of RichText APIs, thus full implementation is currently impossible.
812	795		- The following classes need to be mapped to C-functions:
813	796		- [QTextBlockFormatH](http://doc.qt.io/qt-4.8/qtextblockformat.html) needed for paragraphs alignments (such as paragraph indents, line spacing and tabs). QTextEdit only exposes paragraph alignment.
814	797		- [QTextCharFormatH](http://doc.qt.io/qt-4.8/qtextcharformat.html) needed for additional character formatting (i.e. vertical alignment, links support). QTextEdit only exposes font styles.
815	798
816	799		## See also
817	800
818	801		- [[RichMemo/Features]] - Comments on some features in progress.
819	802		- [[RichMemo/WorkArounds]] - Some notes about features not yet complete.
820	803		- [[RichMemo/Defines]] - Additional package switches that allow to resolve compiling/runtime issues.
821	804		- [[RichMemo/Samples]] - More examples.
822	805		- [[RichMemo/FAQ]] - Frequently (Forum) Asked Questions
823	806		- [MyNotex](https://sites.google.com/site/mynotex/) - Application which uses modified by Massimo Nardello RichMemo package on Linux-Gtk2.
824	807		- [[TMemo]]
825	808		- [[KControls\|KMemo control]]
826	809
827	810		---
828	811		From the Free Pascal wiki, page "RichMemo", as it stood on 2022-09-29 after a change by Skalogryz, 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).

Back to history