Header and Footer

WPTools provides powerful support for headers and footers.

You can create a header or footer which is valid for all pages or header and footers for the first, the odd and the even pages.

In WPTools 5 ist is also possible to start a new section in the text. This section can then have its own set of header and footer and also, optionally, a different page size or different margins.

Example: Create a Footer with the text "PAGE # of ##"

var par : TParagraph;

   txtplain : Cardinal;

begin

par:=WPRichText1.HeaderFooter.Get(wpFooter,wpraOnAllPages).FirstPar;

WPRichText1.WritingAttr.Clear;

WPRichText1.WritingAttr.SetFontName('Courier New');

WPRichText1.WritingAttr.SetFontSize(900);  // 9pt

txtplain := WPRichText1.WritingAttr.CharAttr;

par.ClearText;

par.ASet(WPAT_Alignment, Integer(paralRight));

par.Insert(0,'Page ',txtplain);

par.InsertNewObject(maxint, wpobjTextObject, false, false,txtplain).Name := WPTextFieldNames[wpoPageNumber];

par.Insert(maxint,' of ',txtplain);

par.InsertNewObject(maxint, wpobjTextObject, false, false,txtplain).Name := WPTextFieldNames[wpoNumPages];

end;

Please note that the property 'FirstPar' will always create a paragraph if the text block was empty.

"Manage Header and Footer", a useful dialog

WPTools comes with a useful form in unit WPManHeadFoot to work with header and footer.

This form makes it easy to navigate to a certain header or footer. It can be edited, copied or deleted. The two buttons switch between the page layout mode and the normal layout mode. If the user clicks on a header or footer which is currently not visible, the text cannot be edited in page layout mode, so the dialog will automatically select the normal mode.

To use this form add the unit to the uses clause and create a global variable:

ManHeadFoot : TWPManageHeaderFooter;

Now, to show the form in a non-modal:

if ManHeadFoot=nil then

    ManHeadFoot := TWPManageHeaderFooter.Create(Self);

ManHeadFoot.WPRichText := WPRichText1;

ManHeadFoot.Show;

We recommend to check out the source of this dialog since it also contains good example code.

Properties TWPRichText.WorkOnText and TWPRTFDataBlock.WorkOnText

This property selects the text which is currently edited. All commands will operate on the selected text part. Only ‚Load' and ‚Save' will automatically select the body.

Possible values for 'WorkOnText' are

wpIsBody

wpIsHeader

wpIsFooter

If you need to select the special text for a certain 'range' you the property HeaderFooterTextRange. (type TWPPagePropertyRange).

WPRichText1.HeaderFooterTextRange := wpraOnOddPages;

WPRichText1.WokOnText := wpIsHeader;

Now all the procedures work with the header for odd pages. You can execute mailmerge "MergeText", add number fields "InputTextFieldName('PAGE')" or inserts texts "InputString'Hello World')".

If you have a reference to a certain TWPRTFDataBlock -  for example provided by WPRichText1.HeaderFooter.Get - you can also set the boolean property WorkOnText of this element to TRUE to select it for editing!  

  WPRichText1.HeaderFooter.Get(wpIsHeader,wpraOnFirstPage,'').WorkOnText := TRUE;

  WPRichText1.InputString('WPTools Documentation');

  WPRichText1.WorkOnText := wpIsBody;

Please note that you will only see the selected text exclusively in the 'normal' LayoutMode. Otherwise the cursor simply moves to the header or footer region.

Notes

a) Please note, the above puts the cursor into a certain header/footer text. It does not change which header or footer is currently displayed on the page. If you need to modify the way header and footer are selected for the display in page layout mode use the OnGetSpecialText event.

This event handler selects the ALL PAGES header or footer for all pages, also first, odd and even no matter what other header or footer are there:

procedure TForm1.WPRichText1GetSpecialText(Sender: TObject;

par: TParagraph; PosInPar, PageNr: Integer; Kind: TWPPagePropertyKind;

var IsLastPage, UseThis: Boolean; var SpecialText: TWPRTFDataBlock);

begin

// We use 'Get' to find the header or footer

SpecialText := WPRichtext1.HeaderFooter.Get(Kind, wpraOnAllPages, '');

// Only then the variable is actually used

UseThis := TRUE;

end;

b) It is important to note that if the PrintHeaderFooter sub-property is set to wprNever, the headers and footers will not be displayed on screen either.

Also, you can choose if the headers and footers will be displayed in grayed form by setting the wpDontGrayHeaderFooter sub-property of the ViewOptions property to false.

c) The header and footer can be printed in the top/bottom margin area or in the text area. It is up to you what you like better, both possibilities are used by standard word processors. This behavior is controlled by the sub-property PrintHeaderFooterInPageMargins in property HeaderHeader. In the property Header you can also modify the values for the margins and page and the default values that should be set when the buffer was cleared.

Collection HeaderFooter : TWPRTFDataCollection

The headers and footers (and also the body and optional texts) are stored in the runtime collection property TWPRichText.HeaderFooter.

This collection manages a list of instances of the class TWPRTFDataBlock. Each instance holds one 'special' text. This text can be used as a header or a footer within the selected range.

TWPRTFDataBlock = class(TCollectionItem)

...

published

   property Name: string

   property UsedForSectionID

   property Range: TWPPagePropertyRange

   property Kind: TWPPagePropertyKind

   property RtfText: TWPRTFDataContents

end;

TWPPagePropertyRange =

   (wpraOnAllPages, wpraOnOddPages, wpraOnEvenPages, wpraOnFirstPage,

   // these Modes are not compatible to the RTF Standard !

   // They have priority !!!!

   wpraOnLastPage, wpraNotOnFirstAndLastPages,

   wpraNamed, wpraIgnored);

TWPPagePropertyKind = (wpIsBody, wpIsHeader, wpIsFooter,

     wpIsFootnote,        // The last 4 are for internal use only

     wpIsLoadedBody,

     wpIsDeleted,

     wpIsOwnerSelected);

TWPRTFDataContents = class(TPersistent)

public

   constructor Create(Source: TWPRTFDataBlock);

   procedure LoadFromStream(Stream: TStream); virtual;

   procedure SaveToStream(Stream: TStream); virtual;

   property AsString: string read GetAsString write SetAsString;

   procedure Assign(Source: TPersistent); override;

   property Format: string read FFormat write FFormat;

end;

To change the text you can load the text from a stream using Item.RtfText.LoadFromStream or you can simply set or read the property AsString! This string can also be in HTML or WPTOOLS format!

The RTFDataCollection provides this functions to find certain header or footer entries. You can of course enumerate all the items using the Items[] array.

function Find(Kind: TWPPagePropertyKind; Range: TWPPagePropertyRange;

const Name: string = '*'; UsedForSectionID: Integer = 0): TWPRTFDataBlock;

procedure DeleteTexts(UsedForSectionID: Integer); overload;

procedure DeleteTexts(Kind: TWPPagePropertyKind; UsedForSectionID: Integer); overload;

procedure DeleteRTFData(RTFData: TWPRTFDataBlock);

procedure DeleteText(Kind: TWPPagePropertyKind; Range: TWPPagePropertyRange; UsedForSectionID: Integer = 0);

We suggest to use this code to add a new header:

WPRichText1.HeaderFooter.Get(

   wpIsHeader,

   wpraOnAllPages,

   '').RtfText.AsString

    :=  WPEditor.AsString; // any other TWPRichText which is used to edit the header

-or-

WPRichText1.HeaderFooter.Get(

      wpIsHeader,

      wpraOnAllPages, '').RtfText.LoadFromStream( filestream1 );

C++Builder:

WPRichText1->HeaderFooter->Get(wpIsHeader,wpraOnAllPages,"")->RtfText->AsString;

Event: OnGetSpecialText

This event receives this parameters:

Sender: TObject;

par: TParagraph;

PosInPar: Integer;

PageNr: Integer;

Kind: TWPPagePropertyKind;

var IsLastPage: Boolean;

var UseThis: Boolean;

var SpecialText: TWPRTFDataBlock

You can set UseThis to true to let the RTF Engine use as header or footer whatever item you have choosen in 'SpecialText'. To switch off the header or footer set this parameter to nil:

SpecialText := nil;

if PageNr=1 then

      UseThis := TRUE

else UseThis := FALSE;