KMemo user manual

Revision 1, August 12th 2015 by TK

Contents
1

Introduction 1

Compatibility issues

Creating documents

3.1 Adding text and paragraphs

3.2 Formatting text

3.3 Formatting paragraphs

3.4 Paragraph numbering

3.5 Adding images

3.6 Adding embedded containers

3.7 Adding tables

3.8 Adding hyperlinks 6

3.9 Setting document background

3.10 Setting default document styles 7

4

Working with RTF documents

Clipboard operations

Setting selection attributes

Printing and previewing

7
8

1 Introduction
KMemo is native rich edit control written in Object Pascal. It has been written
from scratch. It replaces the standard TMemo/TRichedit controls from Delphi
and works both under Delphi and Lazarus on every platform with the same
features. It unifies the behavior of different rich edit controls available in
different OSes.
This document describes only important features of KMemo. For more
detailed info see the help file or study the demos.
All used code snippets are present in the KMemoDemo example.

2 Compatibility issues
KMemo is not compatible with Delphi TRichEdit control. This is because
KMemo uses its own, very powerful concept of document skeleton, which is
built on TKMemoBlocks containers and TKMemoBlock objects. Once you
decide to abandon TRichEdit and replace it by TKMemo, you do your work
only once and then, if you use your project in different IDE or OS, the code
stays as is. Porting from TRichEdit should not be very difficult, because
KMemo is really easy to use.

3 Creating documents
One of the most important features of KMemo is the very simple way of
creating documents directly with Object Pascal code. You dont need to
create some intermediate documents to show it in KMemo. You just build up
your document by adding text blocks, image blocks, tables etc.
Note: Once you have your document created by code and let the
user to edit it, the block pointers referred by snippets in chapters
below cannot be used anymore. This is because the user may insert
new blocks, delete selections, split text blocks as a result of
formatting actions etc.

3.1 Adding text and paragraphs

Adding a plain text is very simple:
procedure TMainForm.Test1;
begin
KMemo1.Blocks.AddTextBlock('Hello world!');
end;

In the above example, a simple text block is added at the end of the
document. If you want clear everything and add new text use following:
procedure TMainForm.Test2;
begin
KMemo1.Blocks.Clear;
KMemo1.Blocks.AddTextBlock('Hello world!');
end;

Please note each such operation will force the KMemo update which is often a
time consuming operation, especially for large documents. For such cases,
update locking has been introduced. For sequential operations on KMemo

blocks always use this:

procedure TMainForm.Test3;
begin
with KMemo1.Blocks do
begin
LockUpdate;
try
Clear;
AddTextBlock('Hello world!');
finally
UnlockUpdate;
end;
end;
end;

Now create two paragraphs :

procedure TMainForm.Test4;
begin
with KMemo1.Blocks do
begin
LockUpdate;
try
Clear;
AddTextBlock('First paragraph text!');
AddParagraph;
AddTextBlock('Second paragraph text!');
AddParagraph;
finally
UnlockUpdate;
end;
end;
end;

In the above example, each paragraph is terminated by a paragraph block.

3.2 Formatting text

Note: To keep this document small, lets skip the LockUpdate and
UnlockUpdate pairs in following examples.
Formatting text is very simple. Each text block has an associated

TKMemoTextStyle object instance which allows custom text formatting of this

block:
procedure TMainForm.Test5;
var
TB: TKMemoTextBlock;
begin
TB := KMemo1.Blocks.AddTextBlock('Hello world!');
TB.TextStyle.Font.Name := 'Arial';
TB.TextStyle.Font.Color := clRed;
TB.TextStyle.Font.Style := [fsBold];
end;

Above example will show red bold text in KMemo, its font will be Arial. Many
text formatting features are available.

3.3 Formatting paragraphs

Formatting a paragraph is very simple. Each paragraph block has an
associated TKMemoParaStyle object instance which allows custom paragraph
formatting of this block:
procedure TMainForm.Test6;
var
TB: TKMemoTextBlock;
PA: TKMemoParagraph;
begin
TB := KMemo1.Blocks.AddTextBlock('Hello world!');
PA := KMemo1.Blocks.AddParagraph;
PA.ParaStyle.HAlign := halCenter;
PA.ParaStyle.BottomPadding := 20;
end;

Above example will center the paragraph in KMemo and the paragraph will
have an additional space of 20 points at the bottom. Also for paragraphs
many formatting features are available.

3.4 Paragraph numbering

Each paragraph can have an associated ordered or unordered list. Lists are
implemented in similar way as in Microsoft Word. Each paragraph can have
an associated list ID and list level. Here the simplest example to switch on
numbering for a paragraph:

procedure TMainForm.Test7;
var
TB: TKMemoTextBlock;
PA: TKMemoParagraph;
begin
TB := KMemo1.Blocks.AddTextBlock('Hello world!');
PA := KMemo1.Blocks.AddParagraph;
PA.Numbering := pnuArabic;
end;

Above example turns on Arabic numbering for the paragraph. Many list styles
are available, but an empty document has no list styles defined (in the above
example, the numbering assignment automatically creates a new list for the
document if the KMemo was empty).
Creating a more complex numbering shows the Test8 method in the demo.

3.5 Adding images

Adding an image is very simple:
procedure TMainForm.Test9;
begin
KMemo1.Blocks.AddImageBlock('penguins.jpg');
end;

Above example adds the image to KMemo. The image will be positioned in
text flow in original size. To change the position to allow text to float around
the image just use:
procedure TMainForm.Test10;
var
IB: TKMemoImageBlock;
begin
IB := KMemo1.Blocks.AddImageBlock('image.png');
IB.Position := mbpRelative;
IB.LeftOffset := 50;
end;

Above example will set relative position to the image. The image anchor
stays where the image was originally inserted. The LeftOffset property moves
the image 50 points to the right of its anchor. Similar meaning has the
TopOffset property.

Note: Do not use negative offsets. The KMemo word processor

cannot handle them properly.

3.6 Adding embedded containers

An embedded container can be arbitrary positioned, as an image. But it can
hold any contents, such as text and paragraphs and even images, tables and
other containers. Adding an embedded container is very simple:
procedure TMainForm.Test11;
var
CO: TKMemoContainer;
begin
CO := KMemo1.Blocks.AddContainer;
CO.Position := mbpRelative;
CO.LeftOffset := 50;
CO.TopOffset := 20;
CO.FixedWidth := True;
CO.RequiredWidth := 300;
CO.BlockStyle.Brush.Color := clLime;
CO.Blocks.AddTextBlock('Text in a container!');
CO.Blocks.AddImageBlock('penguins.jpg');
end;

Note: Containers should always have fixed width. Otherwise they will
be resized when KMemos ClientWidth changes. For nonzero
LeftOffset it means the container would reach beyond KMemo right
edge, causing the horizontal scrollbar to appear.

3.7 Adding tables

KMemo has advanced table support. Even very complex tables with merged
cells created with Microsoft Word can be loaded, shown and edited. However,
nested tables are not supported. An example of simple table:
procedure TMainForm.Test12;
var
TBL: TKMemoTable;
begin
TBL := KMemo1.Blocks.AddTable;
TBL.ColCount := 2;
TBL.RowCount := 2;
TBL.Cells[0, 0].Blocks.AddTextBlock('Table text 1');
TBL.Cells[0, 1].Blocks.AddTextBlock('Table text 2');

TBL.Cells[1, 0].Blocks.AddTextBlock('Table text 3');

TBL.Cells[1, 1].Blocks.AddTextBlock('Table text 4');
TBL.CellStyle.BorderWidth := 1;
TBL.ApplyDefaultCellStyle;
end;

Above example adds a table to KMemo. It contains two rows and two
columns. Each cell contains one text box. The table border has default
properties and width of 1 point. Specifying the border width to CellStyle
property does not alone update the table, to do this you must call
ApplyDefaultCellStyle.
Creating a more complex table shows the Test13 method in the demo.

3.8 Adding hyperlinks

A hyperlink is just a specific text block having the URL property and adding it
into KMemo document is, as everything in KMemo, very simple:
procedure TMainForm.Test14;
begin
KMemo1.Blocks.AddHyperlink('www.google.com', 'www.google.com');
end;

3.9 Setting document background

KMemo background can be either arbitrary colored or painted with an image:
procedure TMainForm.Test14;
begin
KMemo1.Colors.BkGnd := clYellow;
KMemo1.BackgroundImage.LoadFromFile('../../resource_src/clouds.jpg');
end;

Above example sets document background to yellow first, then to an image.

3.10 Setting default document styles

KMemo has its own TextStyle and ParaStyle properties. They define the
default properties and can be arbitrary changed:
procedure TMainForm.Test15;
begin
KMemo1.TextStyle.Font.Name := 'Arial';
KMemo1.TextStyle.Font.Size := 20;

KMemo1.ParaStyle.HAlign := halCenter;
end;

Above example sets default font to Arial and 20 point size. Default
paragraphs will have centered alignment. Setting default properties will
reformat the entire document but it affects only text blocks and/or
paragraphs. Furthermore, only blocks whose styles were not explicitly
changed in code or edited by user will be reformatted.

4 Working with RTF documents

It is possible to load and save RTF documents with KMemo. Even part of
document can be saved into separate RTF file and a one RTF file can be
appended to the existing KMemo document or inserted anywhere in the
middle of it.
procedure TMainForm.Test16;
begin
KMemo1.LoadFromRTF('kmemo_manual.rtf');
KMemo1.SaveToRTF('kmemo_manual_copy.rtf');
end;

KMemo supports working with streams as well see LoadFromRTFStream

and SaveToRTFStream. And even RTF strings are supported through the RTF
property.

5 Clipboard operations
KMemo supports clipboard operations. These work with both with simple
TEXT format and with the RICH TEXT FORMAT defined by Microsoft. Clipboard
operations can be called programmatically:
procedure TMainForm.Test17;
begin
KMemo1.ExecuteCommand(ecSelectAll);
KMemo1.ExecuteCommand(ecCopy);
end;

Similar operations exists for cutting and pasting from clipboard.

6 Setting selection attributes

KMemo supports assigning custom text or paragraph attributes to active

selection. This is needed for the user editing but might be useful even in the
programmatic approach:
procedure TMainForm.Test18;
var
TextStyle: TKMemoTextStyle;
ParaStyle: TKMemoParaStyle;
begin
KMemo1.ExecuteCommand(ecSelectAll);
ParaStyle := TKMemoParaStyle.Create;
TextStyle := TKMemoTextStyle.Create;
try
TextStyle.Font.Style := [fsBold];
ParaStyle.FirstIndent := 20;
KMemo1.SelectionParaStyle := ParaStyle;
KMemo1.SelectionTextStyle := TextStyle;
finally
ParaStyle.Free;
TextStyle.Free;
end;
end;

Above example sets custom text and paragraph style to the selection.
Attributes can also be read. In such case the attributes are returned, which
correspond to caret position or selection end position in the innermost
container.

7 Printing and previewing

The documents created in KMemo can be previewed and printed in a very
easy manner. KMemo fully supports the built in KControls printing and
previewing engine. To print the KMemo to a default printer with default
settings, just call:
KMemo1.PrintOut;

To preview the document, drop a TKPrintPreviewDialog component to a form

and then use this code:
procedure TMainForm.Test19;
begin
KPrintPreviewDialog1.Control := KMemo1;

KPrintPreviewDialog1.Execute;
end;

To print the document with page and printer setup, drop a TKPrintSetupDialog
component to a form and then use this code:
procedure TMainForm.Test20;
begin
KPrintSetupDialog1.Control := KMemo1;
KPrintSetupDialog1.Execute;
end;