Class: TPaginator

Declaration: Paginator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

A TPaginator is an object that provides pagination metrics for partitioning arbitrary real estate into equal rectangular pieces. The model of pagination is loosely based on tiling isomorphic rectangles (called page rectangles) over another rectangle, (called the extent rectangle) which has arbitrary dimensions. The extent rectangle can be specified with borders around the page rectangles and the pages can have uniform gaps between them. The pagination can be specified with partial pages at the edges of the extent rectangle or adjusted to accommodate whole pages.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a specific stand-alone class not intended for general deriving.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPaginator::TPaginator

TPaginator ()
TPaginator (const TPaginator &)
TPaginator (const TGPoint & pageSize, const TGPoint & extent, bool wholePages =true, const TGPoint & topLeftOffset =TGPoint :: kOrigin, const TGPoint & bottomRightOffset =TGPoint :: kOrigin, const TGPoint & gap =TGPoint :: kOrigin)
TPaginator (const TULongPair & pageFrequency, const TGPoint & pageSize, const TGPoint & topLeftOffset =TGPoint :: kOrigin, const TGPoint & bottomRightOffset =TGPoint :: kOrigin, const TGPoint & gap =TGPoint :: kOrigin)
TPaginator (const TGPoint & extent, const TULongPair & pageFrequency, const TGPoint & topLeftOffset =TGPoint :: kOrigin, const TGPoint & bottomRightOffset =TGPoint :: kOrigin, const TGPoint & gap =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Sets the pagination based on page size, extent size, whether or not to use whole pages, offsets, and gaps.
Sets the pagination based on the page frequency, page size, offsets, and gaps.
Sets the pagination based on the extent rectangle, page frequency, offsets, and gaps.

Calling Context:

Called by the stream-in operators.
Called to copy an object.
Called to construct a paginator from one set of metrics.
Called to construct a paginator from another set of metrics.
Called to construct a paginator from yet another set of metrics.

Parameters:

Takes no parameters.
const TPaginator & -The object to copy.
const TGPoint & pageSize -Specifies the size of the page to be used in the pagination.
const TGPoint & extent -Specifies the size of the extent rectangle to be used in the pagination. The page frequency is derived based on the value of these metrics.
bool wholePages =true -If wholePages is true (the default), the extent rectangle is adjusted to cover all the pages completely.
const TGPoint & topLeftOffset =TGPoint :: kOrigin -Specifies the top-left border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & bottomRightOffset =TGPoint :: kOrigin -Specifies the bottom-right border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & gap =TGPoint :: kOrigin -Specifies the gap between pages. The default is no gap.
const TULongPair & pageFrequency -Sets the pagination from the number of pages in x and y.
const TGPoint & pageSize -Specifies the page size to use. The page frequency and page size determine the size of the extent rectangle.
const TGPoint & topLeftOffset =TGPoint :: kOrigin -Specifies the top-left border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & bottomRightOffset =TGPoint :: kOrigin -Specifies the bottom-right border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & gap =TGPoint :: kOrigin -Specifies the gap between pages. The default is no gap.
const TGPoint & extent -Sets the pagination from the size of the extent rectangle and the page frequency.
const TULongPair & pageFrequency -Specifies the number of pages in x- and y-dimensions to cover the specified extent. The page size is adjusted to make this happen.
const TGPoint & topLeftOffset =TGPoint :: kOrigin -Specifies the top-left border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & bottomRightOffset =TGPoint :: kOrigin -Specifies the bottom-right border. The extent rectangle is adjusted to accommodate this border specification. The default is no border.
const TGPoint & gap =TGPoint :: kOrigin -Specifies the gap between pages. The default is no gap.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::~TPaginator

virtual ~ TPaginator ()

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: TPaginator::CreatePaginatorIterator

virtual TPaginatorIterator * CreatePaginatorIterator (TPrimitiveRegion * adoptRegion =NIL) const

Interface Category:

API.

Purpose:

Once a pagination structure has been defined, its pages can be parsed using an iterator (TPaginatorIterator) that defines the sequence in which the pages are accessed (TScanOrder) and which pages should be included (TPrimitiveRegion) in the iteration. A paginator can have any number of iterators but no iterator should be used after the paginator has been destroyed. Only TPaginator objects can create paginator iterators. This function creates a paginator iterator for the paginator and gives it the range specified by the argument, which, if NIL, defaults to all pages in the pagination.

Calling Context:

Called directly to create an iterator for a paginator. Any number of iterators can exist at the same time.

Parameters:

TPrimitiveRegion * adoptRegion =NIL -The region is used to specify pages that are in the range. A NIL range defaults to all pages in the paginator.

Return Value:

The created iterator is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetWhollyContainedPages

virtual void SetWhollyContainedPages (bool)

Interface Category:

API.

Purpose:

The extent rectangle used in the pagination process cannot subdivide into a whole number of page-sized pieces, meaning that some pages can be fractional-sized if pages at the edges of the pagination cannot be made to fit completely within the bounds of the extent. The parameter to this function, if true, causes the extent rectangle, to be stretched so that whole pages fit completely within the rectangle. If false, they are allowed to fall off the edge.

Calling Context:

Called directly to set whether whole pages are used for all of the pagination.

Parameters:

bool - The Boolean flag that sets whole pages.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetWhollyContainedPages

virtual bool GetWhollyContainedPages () const

Interface Category:

API.

Purpose:

Returns the current state of whole pages.

Calling Context:

Called directly to get the whole pages setting.

Parameters:

Takes no parameters.

Return Value:

Returns true if whole pages are used in the pagination.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetArrayModelToBeFixed

virtual void SetArrayModelToBeFixed (bool)

Interface Category:

API.

Purpose:

If the array model is fixed, the grid or number of pages in the x- and y-dimensions is not allowed to change unless it is set explicitly. If the model is not fixed or flexible, then the grid is allowed to change.

Calling Context:

Called directly to set whether the pagination grid array is flexible or fixed.

Parameters:

bool - The Boolean flag that sets the array to fixed or flexible.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetExtentBySize

virtual void SetExtentBySize (const TGPoint &)

Interface Category:

API.

Purpose:

Explicitly sets the size of the extent rectangle.

Calling Context:

Called directly to explicitly set the size of the extent rectangle.

Parameters:

const TGPoint & -The explicit size of the extent rectangle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetExtentByPage

virtual void SetExtentByPage (const TULongPair & pagecountxy)

Interface Category:

API.

Purpose:

Explicitly sets the size of the extent rectangle by specifying the number of pages in x and y. The extent rectangle is expanded or reduced to accommodate the new number of pages in each direction.

Calling Context:

Called directly to set the extent rectangle using the number of pages in each dimension as the metric.

Parameters:

const TULongPair & pagecountxy -The number of pages specified to be in each dimension.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetPageFrequency

virtual void SetPageFrequency (const TULongPair & pagecountxy)

Interface Category:

API.

Purpose:

Explicitly sets the number of pages in x and y by changing the page size without changing the extent rectangle.

Calling Context:

Called directly to set the number of pages in the extent rectangle without changing the size of the extent rectangle. Instead, the size of the pages are changed.

Parameters:

const TULongPair & pagecountxy -The number of pages specified to be in each dimension.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetPageSize

virtual void SetPageSize (const TGPoint & pageSize)

Interface Category:

API.

Purpose:

Sets the page size for the pagination. The extent rectangle is modified depending on the state of whole pages and the flexibility of the grid.

Calling Context:

Called directly to set the size of the page in the pagination.

Parameters:

const TGPoint & pageSize -The specified page size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetOffsets

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

Interface Category:

API.

Purpose:

Sets the offsets between the pagination and the outer edge of the extent rectangle.

Calling Context:

Called directly to change the borders or margins of the pagination.

Parameters:

const TGPoint & topLeft -The top-left border desired.
const TGPoint & bottomRight -The bottom-right border desired.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::SetGap

virtual void SetGap (const TGPoint & gap)

Interface Category:

API.

Purpose:

Sets the gaps between the pages of the pagination.

Calling Context:

Called directly to set the gap between pages.

Parameters:

const TGPoint & gap -The desired gap between pages.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetGridSize

virtual TULongPair GetGridSize () const

Interface Category:

API.

Purpose:

Gets the number of pages in the x- and y-dimensions.

Calling Context:

Called directly to get the grid size.

Parameters:

Takes no parameters.

Return Value:

Returns the size of the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetPageFrequency

virtual TULongPair GetPageFrequency () const

Interface Category:

API.

Purpose:

Gets the number of pages in the x- and y-dimensions.

Calling Context:

Called directly to get the number of pages in the pagination.

Parameters:

Takes no parameters.

Return Value:

Returns the number of pages in x and y.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetTopLeftOffset

virtual TGPoint GetTopLeftOffset () const

Interface Category:

API.

Purpose:

Gets the offset in the top-left portion of the pagination.

Calling Context:

Called directly to get the top-left border values.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left border.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetBottomRightOffset

virtual TGPoint GetBottomRightOffset () const

Interface Category:

API.

Purpose:

Gets the offset in the bottom-right corner of the pagination.

Calling Context:

Called directly to get the bottom-right border values.

Parameters:

Takes no parameters.

Return Value:

Returns the bottom-right border.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetGap

virtual TGPoint GetGap () const

Interface Category:

API.

Purpose:

Gets the gap between pages.

Calling Context:

Called directly to get the gap between pages.

Parameters:

Takes no parameters.

Return Value:

Returns the gap spacing between pages.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetPageCount

virtual unsigned long GetPageCount () const

Interface Category:

API.

Purpose:

Returns the total number of pages in the pagination.

Calling Context:

Called directly to get the total number of pages in the pagination.

Parameters:

Takes no parameters.

Return Value:

Returns the total page count.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetPageSize

virtual TGPoint GetPageSize () const

Interface Category:

API.

Purpose:

Returns the page size used in the pagination.

Calling Context:

Called directly to get the page size.

Parameters:

Takes no parameters.

Return Value:

Returns the page size used in the pagination.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::GetExtentSize

virtual TGPoint GetExtentSize () const

Interface Category:

API.

Purpose:

Returns the size of the extent rectangle used in the pagination.

Calling Context:

Called directly to get the size of the extent rectangle.

Parameters:

Takes no parameters.

Return Value:

Returns the size of the extent rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::AddRow

virtual void AddRow ()

Interface Category:

API.

Purpose:

Adds a row of pages to the pagination grid. The row is added at the bottom of the existing grid. If whole pages is set true, the extent rectangle is expanded to cover all the pages in the new row. If whole pages is set false, the extent rectangle is not changed and the border is changed to reflect the added pages.

Calling Context:

Called directly to add a row of pages to the 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: TPaginator::SubtractRow

virtual void SubtractRow ()

Interface Category:

API.

Purpose:

Removes a row from the bottom of the pagination grid.

Calling Context:

Called directly to remove a row of pages from the 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: TPaginator::AddColumn

virtual void AddColumn ()

Interface Category:

API.

Purpose:

Adds a column of pages to the right edge of the pagination grid.

Calling Context:

Called directly to add a column of pages to the 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: TPaginator::SubtractColumn

virtual void SubtractColumn ()

Interface Category:

API.

Purpose:

Removes a column of pages from the edge of the pagination grid.

Calling Context:

Called directly to remove a column of pages from the 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: TPaginator::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 it 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 convert a pagination grid coordinate to a page position.

Parameters:

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

Return Value:

Returns true if the coordinate is a valid page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::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 convert an arbitrary point to the closest page position.

Parameters:

TGPoint & position -The argument in which the position of the closest page is returned.
TULongPair & coordinate -The argument in which the page coordinate for the closest page is returned.
const TGPoint & input -The page closest to this point is desired.

Return Value:

Returns true if the point is inside a valid page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::operator=

TPaginator & operator =(const TPaginator &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPaginator & -The object to be copied.

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: TPaginator::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called directly to generate a hash value. Also called when this object is placed in a collection.

Parameters:

Takes no parameters.

Return Value:

A hash value for this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginator::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 is streamed 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: TPaginator::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 is streamed 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.

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