Class: TPaginatedPageFolio

Declaration: HighLevelPrint.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MPageFolio

Inherited By:

TBookPageFolio

Purpose:

This is a concrete example of an MPageFolio. A paginated page folio is best visualized as representing an arbitrarily large canvas area, such as a painting, which can be divided into uniform rectangular blocks representing pages. The blocks can be arranged to completely cover the canvas, to allow borders around the edges, or even to have gaps between the blocks. Blocks at the edge of the canvas can be partial or whole and the canvas (also called the extent rectangle) can be stretched to cover all blocks completely. The canvas is represented by an MGraphic and the blocks by a TPageDescription.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a fully functional class and shouldn't need to be derived except to change specific functional behavior.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPaginatedPageFolio::TPaginatedPageFolio

TPaginatedPageFolio (const TPaginatedPageFolio &)
TPaginatedPageFolio (const TPageDescription & pageDescription, const MGraphic * aliasGraphic, bool wholePages =false, const TGPoint & topLeftOffset =TGPoint :: kOrigin, const TGPoint & bottomRightOffset =TGPoint :: kOrigin, const TGPoint & gap =TGPoint :: kOrigin)
TPaginatedPageFolio ()

Interface Category:

API.

Purpose:

Copy constructor.
General constructor specified by a page description, a graphic, whether to include whole or partial pages, and offsets and gaps.
Default constructor.

Calling Context:

Called to copy an object.
Called to construct a page folio as per specified parameters.
Only for internal use by Resurrect. Developers should treat as protected.

Parameters:

const TPaginatedPageFolio & -The folio object to copy.
const TPageDescription & pageDescription -The page description whose active area is used as the size of the block for paginating the canvas into pages.
const MGraphic * aliasGraphic -Represents the canvas area that will be divided into pages. The area used for pagination is obtained by calling GetGeometricBounds on this MGraphic. This parameter should never be NIL.
bool wholePages =false -Specifies whether or not to stretch the canvas to cover the paginated pages in whole, or to let some pages at the edge of the canvas be only partially covered by the canvas. It defaults to false.
const TGPoint & topLeftOffset =TGPoint :: kOrigin -Specifies the offset between the top-left edge of the canvas and the pagination blocks. This parameter defaults to no offset at all.
const TGPoint & bottomRightOffset =TGPoint :: kOrigin -Specifies the offset between the bottom-right edge of the canvas and the pagination blocks. This parameter defaults to no offset at all.
const TGPoint & gap =TGPoint :: kOrigin -Specifies the gap between pages of the pagination blocks. It defaults to no gaps.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws TStandardPrintPreprocessingException::kTargetMissing if MGraphic is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::~TPaginatedPageFolio

virtual ~ TPaginatedPageFolio ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::CreatePageIterator

virtual TPrintPageIterator * CreatePageIterator (TPageRange * aliasRange =NIL) const

Interface Category:

API.

Purpose:

Creates a page iterator that can parse all the pages of a TPaginatedPageFolio. Any number of page iterators can be created and operated at the same time on the same page folio. When an iterator is created, the page range parameter determines those pages that will be included in the iteration. If no page range is specified, all pages are included. The page iterator pointer returned is a polymorphic TPageIterator but can be cast to a TPaginatedPageIterator pointer. If a page range is specified when a TPageIterator is created, the number of pages returned by the folio and the iterator might be different.

Calling Context:

Called directly to obtain a page iterator for a paginated page folio. This is the only proper way to create an iterator for a folio.

Parameters:

TPageRange * aliasRange =NIL -When a page iterator is created, its page range can be specified by providing an appropriate class pointer as the parameter to the create function. If none is provided, the page iterator defaults to include all pages in the page range.

Return Value:

Returns a TPaginatedPageIterator that can parse the pages in the page folio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any number of page iterators can be created for a page folio and all can be operated at the same time (although not concurrently in different contexts without safe multitasking steps being taken). If at any time the MPageFolio is destroyed without also destroying all of its iterators, the attempt to use any of its iterators could result in catastrophic exceptions. This consideration applies to all MPageFolio derived classes and their page iterators. There is no easy way to safeguard a page iterator when its target page folio is destroyed.

Member Function: TPaginatedPageFolio::GetPageCount

virtual unsigned long GetPageCount () const

Interface Category:

API.

Purpose:

Calculates the total number of pages in the folio. This does not mean that pages actually have content.

Calling Context:

Called directly to obtain the number of pages in a folio.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of pages in the page folio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetGraphic

virtual const MGraphic * GetGraphic () const

Interface Category:

API.

Purpose:

Returns the entire MGraphic that was paginated by the page folio.

Calling Context:

Called directly to obtain the graphic currently being used by the folio to represent its contents.

Parameters:

Takes no parameters.

Return Value:

Returns the MGraphic object used to create the folio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetPageDescription

virtual void SetPageDescription (const TPageDescription &)

Interface Category:

API.

Purpose:

The page size for the pagination can be changed by setting the page description. The active page area of the page description is actually used for the pagination block size.

Calling Context:

Called directly to set a new page description in a folio, which also affects the pagination.

Parameters:

const TPageDescription & -A page description that is used to set the block size for the pagination. The active area of the page description is used as the relevant area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetPageDescription

virtual TPageDescription * GetPageDescription () const

Interface Category:

API.

Purpose:

Returns a pointer to the page description that is used internally to set the page size for the pagination. The page description is still owned by the page folio.

Calling Context:

Called directly to obtain the page description used in the pagination.

Parameters:

Takes no parameters.

Return Value:

Returns the page description used for the pagination block size.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::operator=

TPaginatedPageFolio & operator =(const TPaginatedPageFolio &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPaginatedPageFolio & -The object to assign from.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

May be called directly. Is also called by the collection framework when this object is placed in a collection.

Parameters:

Takes no parameters.

Return Value:

A hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetWhollyContainedPages

virtual void SetWhollyContainedPages (bool)

Interface Category:

API.

Purpose:

The canvas size or extent rectangle used in the pagination process cannot subdivide into a whole number of page-sized blocks, meaning that some pages might be fractional sized if pages at the edges of the canvas cannot be made to fit completely on the canvas. This parameter, if true, causes the extent rectangle, that is the canvas, to be stretched so that whole pages fit completely on the canvas. If false, they are allowed to fall off the edge without changing the canvas. These are the two styles of doing pagination.

Calling Context:

Called directly to make sure pages are fully enclosed in the pagination of the folio or not.

Parameters:

bool - If true, sets the paginator to whole pages, false sets to partial pages.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::IsWhollyContainedPages

virtual bool IsWhollyContainedPages () const

Interface Category:

API.

Purpose:

Returns the current state of the whole pages parameter. (See the discussion under SetWhollyContainedPages(bool).)

Calling Context:

Called directly to find out if pages are fully enclosed in the pagination or not.

Parameters:

Takes no parameters.

Return Value:

Returns true if the page-sized blocks of the pagination are whole, that is, are completely covered by the canvas or extent rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetArrayModelToBeFixed

virtual void SetArrayModelToBeFixed (bool)

Interface Category:

API.

Purpose:

Controls the number of pages in the x and y direction of the pagination (the page frequency) when the extent rectangle, gaps, or offsets are explicitly changed. If set to true, the number of pages in the grid is not allowed to change during these adjustments; if set to false, the number of pages in the grid is allowed to change.

Calling Context:

Called directly to make the page grid constant or variable.

Parameters:

bool - If true, sets the array to be fixed dimensions, false sets it to flexible.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetExtentBySize

virtual void SetExtentBySize (const TGPoint &)

Interface Category:

API.

Purpose:

Sets the size of the extent rectangle independently of the page size. Page size or page frequency is adjusted based on fixed array and whole pages parameters.

Calling Context:

Called directly to set the canvas size.

Parameters:

const TGPoint & -Explicitly sets the canvas or extent rectangle to be the specified size. The WhollyContainedPages parameter is necessarily ignored for this call.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetExtentByPage

virtual void SetExtentByPage (const TULongPair & pagecountxy)

Interface Category:

API.

Purpose:

Sets the size of the extent rectangle from the number of pages specified in the x and y directions and then adjusted based on the fixed array and whole pages parameters.

Calling Context:

Called directly to set the number of pages in the pagination. The extent size or canvas is necessarily affected.

Parameters:

const TULongPair & pagecountxy -Sets the size of the extent rectangle to be determined by the page count in the x and y dimensions, that is, the page frequency. The FixedArraySize parameter is necessarily ignored for this call.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetPageFrequency

virtual void SetPageFrequency (const TULongPair & pagecountxy)

Interface Category:

API.

Purpose:

Sets the page frequency (the number of pages in the x and y direction) independently of the page size. Page and extent rectangle are adjusted based on the current fixed array and whole pages parameters.

Calling Context:

Called directly to set the number of pages in the x and y direction.

Parameters:

const TULongPair & pagecountxy -Doesn't change the extent size, but the page frequency is adjusted accordingly. The FixedArraySize state and the page description are ignored for this call.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetPageSize

virtual void SetPageSize (const TGPoint & pageSize)

Interface Category:

API.

Purpose:

Sets the page size independently of the page frequency. Page frequency and extent rectangle are adjusted based on the current fixed array and whole pages parameters.

Calling Context:

Called directly to set the page size.

Parameters:

const TGPoint & pageSize -This sets the page size for the pagination.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetOffsets

virtual void SetOffsets (const TGPoint & topLeft, const TGPoint & bottomRight)

Interface Category:

API.

Purpose:

Adjusts the canvas or extent rectangle with the specified margins between the edge of the canvas and the page matrix.

Calling Context:

Called directly to set the corner offsets between the canvas and the enclosed pages of a pagination.

Parameters:

const TGPoint & topLeft -This specifies the border between the top-left corner of the canvas and the beginning of the pagination blocks.
const TGPoint & bottomRight -This specifies the border between the bottom-right corner of the canvas and the pagination blocks.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SetGap

virtual void SetGap (const TGPoint & gap)

Interface Category:

API.

Purpose:

Sets the amount of spacing between pages in the pagination.

Calling Context:

Called directly to set the gap between pages.

Parameters:

const TGPoint & gap -This sets the horizontal and vertical gap distance between page blocks.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetPageFrequency

virtual TULongPair GetPageFrequency () const

Interface Category:

API.

Purpose:

Returns the number of pages in the x and y direction for the pagination.

Calling Context:

Called directly to obtain the number of pages in x and y.

Parameters:

Takes no parameters.

Return Value:

Returns a TULongPair representing the number of pages in the x and y dimensions.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetTopLeftOffset

virtual TGPoint GetTopLeftOffset () const

Interface Category:

API.

Purpose:

Returns the top and left margins of the pagination between the edge of the canvas and the pages.

Calling Context:

Called directly to get top-left offset.

Parameters:

Takes no parameters.

Return Value:

Returns a point vector representing the offset, or margin, from the extent rectangle edge to the pagination blocks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetBottomRightOffset

virtual TGPoint GetBottomRightOffset () const

Interface Category:

API.

Purpose:

Returns the bottom and right margins of the pagination between the edge of the canvas and the pages.

Calling Context:

Called directly to get bottom-right offset.

Parameters:

Takes no parameters.

Return Value:

Returns a point vector representing the offset, or border margin, from the extent rectangle edge to the pagination blocks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetGap

virtual TGPoint GetGap () const

Interface Category:

API.

Purpose:

Returns the amount of spacing between pages in the pagination.

Calling Context:

Called directly to get the gap between pages.

Parameters:

Takes no parameters.

Return Value:

Returns a point containing the width of the gaps between pages.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::AddRow

virtual void AddRow ()

Interface Category:

API.

Purpose:

Adds a new row of pages to the pagination matrix. The extent and page frequency is adjusted accordingly.

Calling Context:

Called directly to add pages to a pagination at the same time that an MGraphic is expanded to add a new page.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SubtractRow

virtual void SubtractRow ()

Interface Category:

API.

Purpose:

Removes a row of pages from the pagination matrix. The extent and page frequency are adjusted according to the whole pages and fixed array settings. You cannot subtract the last row; there will always be at least one.

Calling Context:

Called directly to remove a row of pages from a pagination.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::AddColumn

virtual void AddColumn ()

Interface Category:

API.

Purpose:

Adds a column of pages to the pagination matrix. The extent and page frequency are adjusted according to the whole pages and fixed array settings.

Calling Context:

Called directly to add columns of pages to a pagination.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::SubtractColumn

virtual void SubtractColumn ()

Interface Category:

API.

Purpose:

Removes a column of pages from the pagination matrix. The extent and page frequency are adjusted according to the whole pages and fixed array settings. You cannot subtract the last column.

Calling Context:

Called directly to remove columns of pages from a pagination.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetGridSize

virtual TULongPair GetGridSize () const

Interface Category:

API.

Purpose:

Gets the size of the grid used in the pagination. This is the same as the PageFrequency function. The grid is the number of pages in the x and y directions.

Calling Context:

Called directly to get the size of the grid used in the pagination.

Parameters:

Takes no parameters.

Return Value:

Returns the number of pages in the x and y dimensions.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetPageSize

virtual TGPoint GetPageSize () const

Interface Category:

API.

Purpose:

Returns the size of the page used in making the pagination.

Calling Context:

Called directly to obtain the size of the pagination page.

Parameters:

Takes no parameters.

Return Value:

Returns the size of the pagination blocks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetExtentSize

virtual TGPoint GetExtentSize () const

Interface Category:

API.

Purpose:

Gets the size of the canvas or extent rectangle used in the pagination.

Calling Context:

Called directly to obtain the canvas or extent rectangle.

Parameters:

Takes no parameters.

Return Value:

Returns the size of the entire canvas.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetPageFromCoordinate

virtual bool GetPageFromCoordinate (TGPoint & position, const TULongPair & input) const

Interface Category:

API.

Purpose:

Given an arbitrary input coordinate in the pagination grid matrix, this function returns true if it corresponds to a valid page in the pagination and then returns the position of the top-left corner of that page. If the input coordinate is not valid, the function returns false.

Calling Context:

Called directly to find the page corresponding to a given coordinate.

Parameters:

TGPoint & position -The argument in which the calculated page position is returned.
const TULongPair & input -The input grid coordinate for the page of interest.

Return Value:

Returns true if the supplied coordinate is an actual page in the pagination.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatedPageFolio::GetPageFromPoint

virtual bool GetPageFromPoint (TGPoint & position, TULongPair & coordinate, const TGPoint & input) const

Interface Category:

API.

Purpose:

Given an arbitrary input point anywhere, this function calculates the closest page to that point and returns the top-left corner of that page and the coordinate of that page. If the point falls inside the boundaries of the page, the function also returns true. If the point lies outside the boundaries of the page, the function returns false, but the calculations for the page are still valid.

Calling Context:

Called directly to find a page closest to an arbitrary point. This acts like a hit function.

Parameters:

TGPoint & position -The argument in which the calculated top-left corner position of the expected page is returned.
TULongPair & coordinate -The argument in which the grid coordinate of the desired page is returned.
const TGPoint & input -This is an arbitrary input point; the page that is physically closest to this point is calculated and returned in the other parameters, the corner position and the grid coordinate.

Return Value:

Returns true if the point lies inside a page boundary.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.