RichMemo: what changed

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

Old	New		Line
1	1		![](/wiki-images/5/54/Richmemosample.png)
2	2
3	3		## Introduction
4	4
5	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.
6	6
7	7		Its main characteristics are
8	8
9	9		- Text highlight
10	10		- System based Unicode edit support
11	11
12	12		Planned: (patches are welcomed)
13	13
14	14		- Adding images into text
15	15		- Embedding LCL Controls?
16	16
17	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.
18	18
19	19		Please add your bugreports, feature requests, pull request on [GitHub](https://github.com/skalogryz/richmemo/issues).
20	20
21	21		## Licensing
22	22
23	23		Author: Dmitry 'skalogryz' Boyarintsev
24	24
25	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.
26	26
27	27		## Download
28	28
29	29		The easiest way to install the stable version of the component is via the [[Online Package Manager]] included in current Lazarus versions.
30	30
31	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).
32	32
33	33		## Installation
34	34
35	35		- Download the package set.
36	36		- Open richmemo_design.lpk package, and install it, rebuilding the IDE.
37	37		- TRichMemo is added to the 'Common Controls' component page.
38	38
39	39		![](/wiki-images/8/80/RichMemoPalette.PNG)
40	40
41	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:
42	42
43	43		- richmemopackage - run-time rich memo component.
44	44		- richmemo_design - IDE extensions to support for RichMemo component.
45	45
46	46		## Font Parameters
47	47
48	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).
49	49
50	50		- Name - name of the font (family).
51	51		- Size - size of the font in points (passing a negative value might produce unexpected results).
52	52		- Color - color of the font.
53	53		- Style - font styles, including Bold, italic, strike-through, underline.
54	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.
55	55		- BkColor - background (aka highlight) color for the text.
56	56		- VScriptPos - vertical adjustment for the text ![](/wiki-images/c/c1/Richmemo_Subsuper.png).
57	57		- vpNormal - no special position.
58	58		- vpSubscript - the text is subscript.
59	59		- vpSuperscript - the text is superscript.
60	60
61	61
62	62		The actual vertical offset of super/sub scripts depends on OS implementation and currently cannot be controlled.
63	63
64	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).
65	65
66	66		GetFontParams function resolves "Default" font name and returns the actual font family name.
67	67
68	68		## Methods
69	69
70	70		### SetTextAttributes
71	71
72	72		```delphi
73	73		procedure SetTextAttributes(TextStart, TextLen: Integer; AFont: TFont);
74	74		```
75	75
76	76		- TextStart : Integer - the first character to be modified
77	77		- TextLen : Integer - number of characters to be modified
78	78		- AFont : TFont - a font that should be applied to the part of the text
79	79
80	80		```delphi
81	81		procedure SetTextAttributes(TextStart, TextLen: Integer; const TextParams: TFontParams);
82	82		```
83	83
84	84		- TextStart : Integer - the first character to be modified
85	85		- TextLen : Integer - number of characters to be modified
86	86		- TextParams : TFontParams - font parameters to be set
87	87
88	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).
89	89
90	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:
91	91
92	92		```delphi
93	93		RichMemo1.SetTextAttributes(RichMemo1.SelStart, RichMemo1.SelLength, FontDialog1.Font);
94	94		```
95	95
96	96		### GetTextAttributes
97	97
98	98		```delphi
99	99		function GetTextAttributes(TextStart: Integer; var TextParams: TFontParams): Boolean; virtual;
100	100		```
101	101
102	102		- TextStart : Integer - the character position to be queried for font parameters
103	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.
104	104
105	105		Fill font params of the character, at TextStart position. Method returns True if textstart is valid character position, and False overwise.
106	106
107	107		### GetStyleRange
108	108
109	109		```delphi
110	110		function GetStyleRange(CharPos: Integer; var RangeStart, RangeLen: Integer): Boolean; virtual;
111	111		```
112	112
113	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.
114	114
115	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.
116	116		- var RangeStart : Integer - the first character in the range
117	117		- var RangeLen : Integer - number of characthers in the range
118	118
119	119		The method returns true if successed. the method returns false, if CharPos is incorrect value - more than available characters or some other error.
120	120
121	121		### CharAtPos
122	122
123	123		```delphi
124	124		function CharAtPos(x,y: Integer): Integer; virtual;
125	125		```
126	126
127	127		Returns zero-based character offset (not UTF8 position). Returns -1 if fails.
128	128
129	129		- x, y - is a point in the client area of the RichMemo control.
130	130
131	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.
132	132
133	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.
134	134
135	135		### SetRangeColor
136	136
137	137		```delphi
138	138		procedure SetRangeColor(TextStart, TextLength: Integer; FontColor: TColor);
139	139		```
140	140
141	141		The method sets color of characters in the specified range to the FontColor. Other font parameters (name, size, styles) are left unchanged.
142	142
143	143		- TextStart: Integer - the first character in the range
144	144		- TextLength: Integer - number of characters in the range
145	145		- FontColor: TColor - color that should be set
146	146
147	147		### SetRangeParams
148	148
149	149		```delphi
150	150		procedure SetRangeParams(TextStart, TextLength: Integer; ModifyMask: TTextModifyMask;
151	151		const fnt: TFontParams; AddFontStyle, RemoveFontStyle: TFontStyles); overload;
152	152		```
153	153
154	154		The method changes font parameters in the specified range.
155	155
156	156		- TextStart - the first character in the range
157	157		- TextLength - number of characters in the range
158	158		- ModifyMask - shows what exact font attributes must be updated The mask accepts any combination of the following values:
159	159		- tmm_Color - font color would be modified (fnt.Color field must be populated)
160	160		- tmm_Name - font name would be modified (fnt.Name field must be populated)
161	161		- tmm_Size - font size would be modified (fnt.Size field must be populated)
162	162		- tmm_Styles - font styles would be modified as specified by AddFontStyle, RemoveFontStyle parameters
163	163		- tmm_BackColor - text highlight (background) color would be modified. (fnt.HasBkClr and fnt.BkColor fields must be populated )
164	164		- Sending an empty mask will cause the method to return without making any changes.
165	165		- fnt - font parameters that are going to be used, depending on the ModifyMask values.
166	166		- AddFontStyle - set of styles that should be applied to the range (used only if tmm_Styles in ModifyMask, otherwise ignored)
167	167		- RemoveFontStyle - set of font style should should be removed from the range (used only if tmm_Styles in ModifyMask, otherwise ignored)
168	168
169	169		```delphi
170	170		procedure SetRangeParams(TextStart, TextLength: Integer;
171	171		ModifyMask: TTextModifyMask; const FontName: String;
172	172		FontSize: Integer; FontColor: TColor;
173	173		AddFontStyle, RemoveFontStyle: TFontStyles);
174	174		```
175	175
176	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
177	177
178	178		- FontName - font name that should set (used only if tmm_Name in ModifyMask, otherwise ignored)
179	179		- FontColor - font color that should set (used only if tmm_Color in ModifyMask, otherwise ignored)
180	180
181	181		For example, if the following code is used
182	182
183	183		```delphi
184	184		RichMemo1.SetRangeParams (
185	185		RichMemo1.SelStart, RichMemo1.SelLength,
186	186		[tmm_Styles, tmm_Color], // changing Color and Styles only
187	187		'', // this is font name - it's not used, thus we can leave it empty
188	188		0, // this is font size - it's font size, we can leave it empty
189	189		clGreen, // making all the text in the selected region green color
190	190		[fsBold, fsItalic], // adding Bold and Italic Styles
191	191		[]
192	192		);
193	193		```
194	194
195	195		### GetParaAlignment
196	196
197	197		Gets paragraph alignment
198	198
199	199		```delphi
200	200		function GetParaAlignment(TextStart: Integer; var AAlign: TParaAlignment): Boolean;
201	201		```
202	202
203	203		- TextStart - the position of the character that's belongs to the paragraph
204	204		- AAlign - gets alignment of a paragraph.
205	205
206	206		Note:
207	207
208	208		- Win32 - full-width Justification doesn't work on Windows XP and earlier.
209	209		- OSX - due to Carbon limitation, this is not working in Carbon, but works for Cocoa widgetset.
210	210
211	211		### SetParaAlignment
212	212
213	213		Sets paragraph alignent
214	214
215	215		```delphi
216	216		procedure SetParaAlignment(TextStart, TextLen: Integer; AAlign: TParaAlignment);
217	217		```
218	218
219	219		Note:
220	220
221	221		- Win32 - full-width Justification doesn't work on Windows XP and earlier.
222	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
223	223
224	224		### GetParaMetric
225	225
226	226		Returns paragraph metrics for a given paragraph ![](/wiki-images/b/be/Richmemo_parametric.PNG)
227	227
228	228		- FirstLine - an offset for the first line (in points), of the paragraph from the beginning of control
229	229		- TailIndent - an offset for each line (in points), except for the first line, of the paragraph from the end of the control
230	230		- HeadIndent - an offset for each line (in points) of the paragraph from the end of the control
231	231		- SpaceBefore - additional space before paragraph (in points)
232	232		- SpaceAfter - additional space after paragraph (in points)
233	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.
234	234		- not supported in WinXP or earlier
235	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
236	236
237	237		Note
238	238
239	239		- RichEdit paragraph settings are specified in pixels, not points, so you'll need to either convert these sizes yourself or use RichMemoHelper methods
240	240		- the notation of "Left"/"Right" offsets is avoided to prevent confusion for RTL.
241	241
242	242		```delphi
243	243		function GetParaMetric(TextStart: Integer; var AMetric: TParaMetric): Boolean;
244	244		```
245	245
246	246		procedure SetParaMetric(TextStart, TextLen: Integer; const AMetric: TParaMetric);
247	247
248	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.
249	249
250	250		### GetParaRange
251	251
252	252		Returns character range for a paragraph. The paragraph is identified by a character.
253	253
254	254		```delphi
255	255		function GetParaRange(CharOfs: Integer; var ParaRange: TParaRange): Boolean;
256	256		function GetParaRange(CharOfs: Integer; var TextStart, TextLength: Integer): Boolean;
257	257		```
258	258
259	259		CharOfs - is a character that belongs to a paragraph which range is returned. TParaRange - is a structure that returns 3 fields
260	260
261	261		- start - the first character in the paragraph
262	262		- lengthNoBr - the length of the paragraph, excluding the line break character
263	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.
264	264
265	265		### SetParaTabs
266	266
267	267		Sets the set of tab stops to paragraphs in the specified length.
268	268
269	269		```delphi
270	270		procedure SetParaTabs(TextStart, TextLen: Integer; const AStopList: TTabStopList);
271	271		```
272	272
273	273		- TextStart
274	274		- TextLen
275	275		- AStopList - the structure that contains an array of tab stops.
276	276		- Count - specifies the number of initialized elements.
277	277		- Tabs - array contains the description of each tab stop, consisting of an Offset and Alignment.
278	278		- Offset - the tab point offset in points (from the left side of the control)
279	279		- Align - the alignment of the tab stop (tabLeft - default one, tabCenter, tabRight, tabDecimal).
280	280
281	281		Notes
282	282
283	283		Renamefest
284	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.
285	285
286	286		win32
287	287		allows no more that 32 tabs
288	288
289	289		gtk2
290	290		only tabLeft align is supported
291	291
292	292		carbon
293	293		not implemented
294	294
295	295		### GetParaTabs
296	296
297	297		Gets the tab stops array. If no specific tabs were specified (widget default tab stops) AStopList count would be set to 0.
298	298
299	299		```delphi
300	300		function GetParaTabs(CharOfs: Integer; var AStopList: TTabStopList): Boolean;
301	301		```
302	302
303	303		### SetParaNumbering
304	304
305	305		Sets paragraphs automatic numbering and styles, such as bullets
306	306
307	307		```delphi
308	308		procedure SetParaNumbering(TextStart, TextLen: Integer; const ANumber: TParaNumbering); virtual;
309	309		```
310	310
311	311		- TextStart - the character of the the first paragraph to apply the style too
312	312		- TextLength - the number of characters that paragraph properties should be modified
313	313		- TParaNumbering - the structure describing the paragraph numbering information
314	314
315	315		:* style - the style of numbering
316	316
317	317
318	318
319	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
320	320
321	321		for initializing the structure you can use InitParaNumbering() or InitParaNumber() functions. Also using Default() would work too
322	322
323	323		### SetRangeParaParams
324	324
325	325		Sets paragraph metrics selectively
326	326
327	327		```delphi
328	328		procedure SetRangeParaParams(TextStart, TextLength: Integer; ModifyMask: TParaModifyMask; const ParaMetric: TParaMetric);
329	329		```
330	330
331	331		- TextStart - the character of the the first paragraph to apply the style too
332	332		- TextLength - the number of characters that paragraph properties should be modified
333	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
334	334		- pmm_FirstLine - changes the first line indentation. FirstLine field of ParaMetric must be initialized
335	335		- pmm_HeadIndent - changes the heading paragraph indentation. HeadIndent field of ParaMetric must be initialized
336	336		- pmm_TailIndent - changes the trail paragraph indentation. TailIndent field of ParaMetric must be initialized
337	337		- pmm_SpaceBefore - changes the space preceding . SpaceBefore field of ParaMetric must be initialized
338	338		- pmm_SpaceAfter - changes the space after (below) the paragraph. SpaceAfter field of ParaMetric must be initialized
339	339		- pmm_LineSpacing - line spacing within paragraph. LineSpace field of ParaMetric must be initialized
340	340		- ParaMetric - the structure containing the values to be set. Only fields specified by ModifyMask should be initialized
341	341
342	342		### LoadRichText
343	343
344	344		```delphi
345	345		function LoadRichText(Source: TStream): Boolean; virtual;
346	346		```
347	347
348	348		- Source: TStream - a stream to read richtext data from
349	349
350	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
351	351
352	352		The content of TRichMemo is completely replaced by the content on the source stream. Current text selection is reset.
353	353
354	354		### SaveRichText
355	355
356	356		```delphi
357	357		function SaveRichText(Dest: TStream): Boolean; virtual;
358	358		```
359	359
360	360		- Source: TStream - a stream to read richtext data from
361	361
362	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
363	363
364	364		Current state of TRichMemo is unchanged after the method returns
365	365
366	366		### Search
367	367
368	368		```delphi
369	369		function Search(const ANiddle: string; Start, Len: Integer; const SearchOpt: TSearchOptions): Integer;
370	370		```
371	371
372	372		- ANiddle: string - a text to search for
373	373		- Start: Integer - a character position to start search from, if -1 or 0 search from the start
374	374		- Len: Integer - length (in characters, not bytes) of the text to search for the niddle.
375	375		- SearchOpt: TSearchOptions
376	376		- soMatchCase - case sensitive search
377	377		- soBackward - searching from the end of the document to the character identified by "Start" parameter
378	378		- soWholeWord - searching for the whole word
379	379
380	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.
381	381
382	382		If the ANiddle was not found in the text, -1 is returned
383	383
384	384		```delphi
385	385		function Search(const ANiddle: string; Start, Len: Integer; const SearchOpt: TSearchOptions;
386	386		var TextStart, TextLength: Integer): Boolean;
387	387		```
388	388
389	389		(The method is introduced with r5115)
390	390
391	391		- ANiddle: string - a text to search for
392	392		- Start: Integer - a character position to start search from, if -1 or 0 search from the start
393	393		- Len: Integer - length (in characters, not bytes) of the text to search for the niddle.
394	394		- SearchOpt: TSearchOptions
395	395		- soMatchCase - case sensitive search
396	396		- soBackward - searching from the end of the document to the character identified by "Start" parameter
397	397		- soWholeWord - searching for the whole word
398	398		- (output) ATextStart - a position of the text found (in characters)
399	399		- (output) ATextLength - length of the text found (in characters (cursor positions!))
400	400
401	401		The method returns the true if searched sub-string is found, false otherwise.
402	402
403	403		The returned ATextStart and ATextLength values are suitable for use in SelStart and SelLength properties.
404	404
405	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.
406	406
407	407		If you need to extract the found text, you should use GetText() method (passing ATextStart and ATextLength values).
408	408
409	409		### GetText, GetUText
410	410
411	411		```delphi
412	412		function GetText(TextStart, TextLength: Integer): String;
413	413		function GetUText(TextStart, TextLength: Integer): UnicodeString;
414	414		```
415	415
416	416		- TextStart: Integer - a character position to start extract from. (0 - is the first character in the text).
417	417		- TextLength: Integer - length (in characters, not bytes) of the text to extract
418	418
419	419		GetText() returns UTF8 sub-string
420	420
421	421		GetUText() returns UTF16 sub-string
422	422
423	423		Current selection would not be affected by the operation. (If you see the selection affected, please report as an issue).
424	424
425	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.
426	426
427	427		### Redo
428	428
429	429		```delphi
430	430		procedure Redo;
431	431		```
432	432
433	433		The method redos the last change [undone](http://lazarus-ccr.sourceforge.net/docs/lcl/stdctrls/tcustomedit.undo.html) previously.
434	434
435	435		You can always call CanRedo to check, if there're any actions can be redone.
436	436
437	437		## Properties
438	438
439	439		### ZoomFactor
440	440
441	441		```delphi
442	442		property ZoomFactor: double
443	443		```
444	444
445	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).
446	446
447	447		### HideSelection
448	448
449	449		```delphi
450	450		property HideSelection: Boolean default false
451	451		```
452	452
453	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.
454	454
455	455		### CanRedo
456	456
457	457		```delphi
458	458		property CanRedo: Boolean
459	459		```
460	460
461	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.
462	462
463	463		### Transparent
464	464
465		-	~~<img src="richmemo_transparent.png" title="richmemo_transparent.png" width="400" />~~
	465	+	![](/wiki-images/4/40/Richmemo_transparent.png)
466	466
467	467		```delphi
468	468		property Transparent: Boolean
469	469		```
470	470
471	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
472	472
473	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)
474	474
475	475		- Supported by Win32, Qt5 and Cocoa
476	476
477	477		### Rtf
478	478
479	479		```delphi
480	480		property Rtf: String
481	481		```
482	482
483		-	~~<img src="RtfEditor.PNG" title="RtfEditor.PNG" width="400" />~~
	483	+	![](/wiki-images/b/b8/RtfEditor.PNG)
484	484
485	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.
486	486
487	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.
488	488
489	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.
490	490
491	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.
492	492
493	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)
494	494
495	495		## Events
496	496
497	497		### OnSelectionChange
498	498
499	499		```delphi
500	500		property OnSelectionChange: TNotifyEvent
501	501		TNotifyEvent = procedure (Sender: TObject) of object;
502	502		```
503	503
504	504		The event is fired whenever, selection is changed within RichMemo, either programmatically or due to the user action.
505	505
506	506		## TRichEditForMemo
507	507
508	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.
509	509
510	510		### Methods
511	511
512	512		#### FindText
513	513
514	514		Searches a given range in the text for a target string
515	515
516	516		### Properties
517	517
518	518		#### SelAttributes
519	519
520	520		Reads/Modifies character attributes of the current selection.
521	521
522	522		### Paragraph
523	523
524	524		Reads/Modifies paragraph attributes of the current selection.
525	525
526	526		### RichMemoUtils
527	527
528	528		The unit is introduced to add some useful OS-specific features for handling working with RichMemo
529	529
530	530		#### InsertImageFromFile
531	531
532	532		```delphi
533	533		function InsertImageFromFile (const ARichMemo: TCustomRichMemo; APos: Integer;
534	534		const FileNameUTF8: string;
535	535		const AImgSize: TSize
536	536		): Boolean = nil;
537	537		```
538	538
539	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).
540	540
541	541		- APos - position in the text
542	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.
543	543
544	544		There's also an utility function InsertImageFromFileNoResize that calls InsertImageFromFile, passing size as 0.
545	545
546	546		An example of use
547	547
548	548		```delphi
549	549		procedure TForm1.Button1Click(Sender: TObject);
550	550		begin
551	551		// running a dialog to select a picture to insert
552	552		if OpenDialog1.Execute then
553	553		// inserting the picture at the current RichMemo cursor position
554	554		InsertImageFromFileNoResize(RichMemo1, RichMemo1.SelStart, OpenDialog1.FileName);
555	555		end;
556	556		```
557	557
558	558		### InsertStyledText,InsertColorStyledText,InsertFontText
559	559
560	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.
561	561
562	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.
563	563
564	564		```delphi
565	565		procedure InsertStyledText(
566	566		const ARichMemo: TCustomRichMemo;
567	567		const TextUTF8: String;
568	568		AStyle: TFontStyles;
569	569		InsPos : Integer = -1 )
570	570		```
571	571
572	572		InsertStyledText inserts the styled text at the specified position.
573	573
574	574		```delphi
575	575		procedure InsertColorStyledText(
576	576		const ARichMemo: TCustomRichMemo;
577	577		const TextUTF8: String;
578	578		AColor: TColor;
579	579		AStyle: TFontStyles;
580	580		InsPos : Integer = -1 )
581	581		```
582	582
583	583		InsertColorStyledText inserts the text with specified style and color at the specified position. to the end of the RichMemo
584	584
585	585		```delphi
586	586		procedure InsertFontText(
587	587		const ARichMemo: TCustomRichMemo;
588	588		const TextUTF8: String;
589	589		const prms: TFontParams;
590	590		InsPos : Integer = -1 )
591	591		```
592	592
593	593		InsertFontText inserts the text and applies specified FontParams to it.
594	594
595	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.
596	596
597	597		## Frequently Asked Questions
598	598
599	599		### Using RichMemo in Shared Libraries
600	600
601	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".
602	602
603	603		## (Delphi) RichEdit like interface
604	604
605	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:
606	606
607	607		- you can either create a sub-class from TCustomRichMemo (or RichMemo) and implement Delphi RichEdit methods;
608	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.
609	609
610	610		`uses ... RichMemo, RichMemoHelpers;`\
611	611
612	612		`TForm = class`\
613	613		` RichMemo1 : TRichMemo;`\
614	614		` `\
615	615		` // SelAttributes property is not available in the base class`\
616	616		` // but added by a helper defined at RichMemoHelpers unit`\
617	617		`RichMemo1.SelAttributes.Name := 'Courier New';`
618	618
619	619		## Append mixed color text at the end of the RichMemo
620	620
621	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):
622	622
623	623		```delphi
624	624		procedure TForm1.Button1Click(Sender: TObject);
625	625		var
626	626		i, j: integer;
627	627		str: string;
628	628		begin
629	629		with Richmemo1 do
630	630		begin
631	631		str := 'Newline text';
632	632		i := Length(Lines.Text) - Lines.Count; // cr as #10#13 is counted only once so subtract it once
633	633		j := Length(str) + 1; // +1 to make the cr the same format
634	634		Lines.Add(str);
635	635		SetRangeColor(i, j, Round(random * $FFFFFF));
636	636		end;
637	637		end;
638	638		```
639	639
640	640		` ``Newline text`\
641	641		` ``NewLine text`\
642	642		` ``NewLine text`
643	643
644	644		Alternative example for simple coloring (tested on Windows):
645	645
646	646		```delphi
647	647		procedure TForm1.Button2Click(Sender: TObject);
648	648		begin
649	649		with RichMemo1 do
650	650		begin
651	651		Lines.Add('Line in red');
652	652		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clRed);
653	653
654	654		Lines.Add('Line in blue');
655	655		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clBlue);
656	656
657	657		Lines.Add('Normal line.');
658	658		Lines.Add('Normal line.');
659	659
660	660		Lines.Add('Line in green ');
661	661		SetRangeColor(Length(Lines.Text) - Length(Lines[Lines.Count - 1]) - Lines.Count - 1, Length(Lines[Lines.Count - 1]), clGreen);
662	662		end;
663	663		end;
664	664		```
665	665
666	666		` ``Line in red`\
667	667		` ``Line in blue`\
668	668		` ``Normal line.`\
669	669		` ``Normal line.`\
670	670		` ``Line in green`
671	671
672	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):
673	673
674	674		```delphi
675	675		procedure TForm1.Button3Click(Sender: TObject);
676	676		procedure AddColorStr(s: string; const col: TColor = clBlack; const NewLine: boolean = true);
677	677		begin
678	678		with RichMemo1 do
679	679		begin
680	680		if NewLine then
681	681		begin
682	682		Lines.Add('');
683	683		Lines.Delete(Lines.Count - 1); // avoid double line spacing
684	684		end;
685	685
686	686		SelStart := Length(Text);
687	687		SelText := s;
688	688		SelLength := Length(s);
689	689		SetRangeColor(SelStart, SelLength, col);
690	690
691	691		// deselect inserted string and position cursor at the end of the text
692	692		SelStart := Length(Text);
693	693		SelText := '';
694	694		end;
695	695		end;
696	696		begin
697	697		AddColorStr('Black, ');
698	698		AddColorStr('Green, ', clGReen, false);
699	699		AddColorStr('Blue, ', clBlue, false);
700	700		AddColorStr('Red', clRed, false);
701	701		end;
702	702		```
703	703
704	704		` ``Black, ``Green, ``Blue, ``Red`\
705	705		` ``Black, ``Green, ``Blue, ``Red`\
706	706		` ``Black, ``Green, ``Blue, ``Red`
707	707
708	708		## Markup Language Parsing
709	709
710	710		![mlparse example](/wiki-images/8/8c/Mlparse.png) The native rich-edit controls do not support a markup-language parsing.
711	711
712	712		You'll need to write it yourself as shown in mlparse example
713	713
714	714		## Internals
715	715
716	716		### Platform Support Matrix
717	717
718	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.
719	719
720	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.
721	721
722	722		\| Feature \| Win32 \| Gtk2 \| Qt \| Cocoa \| Carbon \|
723	723		\|--------------------------------\|-------\|------------\|-----\|-------\|-------------------\|
724	724		\| Font color and style selection \| Yes \| Yes \| Yes \| Yes \| Yes \|
725	725		\| Font background color \| Yes \| Yes \| Yes \| Yes \| No \|
726	726		\| Subscript,Superscript \| Yes \| Yes \| No \| No \| No \|
727	727		\| GetStyleRange \| Yes \| Yes \| No \| Yes \| Yes \|
728	728		\| Paragraph Alignment \| Yes \| Yes \| Yes \| Yes \| Almost Impossible \|
729	729		\| Paragraph Metrics \| Yes \| Yes \| No \| Yes \| Almost Impossible \|
730	730		\| Paragraph Tabs \| Yes \| Yes \| No \| Yes \| No \|
731	731		\| Zoom \| Yes \| Incomplete \| No \| Yes \| No \|
732	732		\| Printing \| Yes \| No \| No \| No \| No \|
733	733		\| RTF Load/Save \| OS \| RichMemo \| No \| OS \| OS \|
734	734		\| Insertables \| Yes \| Yes \| No \| No \| No \|
735	735		\| Transparent \| Yes \| No \| Yes \| Yes \| No \|
736	736
737	737		### Win32
738	738
739	739		![RichMemo without Theme patch](/wiki-images/e/e9/Rm_win32_notheme.PNG) ![RichMemo with Theme](/wiki-images/1/19/Rm_win32_theme.PNG)
740	740
741	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.
742	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.
743	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.
744	744
745	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.
746	746
747	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
748	748
749	749		`uses`\
750	750		` RichMemo, ..{$ifdef WINDOWS}Win32RichMemo{$endif}`\
751	751
752	752		`initialization`\
753	753		` {$ifdef WINDOWS}`\
754	754		` Win32RichMemo.NCPaint:=nil;`\
755	755		` {$endif}`\
756	756
757	757		You can also provide your own implementation of NCPaint. However, if you implement proper animated theme drawing, please provide patch.
758	758
759	759		The behavior is Windows implementation specific and should not (and will not be) part of RichMemo interface.
760	760
761	761		There's additional information about Windows RICHEDIT that can be found at:
762	762
763	763		- MSDN blog by "Murray Sargent: Math in Office" (https://docs.microsoft.com/en-us/archive/blogs/murrays/).
764	764
765	765		### Gtk2
766	766
767	767		- [GtkTextView](https://developer.gnome.org/gtk2/stable/GtkTextView.html) is used as system widgetset
768	768		- Sub and Superscript are not supported natively, an extra code is implemented in gtk2richmemo in order to implement them.
769	769		- Bulletin and numbered lists are emulated.
770	770
771	771		#### 2.1.0 (trunk/later)
772	772
773	773		Gtk2 internal functions got changes. Specifically function GetWidgetInfo was modified, making RichMemo to fail on compilation.
774	774
775	775		in order to adapt the change RMLCLTRUNK must be defined. It can be easily specified using richmemopackage compiler options.
776	776
777	777		![](/wiki-images/0/05/Rmlcltrunkdefine.png)
778	778
779	779		### Gtk3
780	780
781	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.
782	782
783	783		### Cocoa
784	784
785	785		- [NSTextView](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSTextView_Class/index.html) is used for Cocoa as system widgetset
786	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.
787	787
788	788		#### Lazarus 1.8 and earlier
789	789
790	790		You need to add a define RMLCL18 for the package compilation.
791	791
792	792		### Qt
793	793
794	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.
795	795		- The following classes need to be mapped to C-functions:
796	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.
797	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.
798	798
799	799		## See also
800	800
801	801		- [[RichMemo/Features]] - Comments on some features in progress.
802	802		- [[RichMemo/WorkArounds]] - Some notes about features not yet complete.
803	803		- [[RichMemo/Defines]] - Additional package switches that allow to resolve compiling/runtime issues.
804	804		- [[RichMemo/Samples]] - More examples.
805	805		- [[RichMemo/FAQ]] - Frequently (Forum) Asked Questions
806	806		- [MyNotex](https://sites.google.com/site/mynotex/) - Application which uses modified by Massimo Nardello RichMemo package on Linux-Gtk2.
807	807		- [[TMemo]]
808	808		- [[KControls\|KMemo control]]
809	809
810	810		---
811	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