---

Line methods

Functions
STStatus	STLineNew (STLine *oLine, STText iText, STPosition iPosition, STCharCount iCharCount, STCharCount *oCharCount)
	Creates a new STLine object. More...
STStatus	STLineNewForWidth (STLine *oLine, STText iText, STPosition iPosition, double iWidth, STCharCount *oCharCount)
	Creates a new STLine object with as many characters as can fit within the width specified by iWidth. More...
STStatus	STLineDispose (STLine iLine)
	STLine destructor. More...
STStatus	STLineSerialize (STLine iLine, int iFileDes)
	Writes an XML representation of the STLine object environment to the output stream. More...
STStatus	STLineDeserialize (STLine *Line, int iFileDes)
	Reads a previously serialized STLine object from an input stream and creates a new STLine object. More...
STStatus	STLineGrow (STLine iLine, STBoolean iAppend, STCharCount iCharCount)
	Adds characters to the beginning or to the end of the line. More...
STStatus	STLineShrink (STLine iLine, STBoolean iFromEnd, STCharCount iCharCount)
	Removes characters from the beginning or from the end of the line. More...
STStatus	STLineGetPosition (STLine iLine, STPosition *oPosition, STCharCount *oCharCount)
	Queries line position within STText object. More...
STStatus	STLineGetDesignMetrics (STLine iLine, STExtLineMetrics *oMetrics)
	Retrieves design metrics for the line based on scaled font design metrics. More...
STStatus	STLineSetMetrics (STLine iLine, STExtLineMetrics *iLineMetrics, STBaselines *iBaselines)
	Imposes metrics on a line. More...
STStatus	STLineGetMetrics (STLine iLine, STExtLineMetrics **oLineMetrics, STBaselines **oBaselines)
	Queries metrics previously imposed on a line. More...
STStatus	STLineMeasureText (STLine iLine, STRectanglePtr oBBox)
	Calculates a typographic bounding rectangle in user space of a line ignoring all imposed metrics and attributes. More...
STStatus	STLineMeasureTextImage (STLine iLine, STGraphics iGraphics, STRectanglePtr oBBox)
	Calculates a standard bounding rectangle of a laid-out line of text after all attributes (justification, alignment, etc.) have been applied in user space. More...
STStatus	STLineGetGlyphBounds (STLine iLine, STGraphics iGraphics, int iMaxBoundsCount, STBounds iBounds, int *oBoundsCount, STTrapezoidPtr *oBounds)
	Calculates boundaries of glyphs of a final laid-out line in device coordinates. More...
STStatus	STLineHitTest (STLine iLine, double iX, double iY, STPosition *oPrimaryOffset, STBoolean *oIsLeading, STPosition *oSecondaryOffset)
	Converts a pair of coordinates to the logical character offset. More...
STStatus	STLinePositionToCaret (STLine iLine, STPosition iPosition, STBoolean iIsLeading, STCaret *oStrongCaret, STCaret *oWeakCaret, STBoolean *oSplitCaret)
	Returns one or two carets (strong and weak) for a specified logical character position. More...
STStatus	STLineMoveCaret (STLine iLine, STPosition iOffset, STCaretDirection iDirection, STCaretMovement iMovementType, STPosition *oOffset)
	Calculates a new position of the caret. More...
STStatus	STLineRender (STLine iLine, STGraphics iDevice)
	Renders text represented by an STLine object on an STRastderDevice. More...
STStatus	STLineAddHighlight (STLine iLine, STPosition iCharOffset, STCharCount iCharCount)
	Adds a highlighted region identified by the first character and the number of characters to an STLine object. More...
STStatus	STLineRemoveHighlight (STLine iLine, STPosition iCharOffset, STCharCount iCharCount)
	Removes a highlighted region from the text layout. More...
STStatus	STLineGetHighlights (STLine iLine, STCount *oRegionCount, STPosition **oCharOffset, STCharCount **oCharCount)
	Queries currently defined highlighted regions. More...

---

Function Documentation

STStatus STLineAddHighlight (  STLine    iLine, STPosition    iCharOffset, STCharCount    iCharCount )

Adds a highlighted region identified by the first character and the number of characters to an STLine object. STLineRender() needs to be called to display it. Parameters: iLine  STLine object iCharOffset  first character to highlight iCharCount  number of characters in the highlighted region. Returns: STStatus

STStatus STLineDeserialize (  STLine *    Line, int    iFileDes )

Reads a previously serialized STLine object from an input stream and creates a new STLine object. Parameters: oLine  new STLine object iFileDes  file descriptor of an open file Returns: STStatus

STStatus STLineDispose (  STLine    iLine )

STLine destructor. Parameters: iLine  STLine object Returns: STStatus

STStatus STLineGetDesignMetrics (  STLine    iLine, STExtLineMetrics *    oMetrics )

Retrieves design metrics for the line based on scaled font design metrics. Returned metrics is in user space. Parameters: iLine  Line object oMetrics  metrics is stored there Returns: STStatus

STStatus STLineGetGlyphBounds (  STLine    iLine, STGraphics    iGraphics, int    iMaxBoundsCount, STBounds    iBounds, int *    oBoundsCount, STTrapezoidPtr *    oBounds )

Calculates boundaries of glyphs of a final laid-out line in device coordinates. Parameters: iLine  STLine object iGraphics  STGraphics object that includes either a raster or an outline device iMaxBoundsCount  specifies the precision of the output - the maximal number of trapezoids the function can allocate to store glyph bounds. Set it to 1 if only one trapezoid for the entire line is requested iBoundsType  specifies the type of origin used for calculating bounds oBoundsCount  number of trapezoids in the oBounds array oBounds  array of bounding trapezoids

STStatus STLineGetHighlights (  STLine    iLine, STCount *    oRegionCount, STPosition **    oCharOffset, STCharCount **    oCharCount )

Queries currently defined highlighted regions. Parameters: iLine  a line object oRegionCount  number of highlighted regions oCharOffset  array of first first character offsets of highlighted regions oCharCount  array of lengths of highlighted regions Returns: STStatus

STStatus STLineGetMetrics (  STLine    iLine, STExtLineMetrics **    oLineMetrics, STBaselines **    oBaselines )

Queries metrics previously imposed on a line. Parameters: iLine  STLine oLineWidth  line width oLineMetrics  ascent and descent oBaselines  baselines Returns: STStatus

STStatus STLineGetPosition (  STLine    iLine, STPosition *    oPosition, STCharCount *    oCharCount )

Queries line position within STText object. Parameters: iLine  STLine object oPosition  returns a first character offset of the line within STText oCharCount  returns a number of characters in the line Returns: STStatus

STStatus STLineGrow (  STLine    iLine, STBoolean    iAppend, STCharCount    iCharCount )

Adds characters to the beginning or to the end of the line. This function is used for creating customized line-break algorithms. Parameters: iLine  STLine object iAppend  true if characters are appended, false if prepended iCharCount  specifies the number of added characters Returns: STStatus

STStatus STLineHitTest (  STLine    iLine, double    iX, double    iY, STPosition *    oPrimaryOffset, STBoolean *    oIsLeading, STPosition *    oSecondaryOffset )

Converts a pair of coordinates to the logical character offset. Parameters: iLine  STLine object iX  X coordinate relative to the UL corner of the line bounding rectangle iY  Y coordinate relative to the UL corner of the line bounding rectangle oPrimaryOffset  logical offset of the glyph closest to (iX, iY) coordinates oIsLeading  is hit leading or trailing oSecondaryOffset  if (iX, iY) are on a line direction boundary this gives the second logical offset.

STStatus STLineMeasureText (  STLine    iLine, STRectanglePtr    oBBox )

Calculates a typographic bounding rectangle in user space of a line ignoring all imposed metrics and attributes. Parameters: iLine  STLine object oBBox  bounding box values are stored here on return Returns: STStatus

STStatus STLineMeasureTextImage (  STLine    iLine, STGraphics    iGraphics, STRectanglePtr    oBBox )

Calculates a standard bounding rectangle of a laid-out line of text after all attributes (justification, alignment, etc.) have been applied in user space. Parameters: iLine  STLine object iGraphics  STGraphics object that includes either a raster or an outline device oBBox  bounding box values are stored in this structure on return

STStatus STLineMoveCaret (  STLine    iLine, STPosition    iOffset, STCaretDirection    iDirection, STCaretMovement    iMovementType, STPosition *    oOffset )

Calculates a new position of the caret. The caret can be moved by characters, words or Unicode clusters. Direction can be previous, next, left or right. When the initial position of the caret is on a line direction boundary, this function calculates the new position of the primary caret. Inside an LTR text and not on the direction boundary "next" is equivalent to "right," and "previous" is equivalent to "left." Inside an RTL text "next" is equivalent to "left" and "previous" is equivalent to "right." For vertical text "left" is "top" and "right" is "bottom" Parameters: iLine  STLine object iOffset  initial caret position iDirectionType  specifies direction - left, right, next, or previous iMovementType  specifies movement type - character, word, or cluster oOffset  new caret position Returns: STStatus

STStatus STLineNew (  STLine *    oLine, STText    iText, STPosition    iPosition, STCharCount    iCharCount, STCharCount *    oCharCount )

Creates a new STLine object. STLine is a unit of displayable text. It is derived from STText object and refers its text. A line-breaking algorithm can be implemented by sequentually adding characters to the STLine object and measuring its typographic bounds. Parameters: oLine  pointer to the constructed STLine object iText  STText object being broken into lines iPosition  an offset from the first character of the STText object iCharCount  number of characters to add to the line. A special value of ST_CHARCOUNT_TOEND adds all STText characters to this STLine object oCharCount  actual number of added characters is stored here Returns: STStatus

STStatus STLineNewForWidth (  STLine *    oLine, STText    iText, STPosition    iPosition, double    iWidth, STCharCount *    oCharCount )

Creates a new STLine object with as many characters as can fit within the width specified by iWidth. Parameters: oLine  pointer to the constructed STLine object iText  STText object being broken into lines iPosition  an offset from the first character of the STText object iWidth  text width of the line in typographic points. To use text width set for the parent STText object use CWidthNotSet oCharCount  actual number of added characters is stored here Returns: STStatus

STStatus STLinePositionToCaret (  STLine    iLine, STPosition    iPosition, STBoolean    iIsLeading, STCaret *    oStrongCaret, STCaret *    oWeakCaret, STBoolean *    oSplitCaret )

Returns one or two carets (strong and weak) for a specified logical character position. Parameters: iLine  STLine object iPosition  logical offset of the character within STLine's parent STText object iIsLeading  matters only if character at iOffset is at line direction boundary oStrongCaret  denotes primary (or main if oSplitCaret is false) caret oWeakCaret  denotes secondary (or main if oSplitCaret is false) caret oSplitCaret  indicates if character at iOffsets is at line direction boundary

STStatus STLineRemoveHighlight (  STLine    iLine, STPosition    iCharOffset, STCharCount    iCharCount )

Removes a highlighted region from the text layout. Parameters: iLine  STLine object iCharOffset  offset to the first character to remove highlighting from iCharCount  number of characters in the region Returns: STStatus

STStatus STLineRender (  STLine    iLine, STGraphics    iDevice )

Renders text represented by an STLine object on an STRastderDevice. Parameters: iLine  STLine object iGraphics  STGraphics object Returns: STStatus

STStatus STLineSerialize (  STLine    iLine, int    iFileDes )

Writes an XML representation of the STLine object environment to the output stream. Parameters: iLine  STLine object iFileDes  file descriptor of an open file Returns: STStatus

STStatus STLineSetMetrics (  STLine    iLine, STExtLineMetrics *    iLineMetrics, STBaselines *    iBaselines )

Imposes metrics on a line. Parameters: iLine  STLine iLineWidth  width of the line or CWidthNotSet to use the value derived from its parent STText object iLineMetrics  sets ascent and descent or NULL pointer to use the value derived from its parent STText object iBaselines  baselines of this line of text or NULL pointer to use the value derived from its parent STText object Returns: STStatus

STStatus STLineShrink (  STLine    iLine, STBoolean    iFromEnd, STCharCount    iCharCount )

Removes characters from the beginning or from the end of the line. Parameters: iLine  STLine object iFromEnd  true if characters are removed from line end, false if from line start iCharCount  specifies the number of removed characters Returns: STStatus

---