Class: TScanOrder

Declaration: PrintPrimitives.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TRasterScanOrder

Purpose:

TScanOrder is a class that is used to define the order of locations in a grid. Given one item coordinate, a TScanOrder gives you the next item in the sequence (or the previous). It converts between coordinate locations and item numbers so that items can be referred to by a coordinate or sequence number with equal efficiency. Common types of scan orders are normal raster (left-to-right then top-to-bottom), also referred to as RightDown. Others are DownLeft, LeftUp, UpRight, LeftDown, DownRight, RightUp, and UpLeft, to name some of the easier ones.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Clients can derive from this class to provide a scan ordering different from the regular TScanOrder derived class. Common derived classes already existing provide raster scan ordering in all of the possible 8 raster orderings, left-to-right and down, right-to-left and down, left-to-right and up, and so forth. Other possible orders not currently defined are random ordering, spiral ordering (circular), or diagonal. When deriving from TScanOrder, clients must override all pure virtual functions, including Next, Previous, ItemToCoordinate, CoordinateToItem, and CreateOrderedRegion. A region (TPrimitiveRegion) contains an item or representative for each item in the scan order in the order in which they should appear. Given one item in the order, Next and Previous produce the next and previous items respectively. ItemToCoordinate and CoordinateToItem provide a conversion between items in the order and the numerical order in which they appear in the order.

Concurrency:

Multithread safe. The base class is safe but a derived class might not be.

Resource Use:

No special requirements.

Member Function: TScanOrder::~TScanOrder

virtual ~ TScanOrder ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TScanOrder::Next

virtual bool Next (const TULongPair & grid, TULongPair & inOut) const
virtual bool Next (const TULongRect & bounds, TULongPair & inOut) const

Interface Category:

API.

Purpose:

With the input grid bounds being specified by the first argument, sets the input point to the coordinate of the next item in the order that is within the grid.
With the input bounds rectangle, sets the input point to the coordinate of the next item in the grid as defined by the scan order.

Calling Context:

Called to obtain the next logical item in the sequence defined by the order.
Called to obtain the next logical item in the sequence defined by the order.

Parameters:

const TULongPair & grid -The point representing the boundary of the grid.
TULongPair & inOut -The coordinate of the current point that will be set to the coordinate of the next logical item in the grid.
const TULongRect & bounds -The rectangle within a grid that bounds the items of interest.
TULongPair & inOut -The coordinate of the current point that will be set to the coordinate of the next logical item in the grid bounded by the rectangle.

Return Value:

Returns true if the next item is within the given grid or bounds.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should override this function.

Member Function: TScanOrder::Previous

virtual bool Previous (const TULongPair & grid, TULongPair & inOut) const
virtual bool Previous (const TULongRect & bounds, TULongPair & inOut) const

Interface Category:

API.

Purpose:

With the input grid bounds specified by the first argument, sets the input point (second argument) to the coordinate of the previous item in the grid as defined by the scan order.
With the input grid bounds specified by the first argument, sets the input point (second argument) to the coordinate of the previous item in the grid as defined by a TULongRect.

Calling Context:

Called to obtain the previous item in the sequence.
Called to obtain the previous item in the sequence.

Parameters:

const TULongPair & grid -The point representing the boundary of the grid.
TULongPair & inOut -The coordinate of the current point that will be set to the coordinate of the next logical item in the grid.
const TULongRect & bounds -The rectangle within a grid that bounds the items of interest.
TULongPair & inOut -The coordinate of the current point that will be set to the coordinate of the next logical item in the grid bounded by the rectangle.

Return Value:

Returns true if the previous item is within the given grid or bounds.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should override this function.

Member Function: TScanOrder::ItemToCoordinate

virtual TULongPair ItemToCoordinate (const TULongPair & grid, unsigned long item) const

Interface Category:

API.

Purpose:

Converts an item number to a grid coordinate.

Calling Context:

Called to find the item numbers for a given coordinate.

Parameters:

const TULongPair & grid -The boundary of the grid.
unsigned long item -The item number to be converted.

Return Value:

Returns the coordinate within the grid of the given item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should override this function.

Member Function: TScanOrder::CoordinateToItem

virtual unsigned long CoordinateToItem (const TULongPair & grid, const TULongPair & coordinate) const

Interface Category:

API.

Purpose:

Converts a grid coordinate to an item number.

Calling Context:

Called to find the coordinate of a given item.

Parameters:

const TULongPair & grid -The boundary of the grid.
const TULongPair & coordinate -The coordinate to be converted to an item number.

Return Value:

Returns the item number of the given coordinate in the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should override this function.

Member Function: TScanOrder::CreateOrderedRegion

virtual TPrimitiveRegion * CreateOrderedRegion (const TULongPair & grid, unsigned long from, unsigned long to) const

Interface Category:

API.

Purpose:

Creates a region (TPrimitiveRegion) that contains all the items in the grid bounded by from and to.

Calling Context:

Called to create a region representing the grid area.

Parameters:

const TULongPair & grid -The initial grid size of the region.
unsigned long from -The top-left point within the grid that starts the region.
unsigned long to -The bottom-right point within the grid that encloses the region.

Return Value:

Returns the created region whose storage the client is responsible for.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should override this function.

Member Function: TScanOrder::operator=

TScanOrder & operator =(const TScanOrder &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TScanOrder & -The target of the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TScanOrder::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TScanOrder::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called 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:

Multithread safe.

Other Considerations:

None.

Member Function: TScanOrder::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called 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:

Multithread safe.

Other Considerations:

None.

Member Function: TScanOrder::TScanOrder

TScanOrder ()
TScanOrder (const TScanOrder &)

Interface Category:

API.

Purpose:

Default constructor. For derived classes only.
Copy constructor. For derived classes only.

Calling Context:

Called by the stream-in operators and derived classes.
Called to copy an object by derived classes.

Parameters:

Takes no parameters.
const TScanOrder & -The scan order to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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