Class CTextPaginator

class CTextPaginator : public CActive;

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

• CBase - Base class for all classes to be instantiated on the heap

• CActive - The core class of the active object abstraction

• CTextPaginator - Paginates a document

Members

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

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

Inherited from CBase:
Delete(), operator new()

static IMPORT_C 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.

IMPORT_C ~CTextPaginator();

Description

Destructor. Cancels the active object, if any.

IMPORT_C void SetDocumentL(MLayDoc *aLayDoc);

Description

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

Parameters

MLayDoc *aLayDoc The document to paginate.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

IMPORT_C 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.

private: virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls RunError() to handle the leave.

Note that once the active scheduler's Start() function has been called, all user code is run under one of the program's active object's RunL() or RunError() functions.

private: virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

DoCancel() must not wait for event completion; this is handled by Cancel().