Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
None.
Inherited By:
None.
Purpose:
TGGlyphRun is the most primitive renderable text object; it is a complete area-enclosing geometry with shape and location. This class represents a string of text characters, also known as a run of glyphs. The glyphs in any given run all have the same font, style, and point size.
A TGGlyphRun should contain:
- a TFont
- an origin point
- an array of glyphs
- a corresponding array of X offsets. These specify the distance of each glyph from the origin, in the direction of the text stream. If NIL is specified, the offsets default to offsets of cumulative character widths.
Optionally, a corresponding array of Y offsets can be specified; these are offsets from the origin in the direction perpendicular to the text stream. The direction of the text stream is by default kHorizontal; this can be changed to vertical by changing the so-called attachment to kVertical.
If any of the four items previously listed are missing, the TGGlyphRun functions as an empty geometry; it can be validly used, but it renders as nothing and returns kEmptyRect for its bounds.
The glyphs are font-specific codes. To use this class, you must coordinate the glyph codes with the specific TFont object.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Do not derive from this class.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TGGlyphRun (const TFont & font, unsigned long numberOfGlyphs, const GlyphCode glyphs [], const GCoordinate xOffsets [], const GCoordinate yOffsets [] =NIL, const TGPoint & origin =TGPoint :: kOrigin, EAttachment attachment =kHorizontal)
- TGGlyphRun ()
- TGGlyphRun (const TGGlyphRun &)
Interface Category:
API.
Purpose:
- Creates a new glyph run initialized with the specified parameter values.
- Default constructor.
- Copy constructor.
Calling Context:
- Call to create a new glyph run initialized with the specified parameters.
- Called by the stream-in operators.
- Called to copy an object.
Parameters:
- const TFont & font -The font in which to render the glyph run.
- unsigned long numberOfGlyphs -The number of characters in the run.
- const GlyphCode glyphs [] -An array containing the glyph codes for the characters in the run. You must coordinate the glyph codes with the TFont object.
- const GCoordinate xOffsets [] -The horizontal offsets between characters. If NIL is specified, the offsets default to offsets of cumulative character widths.
- const GCoordinate yOffsets [] =NIL -The vertical offsets between characters. The default value is NIL; characters are set horizontally.
- const TGPoint & origin =TGPoint :: kOrigin -The point at which to place the origin of the first character in the glyph run.
- EAttachment attachment =kHorizontal -The direction in which to lay out the characters.
- Takes no parameters.
- const TGGlyphRun & someRun -The glyph run to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
If any of the four items previously listed are missing, the TGGlyphRun functions as an empty geometry; it can be validly used, but it renders nothing and returns kEmptyRect for its bounds.
virtual ~ TGGlyphRun ()
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:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::operator>>=
TStream & operator >>=(TStream & towhere) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & towhere -The stream to which the object streams itself out.
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: TGGlyphRun::operator<<=
TStream & operator <<= (TStream & fromwhere)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromwhere -The stream from which the object streams itself in.
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: TGGlyphRun::operator==
bool operator ==(const TGGlyphRun &) const
Interface Category:
API.
Purpose:
Tests whether two objects are equal.
Calling Context:
Call this function by using the operator in an expression.
Parameters:
- const TGGlyphRun & other -The glyph run to be compared to this one.
Return Value:
Returns true if the two objects are equal.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::operator!=
bool operator != (const TGGlyphRun &) const
Interface Category:
API.
Purpose:
Tests whether two objects are equal.
Calling Context:
Call this function by using the operator in an expression.
Parameters:
- const TGGlyphRun & other -The glyph run to be compared to this one.
Return Value:
Returns true if the two objects are not equal.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::SetOrigin
void SetOrigin (const TGPoint & origin, EAttachment attachment =kHorizontal)
Interface Category:
API.
Purpose:
Sets the origin to the specified point. Optionally sets the attachment (which specifies whether the text stream is horizontal or vertical).
Calling Context:
Call this function to establish the glyph run's origin.
Parameters:
- const TGPoint & origin -The point at which to place the origin of the first character in the glyph run.
- EAttachment attachment =kHorizontal -The direction in which to lay out the characters. The default value is horizontal.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::CopyFont
TFont * CopyFont () const
Interface Category:
API.
Purpose:
Makes a copy of the glyph run's TFont and returns a reference to the copy.
Calling Context:
Call this function to obtain a copy of the glyph run's font.
Parameters:
Return Value:
A reference to the newly created copy of the TFont.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::CopyGlyphs
GlyphCode * CopyGlyphs () const
Interface Category:
API.
Purpose:
Makes a copy of the glyph run's glyph array and returns a reference to the copy.
Calling Context:
Call this function to obtain a copy of the glyph run's glyph array.
Parameters:
Return Value:
A reference to the newly created copy of the glyph array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::CopyXOffsets
GCoordinate * CopyXOffsets () const
Interface Category:
API.
Purpose:
Makes a copy of the glyph run's x offset array and returns a reference to the copy.
Calling Context:
Call this function to obtain a copy of the glyph run's x offset array.
Parameters:
Return Value:
A reference to the newly created copy of the x offset array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::CopyYOffsets
GCoordinate * CopyYOffsets () const
Interface Category:
API.
Purpose:
Makes a copy of the glyph run's y offset array and returns a reference to the copy.
Calling Context:
Call this function to obtain a copy of the glyph run's y offset array.
Parameters:
Return Value:
A reference to the newly created copy of the y offset array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::GetNumberOfGlyphs
unsigned long GetNumberOfGlyphs () const
Interface Category:
API.
Purpose:
Returns the size of the glyph array.
Calling Context:
Call this function to obtain the number of characters in the glyph run.
Parameters:
Return Value:
The number of characters in the glyph run.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::GetOrigin
TGPoint GetOrigin () const
Interface Category:
API.
Purpose:
Returns the origin point. The origin point is the point at which the origin of the first character in the glyph run is placed.
Calling Context:
Call this function to obtain the origin point of the glyph run.
Parameters:
Return Value:
Returns the origin point of the glyph run.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::GetAttachment
EAttachment GetAttachment () const
Interface Category:
API.
Purpose:
Reports whether the text stream is horizontal or vertical.
Calling Context:
Call this function to determine whether the glyph run is laid out horizontally or vertically.
Parameters:
Return Value:
Returns an EAttachment value indicating whether the glyph run is laid out horizontally or vertically.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::GetBounds
TGRect GetBounds () const
Interface Category:
API.
Purpose:
Returns the bounds of the entire glyph run, calculated by looking at the extents of each glyph's offset and ideal advance width, and the font's overall ascender and descender. This function is potentially expensive because it has to acquire the widths of each glyph and then compute the bounding box that encompasses all the individual glyph boxes. (This is the primary reason that this class supports a time stamp, so that classes built upon TGGlyphRun can implement more efficient bounds functions.)
Note that this is not a completely tight bounds, and might include some excess space. Furthermore, the excess space is heuristically defined; it is theoretically possible for a glyph to be hinted in such an extraordinary way that, at a particular point size, the hinted result could exceed the stated GetBounds. However, this would probably be considered an erroneous font.
Calling Context:
Call this function to determine the bounding rectangle of the glyph run.
Parameters:
Return Value:
The bounding rectangle of the glyph run.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TGGlyphRun::GetFont
const TFont * GetFont () const
Interface Category:
API.
Purpose:
Returns a reference to the glyph run's font.
Calling Context:
Call this function to obtain the glyph run's font.
Parameters:
Return Value:
A reference to the glyph run's font.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Contrast GetFont with CopyFont, which creates a copy of the glyph run's font and returns a reference to the copy.
Member Function: TGGlyphRun::GetGlyphs
const GlyphCode * GetGlyphs () const
Interface Category:
API.
Purpose:
Returns a reference to the glyph run's glyph array.
Calling Context:
Call this function to obtain the glyph run's glyph array.
Parameters:
Return Value:
A reference to the glyph run's glyph array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Contrast GetGlyphs with CopyGlyphs , which creates a copy of the glyph run's glyph array and returns a reference to the copy.
Member Function: TGGlyphRun::GetXOffsets
const GCoordinate * GetXOffsets () const
Interface Category:
API.
Purpose:
Returns a reference to the glyph run's x offset array.
Calling Context:
Call this function to obtain the glyph run's x offset array.
Parameters:
Return Value:
A reference to the glyph run's x offset array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Contrast GetXOffsets with CopyXOffsets , which creates a copy of the glyph run's x offset array and returns a reference to the copy.
Member Function: TGGlyphRun::GetYOffsets
const GCoordinate * GetYOffsets () const
Interface Category:
API.
Purpose:
Returns a reference to the glyph run's y offset array.
Calling Context:
Call this function to obtain the glyph run's y offset array.
Parameters:
Return Value:
A reference to the glyph run's y offset array.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Contrast GetYOffsets with CopyYOffsets , which creates a copy of the glyph run's y offset array and returns a reference to the copy.
Member Function: TGGlyphRun::operator=
TGGlyphRun & operator =(const TGGlyphRun &)
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:
Not 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.