Class CTextPaginator

CTextPaginator

Support

Supported from 5.0

Description

Paginates a document.

Sets the page dimensions, the printer device and the source document to paginate. Uses a page list, which is an array of characters-per-page values.

There are two ways of paginating a document; either in the background using an active object or by incrementally adding text to the document and repeatedly notifying the CTextPaginator object to paginate the added text. If an active object is used, the client may be notified on completion of pages, on trapped leaves and on completion of the pagination by an optional pagination observer.

Derivation

CActive The core class of the active object abstraction CBase Base class for all classes to be instantiated on the heap CTextPaginator Paginates a document

Defined in CTextPaginator:
AppendTextL(), NewL(), PaginateCompleteDocumentL(), PaginationCompletedL(), SetDocumentL(), SetObserver(), SetPageMarginsInTwips(), SetPageSpecInTwips(), SetPrinterDevice(), SetTextMarginWidthsInTwips(), ~CTextPaginator()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
operator new()

static CTextPaginator* NewL(CPrinterDevice* aPrinterDevice,CArrayFix<TInt>* aCharsPerPage,TInt aPriority);

Description

Allocates and constructs a CTextPaginator object with a page list, the printer device for which the document is to be paginated and an active object priority.

Parameters

CPrinterDevice* aPrinterDevice Pointer to the printer device for which the document is to be paginated. This must be provided. CArrayFix<TInt>* aCharsPerPage The page list. This is a client-provided array into which characters-per-page values are written. Ownership of the array remains with the client. TInt aPriority Integer specifying the active object priority. A number of standard priorities are specified in CActive::TPriority.

Return value

CTextPaginator* Pointer to the new paginator object.

~CTextPaginator();

Description

Destructor. Cancels the active object, if any and frees all resources owned by the object.

void SetDocumentL(MLayDoc* aLayDoc);

Description

Sets a pointer to the document which is to be paginated.

Parameters

MLayDoc* aLayDoc The document to paginate.

void SetPrinterDevice(CPrinterDevice* aPrinterDevice);

Description

Sets a pointer to the printer device for which the document is to be paginated.

Note:

This function must be called, and SetDocumentL() must have been called beforehand.

Parameters

CPrinterDevice* aPrinterDevice The printer device.

void SetPageSpecInTwips(const TPageSpec& aPageSpec);

Description

Sets the page width and height in twips, overriding the current values specified in the printer device.

Parameters

const TPageSpec& aPageSpec Contains the new page dimensions.

void SetPageMarginsInTwips(const TMargins& aPageMargins);

Description

Sets the widths of the page margins in twips.

The page margin exists on all four sides of the page. It does not include the line cursor or labels margins. The labels and line cursor margins are set using SetTextMarginWidthsInTwips().

Parameters

const TMargins& aPageMargins The page margin widths.

void SetTextMarginWidthsInTwips(TInt aLabelMarginWidth,TInt aGutterMarginWidth);

Description

Sets the widths in twips of:

• the labels margin — the area within which paragraph labels are displayed,

• the gutter margin (also known as the line cursor margin) — exists between the labels margin and the text area.

Parameters

TInt aLabelMarginWidth The labels margin width. TInt aGutterMarginWidth The gutter margin width.

void SetObserver(MPaginateObserver* aObserver);

Description

Sets a pagination observer (an instance of a class inherited from MPaginateObserver). The use of an observer is optional.

An observer may be used when paginating a complete document in the background using the function PaginateCompleteDocumentL(). The observer notifies completion of pages, cancellation, errors, and on completion of multiple pagination.

Parameters

MPaginateObserver* aObserver Observer object inherited from MPaginateObserver.

void PaginateCompleteDocumentL();

Description

Initiates pagination of a complete document in the background using an active object. To start pagination, use either this function, or else incrementally paginate with AppendTextL() — do not try to use both functions together.

Note:

SetDocumentL() must have been called beforehand, or a panic occurs.

TInt AppendTextL(TInt& aCumulativeDocPos);

Description

Paginates incrementally as a document is being constructed (by appending paragraphs, for example). Call this function every time text is added to the document.

The function PaginationCompletedL() should be called at the end (in order to complete the last entry in the characters-per-page array).

Use either this function, or else paginate in the background with PaginateCompleteDocumentL() — do not try to use both functions together.

Note:

SetDocumentL() must have been called beforehand, or a panic occurs.

Parameters

TInt& aCumulativeDocPos The first time the function is called, this should be given a value of zero. Returns the last document position which has been paginated.

Return value

TInt A count of the current number of pages.

TInt PaginationCompletedL();

Description

This function should be called when incremental pagination has completed (see AppendTextL()), to complete the final entry in the page list. If an observer has been set, calls its NotifyCompletion()function.

Return value

TInt Count of total number of pages.