![](../../Home/Icons/Home.gif)
![](../icons/UpCNM.gif)
![](../icons/CNMContext.gif)
![](../../Home/Icons/Search.gif)
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.
virtual ~ TScanOrder ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
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:
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:
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.
- 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.
Copyright©1995 Taligent,Inc. All rights reserved.