#include <ITextRuns.h>

Inheritance diagram for ITextRuns:

Public Types
enum	{ kDefaultIID = IID_ITEXTRUNS }

Public Member Functions
virtual ITextRun *	QueryRunInterface (const RunDescription &description)=0

virtual const RunDescription &	GetRun (int32 at, int32 run)=0

virtual const RunDescription &	GetRun (int32 storyIndex, int32 at, int32 run)=0

virtual bool16	TextRunsContainedInLine (int32 storyIndex, int32 lineIndex)=0

virtual void	DrawRuns (int32 at, IGraphicsPort gPort, const PMRect &clipRect, const PMPoint &scrollCompensationValue, IPMFont displayFont, PMReal displaySize, const LineDescription &description, bool16 topLineInDraw)=0

virtual void	DrawRuns (int32 storyIndex, int32 at, IGraphicsPort gPort, const PMRect &clipRect, const PMPoint &scrollCompensationValue, IPMFont displayFont, PMReal displaySize, const LineDescription &description, bool16 topLineInDraw)=0

virtual void	CopyRuns (K2Vector< RunDescription > source, K2Vector< RunDescription > destination)=0

virtual void	AppendRun (LineDescription &line, RunDescription::RunType runType, TextIndex runStartOffset, TextIndex runEndOffset, UIDRef storyThreadRef, RealAGMColor runColor=RealAGMColor(1.0, 1.0, 1.0))=0

virtual int32	GetNumRuns (int32 at)=0

virtual int32	GetNumRuns (int32 storyIndex, int32 at)=0

virtual PMRect	CalculateRunRect (int32 lineIndex, int32 runIndex)=0

virtual int32	FindIndexOfRunAtPoint (const PMPoint &point, int32 *lineIndex)=0

virtual int32	FindIndexOfRunAtPoint (const PMPoint &point, int32 lineIndex)=0

virtual int32	GetLastRunIndex (int32 lineIndex)=0

virtual int32	GetLastRunIndex (int32 storyIndex, int32 lineIndex)=0

virtual PMReal	ComputeRunWidth (int32 lineIndex, const RunDescription &runDescription, int32 *runLength)=0

virtual bool8	GetUseTextRuns ()=0

virtual TextIndex	GetLineStartOffsetAtRun (int32 lineIndex, int32 runIndex)=0

virtual TextIndex	GetLineEndOffsetAtRun (int32 lineIndex, int32 runIndex)=0

virtual bool16	FindCharacterAtXPosition (int32 atLineIndex, int32 atRunIndex, PMReal &xPosition, int32 &offsetIntoLine)=0

virtual int32	FindIndexOfRunAtTextModelOffset (LineDescription &description, int32 atTextModelOffset)=0

virtual int32	FindIndexOfRunAtDisplayOffset (TextIndex offset, int32 &offsetIntoRun, bool16 bUsingEndOfLine=kFalse)=0

virtual UIDRef	GetNoteContent (ITextModel *model, TextIndex textStart, int32 &textLength, WideString &textContent, int32 startIndex=-1)=0

virtual TextIndex	FindInitialRunStart (int32 at, int32 runIndex, RunDescription::RunType type)=0

virtual TextIndex	FindInitialRunStart (int32 storyIndex, int32 at, int32 runIndex, RunDescription::RunType type)=0

virtual RunDescription *	FindRunAtDisplayOffset (TextIndex galleyDisplayOffset, int32 lineIndex, int32 *runIndex=nil)=0

virtual RunDescription *	FindRunAtDisplayOffset (int32 storyIndex, TextIndex galleyDisplayOffset, int32 lineIndex, int32 *runIndex=nil)=0

virtual int32	GetRunChunk (ITextModel model, const RunDescription &description, TextIndex textStart, int32 textLength, WideString &textContent, float widths, bool16 showInvisibles, int32 bufferSize, IFontMgr::FontStyleBits &fontStyle, IDrawingStyle::CapitalizeMode &capMode, int32 lineIndex, int32 runIndex)=0

virtual int32	GetRunChunk (int32 storyIndex, ITextModel model, const RunDescription &description, TextIndex textStart, int32 textLength, WideString &textContent, float widths, bool16 showInvisibles, int32 bufferSize, IFontMgr::FontStyleBits &fontStyle, IDrawingStyle::CapitalizeMode &capMode, int32 lineIndex, int32 runIndex)=0

virtual int32	GetRunChunk (int32 storyIndex, ITextModel model, const RunDescription &description, TextIndex textStart, int32 textLength, float widths, bool16 showInvisibles, int32 bufferSize, IFontMgr::FontStyleBits &fontStyle, IDrawingStyle::CapitalizeMode &capMode, int32 lineIndex, int32 runIndex)=0

virtual PMReal	DrawRegularTextRun (int32 at, IGraphicsPort gPort, IPMFont displayFont, PMReal displaySize, int32 runIndex, const RealAGMColor &textColor, const PMPoint &drawPt, bool16 showInvisibles)=0

virtual int32	FindIndexOfRunAtPoint (int32 storyIndex, const PMPoint &point, int32 *lineIndex)=0

virtual int32	FindIndexOfRunAtPoint (int32 storyIndex, const PMPoint &point, int32 lineIndex)=0

virtual void	DrawLineOverlaps (int32 at, IGraphicsPort *gPort, const PMPoint &scrollCompensationValue, const LineDescription &description, bool16 topLineInDraw, int32 storyIndex)=0

virtual bool16	GetExtendedRunSpanInformation (int32 storyIndex, const RunLocation &runIndex, RunDescription::RunType type, RangeData displayIndexRange, RunLocation extendedRunStart, RunLocation *extendedRunEnd)=0

Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0

virtual void	AddRef () const =0

virtual void	Release () const =0

Detailed Description

The TextRuns interface has methods related to the handling of story/galley text runs. Note that when talking about textruns with regard to this interface these are not character style runs but rather. Runs of a certain text display type like a inline note text run footnote text run or regular text run. Each line displayed in story and galley may contain text runs. It's possible also that a line may contain no text runs. This would be the case for divider lines although this may change.

Member Function Documentation

virtual void ITextRuns::AppendRun	(	LineDescription &	line,
		RunDescription::RunType	runType,
		TextIndex	runStartOffset,
		TextIndex	runEndOffset,
		UIDRef	storyThreadRef,
		RealAGMColor	runColor = `RealAGMColor(1.0, 1.0, 1.0)`
	)

pure virtual

depricated do not use

Returns: void

virtual PMRect ITextRuns::CalculateRunRect	(	int32	lineIndex,
		int32	runIndex
	)

pure virtual

Gets line owned rectangular screen area for a given run

Parameters

lineIndex	index of line to get rect of
runIndex	index of run to get rect of

Returns: rectangle describing draw bounds of the run

virtual PMReal ITextRuns::ComputeRunWidth	(	int32	lineIndex,
		const RunDescription &	runDescription,
		int32 *	runLength
	)

pure virtual

depricated

virtual void ITextRuns::CopyRuns	(	K2Vector< RunDescription > *	source,
		K2Vector< RunDescription > *	destination
	)

pure virtual

Used to copy run information from one LineDescription to another.

Parameters

source	copy run information from this
source	item to make a copy of
destination	item to copy to

Returns: void

virtual void ITextRuns::DrawLineOverlaps	(	int32	at,
		IGraphicsPort *	gPort,
		const PMPoint &	scrollCompensationValue,
		const LineDescription &	description,
		bool16	topLineInDraw,
		int32	storyIndex
	)

pure virtual

Internal use for handling lines that draw over other lines. Called by DrawRun().

Parameters

at	index of line to draw overlap portion of
gPort	port to draw in
scrollCompensationValue	vertical scroll compensation value
description	description of line to draw overlap portion of
topLineInDraw	optimiztion kTrue if this is the first line drawn in a inval
storyIndex	index of story to draw overlaps in.

Returns: void.

virtual PMReal ITextRuns::DrawRegularTextRun	(	int32	at,
		IGraphicsPort *	gPort,
		IPMFont *	displayFont,
		PMReal	displaySize,
		int32	runIndex,
		const RealAGMColor &	textColor,
		const PMPoint &	drawPt,
		bool16	showInvisibles
	)

pure virtual

Draw a regular text run. That is a run that is part of the primary text model. Called by DrawRuns() and some instances of DrawRun()

Parameters

at	index line to draw text of
gPort	graphics port to draw text in
displayFont	font to draw in
displaySize	size of text to draw
runIndex	index of the run to draw.
textColor	color to draw the text
drawPt	where to draw the text.
showInvisibles	kTrue if want hidden character information to be filled out. See IStoryService.
showInvisibles	should it show the invisible character symbols

Returns: returns width of text drawn

virtual void ITextRuns::DrawRuns	(	int32	at,
		IGraphicsPort *	gPort,
		const PMRect &	clipRect,
		const PMPoint &	scrollCompensationValue,
		IPMFont *	displayFont,
		PMReal	displaySize,
		const LineDescription &	description,
		bool16	topLineInDraw
	)

pure virtual

Used to draw all of the text runs in a line

Parameters

at	index line to draw runs of
gPort	IGraphicsPort to draw runs in
clipRect	area of the graphics port we are allowed to draw in
scrollCompensationValue	amount scrolled vertically in the view
displayFont	instance of display font we are using to draw the text may in fact not be used if this font is not appropriate for a run
displaySize	size of the display font we use to draw text.
description	description of the line. DrawRuns will draw the runs contained in this line description
topLineInDraw	a flag to indicate whether this is the first line in this draw sequence (not usually important it is used as an optimization)

Returns: void

virtual void ITextRuns::DrawRuns	(	int32	storyIndex,
		int32	at,
		IGraphicsPort *	gPort,
		const PMRect &	clipRect,
		const PMPoint &	scrollCompensationValue,
		IPMFont *	displayFont,
		PMReal	displaySize,
		const LineDescription &	description,
		bool16	topLineInDraw
	)

pure virtual

Used to draw all of the text runs in a line

Parameters

storyIndex	index of story to draw runs for
at	index line to draw runs of
gPort	IGraphicsPort to draw runs in
clipRect	area of the graphics port we are allowed to draw in
scrollCompensationValue	amount scrolled vertically in the view
displayFont	instance of display font we are using to draw the text may in fact not be used if this font is not appropriate for a run
displaySize	size of the display font we use to draw text.
description	description of the line. DrawRuns will draw the runs contained in this line description
topLineInDraw	a flag to indicate whether this is the first line in this draw sequence (not usually important it is used as an optimization)

Returns: void

virtual bool16 ITextRuns::FindCharacterAtXPosition	(	int32	atLineIndex,
		int32	atRunIndex,
		PMReal &	xPosition,
		int32 &	offsetIntoLine
	)

pure virtual

This method assumes that the caller has already determined that a Point is within the run specified by the parameter atLineIndex/atRunIndex and is now asking which character within the run has been hit based on xPosition. The routine will alway return a valid result. xPosition starts at left point of container panel

Parameters

atLineIndex	index of line to character in
atRunIndex	index of run to get character in
xPosition	position of interest
offsetIntoLine	index into line of the character at the xPosition

Returns: kTrue if found a valid character at given xPosition

virtual int32 ITextRuns::FindIndexOfRunAtDisplayOffset	(	TextIndex	offset,
		int32 &	offsetIntoRun,
		bool16	bUsingEndOfLine = `kFalse`
	)

pure virtual

Given a galley display index find the run. A galley display index includes runs that are outside of the primary text thread.

Parameters

offset	text display index to find run for
offsetIntoRun	returns offset into run for the given text display index
bUsingEndOfLine	if kFalse skip to start of next line if text index is at end of a line

Returns: index of run at the display text index

virtual int32 ITextRuns::FindIndexOfRunAtPoint	(	const PMPoint &	point,
		int32 *	lineIndex
	)

pure virtual

Get the index of a run at a given point on the screen

Parameters

point	where on the screen is of interest. Given in terms of 0 being first line in view.
lineIndex	filled in by the routine this is the index of the line the returned run is in

Returns: index of the run (may be -1 if none is found).

virtual int32 ITextRuns::FindIndexOfRunAtPoint	(	const PMPoint &	point,
		int32	lineIndex
	)

pure virtual

Same as other FindIndexOfRunAtPoint but if you already know the line that was hit use this one because it is faster.

Parameters

point	where on the screen is of interest. Given in terms of 0 being first line in view.
lineIndex	of the line which was hit.

Returns: index of the run (may be -1 if none is found).

virtual int32 ITextRuns::FindIndexOfRunAtPoint	(	int32	storyIndex,
		const PMPoint &	point,
		int32 *	lineIndex
	)

pure virtual

Get the index of a run at a given point on the screen

Parameters

storyIndex	index of story to use to find point in.
point	where on the screen is of interest. Given in terms of 0 being first line in view.
lineIndex	filled in by the routine this is the index of the line the returned run is in

Returns: index of the run (may be -1 if none is found).

virtual int32 ITextRuns::FindIndexOfRunAtPoint	(	int32	storyIndex,
		const PMPoint &	point,
		int32	lineIndex
	)

pure virtual

Same as other FindIndexOfRunAtPoint but if you already know the line that was hit use this one because it is faster.

Parameters

storyIndex	index of story to use to find point in.
point	where on the screen is of interest. Given in terms of 0 being first line in view.
lineIndex	of the line which was hit.

Returns: index of the run (may be -1 if none is found).

virtual int32 ITextRuns::FindIndexOfRunAtTextModelOffset	(	LineDescription &	description,
		int32	atTextModelOffset
	)

pure virtual

Given a text model index find the run. Only works for runs that are part of the primary thread. Use FindIndexOfRunAtDisplayOffset() to find runs that contain external data (like notes, deleted text). FindIndexOfRunAtDisplayOffset() is valid for regular text runs too. Mostly for internal use.

Parameters

description	of line this line will look in
atTextModelOffset	text model index that the run will be found for

Returns: index of run at the text index

virtual TextIndex ITextRuns::FindInitialRunStart	(	int32	at,
		int32	runIndex,
		RunDescription::RunType	type
	)

pure virtual

Find the first run display offset for a set of associated runs that span multiple lines. For instance, a note may span many lines and have many associated run this routine will find the line that the note starts in and get the display index of the first character in the note. Useful to find the starting galley display offset of a note or deleted text run that has been split across several lines.

Parameters

at	index of line to start searching for run start at
runIndex	index of run with in line to start searching for run start display index at.
type	type of run the run group belongs to

Returns: display index of the first run start that heads a run group.

virtual TextIndex ITextRuns::FindInitialRunStart	(	int32	storyIndex,
		int32	at,
		int32	runIndex,
		RunDescription::RunType	type
	)

pure virtual

Find the first run display offset for a set of associated runs that span multiple lines. For instance, a note may span many lines and have many associated run this routine will find the line that the note starts in and get the display index of the first character in the note. Useful to find the starting galley display offset of a note or deleted text run that has been split across several lines.

Parameters

storyIndex	index of line to start searching for run start at
at	index of line to start searching for run start at
runIndex	index of run with in line to start searching for run start display index at.
type	type of run the run group belongs to

Returns: display index of the first run start that heads a run group.

virtual RunDescription* ITextRuns::FindRunAtDisplayOffset	(	TextIndex	galleyDisplayOffset,
		int32	lineIndex,
		int32 *	runIndex = `nil`
	)

pure virtual

Find a run in the line that contains a galley display offset

Parameters

galleyDisplayOffset	display index to search for
lineIndex	line that we want to search within.
runIndex	return the index of the run.

Returns: return a discription of the run that is at a given display index.

virtual RunDescription* ITextRuns::FindRunAtDisplayOffset	(	int32	storyIndex,
		TextIndex	galleyDisplayOffset,
		int32	lineIndex,
		int32 *	runIndex = `nil`
	)

pure virtual

Find a run in the line that contains a galley display offset

Parameters

storyIndex	index of story to search within.
galleyDisplayOffset	display index to search for
lineIndex	line that we want to search within.
runIndex	return the index of the run.

Returns: return a discription of the run that is at a given display index.

virtual bool16 ITextRuns::GetExtendedRunSpanInformation	(	int32	storyIndex,
		const RunLocation &	runIndex,
		RunDescription::RunType	type,
		RangeData *	displayIndexRange,
		RunLocation *	extendedRunStart,
		RunLocation *	extendedRunEnd
	)

pure virtual

Given a starting run this routine will give back information on the extent of the whole block of associated runs. For example, a note may span many lines and consist of many individual runs this routine will give information on both where the note begins an ends and what the total text span of the run is in galley/story display indexes. This is useful to know when navigating through text in the order things are displayed rather than the order text is actually stored in the text moded. Return true if succesful and false otherwise

Parameters

storyIndex	TextLines story index of the story we are interested in (see ITextLines interface)
runIndex	The location of the start run to begin search at
type	the type of the start run
displayIndexRange	returns display index range of the total extended run
extendedRunStart	returns the lineIndex and runIndex of the first run in the extended run
extendedRunEnd	return the lineIndex and the runIndex of the last run in the extended run.

virtual int32 ITextRuns::GetLastRunIndex ( int32 lineIndex )

pure virtual

Get index of the last run with in a line.

Parameters

lineIndex to get run for

Returns: index of the run (may be -1 if none is found).

virtual int32 ITextRuns::GetLastRunIndex	(	int32	storyIndex,
		int32	lineIndex
	)

pure virtual

Get index of the last run with in a line.

Parameters

storyIndex	index of story to get run of
lineIndex	to get run for

Returns: index of the run (may be -1 if none is found).

virtual TextIndex ITextRuns::GetLineEndOffsetAtRun	(	int32	lineIndex,
		int32	runIndex
	)

pure virtual

Get the text index of the end of the line this run is in if this is an inlinenotetext run we return the thread start offset; otherwise, return the run's line start offset. Not recommended for external use

Parameters

lineIndex	index of line to get end offset of
runIndex	index of run to get end offset of

Returns: return a text index of the end of the line associated with given run

virtual TextIndex ITextRuns::GetLineStartOffsetAtRun	(	int32	lineIndex,
		int32	runIndex
	)

pure virtual

Get the text index of the start of line this run is in if this is an inlinenotetext run we return the thread start offset; otherwise, return the run's line start offset. Not recommended for external use

Parameters

lineIndex	index of line to get start offset of
runIndex	index of run to get start offset of

Returns: return a text index of the start of the line associated with given run

virtual UIDRef ITextRuns::GetNoteContent	(	ITextModel *	model,
		TextIndex	textStart,
		int32 &	textLength,
		WideString &	textContent,
		int32	startIndex = `-1`
	)

pure virtual

Returns the note text content at a given offset. It's better to use Note related routines in general to get information like this. This routine is not neccessarily efficient.

Parameters

model	the model to find note text in
textStart	anchor position of the note text
textLength	returned character length of note text at requested position
textContent	returned note text characters at requested text position
startIndex	offset into note text to start getting text at

Returns: UIDRef of the note text owned item

virtual int32 ITextRuns::GetNumRuns ( int32 at )

pure virtual

Used to get text of a run when drawing.

Parameters

at	index of line to get text of

Returns: number of runs in line

virtual int32 ITextRuns::GetNumRuns	(	int32	storyIndex,
		int32	at
	)

pure virtual

Get number of runs within a line

Parameters

storyIndex	index of story to get run information for
at	index of line to get run information for

Returns: number of runs within the line

virtual const RunDescription& ITextRuns::GetRun	(	int32	at,
		int32	run
	)

pure virtual

Get a RunDescription for a given line and run index

Parameters

at	index of line to get RunDescription of
run	index of run within line to get RunDescription of

Returns: a RunDescription

virtual const RunDescription& ITextRuns::GetRun	(	int32	storyIndex,
		int32	at,
		int32	run
	)

pure virtual

Get a RunDescription for a given story, line and run index

Parameters

storyIndex	index of story to get RunDescription of
at	index of line to get RunDescription of
run	index of run within line to get RunDescription of

Returns: a RunDescription

virtual int32 ITextRuns::GetRunChunk	(	ITextModel *	model,
		const RunDescription &	description,
		TextIndex	textStart,
		int32	textLength,
		WideString &	textContent,
		float *	widths,
		bool16	showInvisibles,
		int32	bufferSize,
		IFontMgr::FontStyleBits &	fontStyle,
		IDrawingStyle::CapitalizeMode &	capMode,
		int32	lineIndex,
		int32	runIndex
	)

pure virtual

This routine gets text in blocks of continuous font styles. Useful when you would like to measure text widths and for drawing.

Parameters

model	textmodel to get text for
description	desciption of run to get the text of
textStart	text index to start getting text at.
textLength	length of text interested in getting maximum.
textContent	text returned in this parameter.
widths	an array of glyph widths is filled out by GetRunChunk (array is preallocated by caller).
showInvisibles	kTrue if want hidden character information to be filled out. See IStoryService.
bufferSize	max number of characters that preallocated buffers will hold
fontStyle	returns the font style that the text should draw in
capMode	return the Capitize mode that the text would draw in
lineIndex	index of the line to get text for
runIndex	index of the run to get text for

Returns: return number of characters actually returned

virtual int32 ITextRuns::GetRunChunk	(	int32	storyIndex,
		ITextModel *	model,
		const RunDescription &	description,
		TextIndex	textStart,
		int32	textLength,
		WideString &	textContent,
		float *	widths,
		bool16	showInvisibles,
		int32	bufferSize,
		IFontMgr::FontStyleBits &	fontStyle,
		IDrawingStyle::CapitalizeMode &	capMode,
		int32	lineIndex,
		int32	runIndex
	)

pure virtual

This routine gets text in blocks of continuous font styles. Useful when you would like to measure text widths and for drawing.

Parameters

storyIndex	index of story to get the text of
model	textmodel to get text for
description	desciption of run to get the text of
textStart	text index to start getting text at.
textLength	length of text interested in getting maximum.
textContent	text returned in this parameter.
widths	an array of glyph widths is filled out by GetRunChunk (array is preallocated by caller).
showInvisibles	kTrue if want hidden character information to be filled out. See IStoryService.
bufferSize	max number of characters that preallocated buffers will hold
fontStyle	returns the font style that the text should draw in
capMode	return the Capitize mode that the text would draw in
lineIndex	index of the line to get text for
runIndex	index of the run to get text for

Returns: return number of characters actually returned

virtual int32 ITextRuns::GetRunChunk	(	int32	storyIndex,
		ITextModel *	model,
		const RunDescription &	description,
		TextIndex	textStart,
		int32	textLength,
		float *	widths,
		bool16	showInvisibles,
		int32	bufferSize,
		IFontMgr::FontStyleBits &	fontStyle,
		IDrawingStyle::CapitalizeMode &	capMode,
		int32	lineIndex,
		int32	runIndex
	)

pure virtual

This routine gets text in blocks of continuous font styles. Useful when you would like to measure text widths and for drawing. This version does not get actual text just the glyph data. This is more efficient than the other two versions of this call because the glyph data is cached while the text unicode data is not.

Parameters

storyIndex	index of story to get the text of
model	textmodel to get text for
description	desciption of run to get the text of
textStart	text index to start getting text at.
textLength	length of text interested in getting maximum.
widths	an array of glyph widths is filled out by GetRunChunk (array is preallocated by caller).
showInvisibles	kTrue if want hidden character information to be filled out. See IStoryService.
bufferSize	max number of characters that preallocated buffers will hold
fontStyle	returns the font style that the text should draw in
capMode	return the Capitize mode that the text would draw in
lineIndex	index of the line to get text for
runIndex	index of the run to get text for

Returns: return number of characters actually returned

virtual bool8 ITextRuns::GetUseTextRuns ( )

pure virtual

Returns true if we are using runs for the view associated with this interface

Returns: kTrue if we are using runs

virtual ITextRun* ITextRuns::QueryRunInterface ( const RunDescription & description )

pure virtual

Get an ITextRun interface for a given line description

Parameters

description a rundescription to get a cooresponding ITextRun for

Returns: An ITextRun interface instance.

virtual bool16 ITextRuns::TextRunsContainedInLine	(	int32	storyIndex,
		int32	lineIndex
	)

pure virtual

Tell the caller whether a line has any runs. Some lines don't for instance divider lines

Parameters

storyIndex	index of story the line is in
lineIndex	index of line interested in

Returns: kTrue if the line has runs. kFalse otherwise will return kFalse for invalid line numbers as well.

Public Types

Public Member Functions

Detailed Description

Member Function Documentation