What are "external pages" ?
This are pages which are displayed by WPTools Version 9 before, after or within the regular text. In page layout mode the page will be displayed as if it was a text page.
Why do I need it ?
If you want to display the output of your favourite report generator and text in a powerful preview component. For example if you need to create a big report which contains of several parts, text and graphical report data.
This feature will also help a lot if you need to combine the ANSI text (such as logging data) with formatted text. Since the external pages are rendered through an event it is possible to work with thousands of them - there is no need to initialize the graphical data at the beginning.
Why can't I use watermarks for this?
Actually you can - and this would be the second best way to implement it. But with the use of "external pages" no empty pages have to be inserted into the text, no place holders are required. The formatted text stays completely unaltered.
Can I save the document with the additional pages ?
No, this is not possible. The data which has been added as "external pages" will not be saved or loaded. The editor will only load and save (and edit) the regular text.
The installed (Tasks\ExternalPages) demo creates a list with dummy data. This list is displayed at the beginning of the formatted text:
Methods to be used for external pages: (only in TWPRTFEnginePaint = WPRichText.Memo)
Adds a reference 'ExternPageRef'. The returned TWPRTFExternPageRef contains variables to change the page size.
function ExternPageRefAdd(
mode: TWPRTFExternPageRefMode;
PageNrX: Integer;
Order: Integer;
ExternPageRef: TObject;
WatermarkRef: TObject): TWPRTFExternPageRef;
procedure ExternPageRefClear - deletes all references and frees the data
Events to be used with external pages:
OnPaintExternPage (in TWPCustomRtfEdit and TWPRTFEnginePaint)
Sender: TObject;
RTFEngine: TWPRTFEnginePaint;
prCanvas: TCanvas;
xoff, yoff: Integer;
r: TRect;
PaintPageNr: Integer;
ExternPageRef: TObject;
DestXRes, DestYRes: Integer
OnInitPage (only in TWPRTFEnginePaint = WPRichText.Memo)
Sender: TObject; // The 'Parent' Object of the RTF - Engine, usually the TWPRichText
RTFEngine: TWPRTFEnginePaint;
paintpagenr: Integer; // the number of the paint page (this is not the RTF page)
rtfpagenr: Integer; // the RTF page which will be used if ExternPageRef stayes to be nil
var ExternPageRef: TObject; // assign an object here to disable RTF text for this page
var WatermarkRef: TObject; // assign data required to paint a watermark
var PaperColor: TColor;
var pagewidth, pageheight, marginleft, margintop, marginright, marginbottom: Integer) of object;
Example:
procedure TWPExternalP.UpdateBtnClick(Sender: TObject);
var s : string;
c,i : Integer;
x,y,th,h: Integer;
pw, ph : Integer;
PageNr : Integer;
aPage : TMetafile;
aCanvas : TMetafileCanvas;
procedure NewPage;
begin
if aPage = nil then
begin
aPage := TMetafile.Create;
aPage.Width := pw;
aPage.Height := ph;
end;
if aCanvas=nil then
begin
aCanvas := TMetafileCanvas.Create( aPage, 0);
aCanvas.Font.Name := 'Arial';
aCanvas.Font.Size := 11;
h := ph - WPScreenPixelsPerInch;
y := WPScreenPixelsPerInch div 2;
th:= aCanvas.TextHeight('Ag');
x := WPScreenPixelsPerInch div 2;
end;
PageCount.Caption := IntToStr(PageNr+1) + ' Extern Pages';
PageCount.Update;
end;
procedure PostPage;
var PageRef : TWPRTFExternPageRef;
begin
FreeAndNil(aCanvas);
if aPage<>nil then
begin
// We add a page at a certain location. The data object we added
// Is freed automatically unless we set in the
// returned TWPRTFExternPageRef object the property DontFreeExternPage
// to true
PageRef := WPRichText1.Memo.ExternPageRefAdd(
wpAsPageX,
PageNr,
0,
aPage,
nil
);
// This values are optional
PageRef.PageWidth := MulDiv( pw, 1440, WPScreenPixelsPerInch);
PageRef.PageHeight := MulDiv( ph, 1440, WPScreenPixelsPerInch);
inc(PageNr);
aPage := nil;
end;
end;
begin
c := StrToInt(ACount.Text); // The count of lines to be printed
s := ALine.Text; // the format string
aPage := nil;
aCanvas := nil;
PageNr := 0;
WPRichText1.Memo.ExternPageRefClear;
// The page size for the external page in pixels
pw := MulDiv( WPRichText1.Header.PageWidth, WPScreenPixelsPerInch, 1440);
ph := MulDiv( WPRichText1.Header.PageHeight, WPScreenPixelsPerInch, 1440);
// Try it: The external pages will be landscape!
// ph := MulDiv( WPRichText1.Header.PageWidth, WPScreenPixelsPerInch, 1440);
// pw := MulDiv( WPRichText1.Header.PageHeight, WPScreenPixelsPerInch, 1440);
// Now create the lines
for i:=1 to c do
begin
if y>h then PostPage;
NewPage;
aCanvas.TextOut(x,y,Format(s,[i,Random(1000000)]));
inc(y,th);
end;
PostPage;
WPRichText1.DelayedReformat;
end;
Since we use simple metafiles as data for the external pages the painting is very easy. Of course we could also use a string list or a custom object and so avoid the overhead of metafiles. If you know in advance the count of pages but do not want to load the data in the beginning, this is possible, too. The data can be initializes when it is used first in the event OnPaintExternPage.
procedure TWPExternalP.WPRichText1PaintExternPage(Sender: TObject;
RTFEngine: TWPRTFEnginePaint; prCanvas: TCanvas; xoff, yoff: Integer;
r: TRect; PaintPageNr: Integer; ExternPageRef: TObject; DestXRes,
DestYRes: Integer);
begin
prCanvas.StretchDraw( r, ExternPageRef as TGraphic );
end;