Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Friends

gfxTextRun Class Reference

gfxTextRun is an abstraction for drawing and measuring substrings of a run of text. More...

#include <gfxFont.h>

Collaboration diagram for gfxTextRun:

List of all members.

Classes

class  CompressedGlyph
 This class records the information associated with a character in the input string. More...
struct  DetailedGlyph
 When the glyphs for a character don't fit into a CompressedGlyph record in SimpleGlyph format, we use an array of DetailedGlyphs instead. More...
struct  GlyphRun
class  GlyphRunIterator
class  GlyphRunOffsetComparator
struct  LigatureData
class  PropertyProvider
 Layout provides PropertyProvider objects. More...

Public Types

typedef gfxFont::RunMetrics Metrics

Public Member Functions

virtual ~gfxTextRun ()
PRBool IsClusterStart (PRUint32 aPos)
PRBool IsLigatureGroupStart (PRUint32 aPos)
PRBool CanBreakLineBefore (PRUint32 aPos)
PRUint32 GetLength ()
virtual PRBool SetPotentialLineBreaks (PRUint32 aStart, PRUint32 aLength, PRPackedBool *aBreakBefore, gfxContext *aRefContext)
 Set the potential linebreaks for a substring of the textrun.
void Draw (gfxContext *aContext, gfxPoint aPt, PRUint32 aStart, PRUint32 aLength, PropertyProvider *aProvider, gfxFloat *aAdvanceWidth)
 Draws a substring.
void DrawToPath (gfxContext *aContext, gfxPoint aPt, PRUint32 aStart, PRUint32 aLength, PropertyProvider *aBreakProvider, gfxFloat *aAdvanceWidth)
 Renders a substring to a path.
Metrics MeasureText (PRUint32 aStart, PRUint32 aLength, gfxFont::BoundingBoxType aBoundingBoxType, gfxContext *aRefContextForTightBoundingBox, PropertyProvider *aProvider)
 Computes the ReflowMetrics for a substring.
gfxFloat GetAdvanceWidth (PRUint32 aStart, PRUint32 aLength, PropertyProvider *aProvider)
 Computes just the advance width for a substring.
virtual PRBool SetLineBreaks (PRUint32 aStart, PRUint32 aLength, PRBool aLineBreakBefore, PRBool aLineBreakAfter, gfxFloat *aAdvanceWidthDelta, gfxContext *aRefContext)
 Clear all stored line breaks for the given range (both before and after), and then set the line-break state before aStart to aBreakBefore and after the last cluster to aBreakAfter.
PRUint32 BreakAndMeasureText (PRUint32 aStart, PRUint32 aMaxLength, PRBool aLineBreakBefore, gfxFloat aWidth, PropertyProvider *aProvider, PRBool aSuppressInitialBreak, gfxFloat *aTrimWhitespace, Metrics *aMetrics, gfxFont::BoundingBoxType aBoundingBoxType, gfxContext *aRefContextForTightBoundingBox, PRBool *aUsedHyphenation, PRUint32 *aLastBreak, PRBool aCanWordWrap, gfxBreakPriority *aBreakPriority)
 Finds the longest substring that will fit into the given width.
void SetContext (gfxContext *aContext)
 Update the reference context.
PRBool IsRightToLeft () const
gfxFloat GetDirection () const
void * GetUserData () const
void SetUserData (void *aUserData)
PRUint32 GetFlags () const
void SetFlagBits (PRUint32 aFlags)
void ClearFlagBits (PRUint32 aFlags)
const gfxSkipChars & GetSkipChars () const
PRUint32 GetAppUnitsPerDevUnit () const
gfxFontGroup * GetFontGroup () const
const PRUint8 * GetText8Bit () const
const PRUnichar * GetTextUnicode () const
const void * GetTextAt (PRUint32 aIndex)
const PRUnichar GetChar (PRUint32 i) const
PRUint32 GetHashCode () const
void SetHashCode (PRUint32 aHash)
virtual gfxTextRun * Clone (const gfxTextRunFactory::Parameters *aParams, const void *aText, PRUint32 aLength, gfxFontGroup *aFontGroup, PRUint32 aFlags)
nsresult AddGlyphRun (gfxFont *aFont, PRUint32 aStartCharIndex, PRBool aForceNewRun=0)
 We've found a run of text that should use a particular font.
void ResetGlyphRuns ()
void SortGlyphRuns ()
void SanitizeGlyphRuns ()
void SetSimpleGlyph (PRUint32 aCharIndex, CompressedGlyph aGlyph)
 Set the glyph data for a character.
void SetGlyphs (PRUint32 aCharIndex, CompressedGlyph aGlyph, const DetailedGlyph *aGlyphs)
void SetMissingGlyph (PRUint32 aCharIndex, PRUint32 aUnicodeChar)
void SetSpaceGlyph (gfxFont *aFont, gfxContext *aContext, PRUint32 aCharIndex)
PRBool FilterIfIgnorable (PRUint32 aIndex)
void FetchGlyphExtents (gfxContext *aRefContext)
 Prefetch all the glyph extents needed to ensure that Measure calls on this textrun not requesting tight boundingBoxes will succeed.
const CompressedGlyph * GetCharacterGlyphs ()
const DetailedGlyph * GetDetailedGlyphs (PRUint32 aCharIndex)
PRBool HasDetailedGlyphs ()
PRUint32 CountMissingGlyphs ()
const GlyphRun * GetGlyphRuns (PRUint32 *aNumGlyphRuns)
PRUint32 FindFirstGlyphRunContaining (PRUint32 aOffset)
virtual void CopyGlyphDataFrom (gfxTextRun *aSource, PRUint32 aStart, PRUint32 aLength, PRUint32 aDest, PRBool aStealData)
nsExpirationState * GetExpirationState ()
PRUint64 GetUserFontSetGeneration ()
void AdjustAdvancesForSyntheticBold (PRUint32 aStart, PRUint32 aLength)

Static Public Member Functions

static gfxTextRun * Create (const gfxTextRunFactory::Parameters *aParams, const void *aText, PRUint32 aLength, gfxFontGroup *aFontGroup, PRUint32 aFlags)

Protected Member Functions

 gfxTextRun (const gfxTextRunFactory::Parameters *aParams, const void *aText, PRUint32 aLength, gfxFontGroup *aFontGroup, PRUint32 aFlags, CompressedGlyph *aGlyphStorage)
 Initializes the textrun to blank.

Static Protected Member Functions

static CompressedGlyph * AllocateStorage (const void *&aText, PRUint32 aLength, PRUint32 aFlags)
 Helper for the Create() factory method to allocate the required glyph storage, and copy the text (modifying the aText parameter) if it is not flagged as persistent.

Friends

class GlyphRunIterator
class FontSelector

Detailed Description

gfxTextRun is an abstraction for drawing and measuring substrings of a run of text.

It stores runs of positioned glyph data, each run having a single gfxFont. The glyphs are associated with a string of source text, and the gfxTextRun APIs take parameters that are offsets into that source text.

gfxTextRuns are not refcounted. They should be deleted when no longer required.

gfxTextRuns are mostly immutable. The only things that can change are inter-cluster spacing and line break placement. Spacing is always obtained lazily by methods that need it, it is not cached. Line breaks are stored persistently (insofar as they affect the shaping of glyphs; gfxTextRun does not actually do anything to explicitly account for line breaks). Initially there are no line breaks. The textrun can record line breaks before or after any given cluster. (Line breaks specified inside clusters are ignored.)

It is important that zero-length substrings are handled correctly. This will be on the test!

gfxTextRun stores a list of zero or more glyphs for each character. For each glyph we store the glyph ID, the advance, and possibly an xoffset and yoffset. The idea is that a string is rendered by a loop that draws each glyph at its designated offset from the current point, then advances the current point by the glyph's advance in the direction of the textrun (LTR or RTL). Each glyph advance is always rounded to the nearest appunit; this ensures consistent results when dividing the text in a textrun into multiple text frames (frame boundaries are always aligned to appunits). We optimize for the case where a character has a single glyph and zero xoffset and yoffset, and the glyph ID and advance are in a reasonable range so we can pack all necessary data into 32 bits.

gfxTextRun methods that measure or draw substrings will associate all the glyphs in a cluster with the first character of the cluster; if that character is in the substring, the glyphs will be measured or drawn, otherwise they won't.

Member Typedef Documentation

typedef gfxFont::RunMetrics gfxTextRun::Metrics

Constructor & Destructor Documentation

virtual gfxTextRun::~gfxTextRun (  )  [virtual]
gfxTextRun::gfxTextRun ( const gfxTextRunFactory::Parameters *  aParams,
const void *  aText,
PRUint32  aLength,
gfxFontGroup *  aFontGroup,
PRUint32  aFlags,
CompressedGlyph *  aGlyphStorage 
) [protected]

Initializes the textrun to blank.

Parameters:
aGlyphStorage preallocated array of CompressedGlyph[aLength] for the textrun to use; if aText is not persistent, then it has also been appended to this array, so it must NOT be freed separately.

Member Function Documentation

nsresult gfxTextRun::AddGlyphRun ( gfxFont *  aFont,
PRUint32  aStartCharIndex,
PRBool  aForceNewRun = 0 
)

We've found a run of text that should use a particular font.

Call this only during initialization when font substitution has been computed. Call it before setting up the glyphs for the characters in this run; SetMissingGlyph requires that the correct glyphrun be installed.

If aForceNewRun, a new glyph run will be added, even if the previously added run uses the same font. If glyph runs are added out of strictly increasing aStartCharIndex order (via force), then SortGlyphRuns must be called after all glyph runs are added before any further operations are performed with this TextRun.

void gfxTextRun::AdjustAdvancesForSyntheticBold ( PRUint32  aStart,
PRUint32  aLength 
)
static CompressedGlyph* gfxTextRun::AllocateStorage ( const void *&  aText,
PRUint32  aLength,
PRUint32  aFlags 
) [static, protected]

Helper for the Create() factory method to allocate the required glyph storage, and copy the text (modifying the aText parameter) if it is not flagged as persistent.

PRUint32 gfxTextRun::BreakAndMeasureText ( PRUint32  aStart,
PRUint32  aMaxLength,
PRBool  aLineBreakBefore,
gfxFloat  aWidth,
PropertyProvider *  aProvider,
PRBool  aSuppressInitialBreak,
gfxFloat *  aTrimWhitespace,
Metrics *  aMetrics,
gfxFont::BoundingBoxType  aBoundingBoxType,
gfxContext *  aRefContextForTightBoundingBox,
PRBool *  aUsedHyphenation,
PRUint32 *  aLastBreak,
PRBool  aCanWordWrap,
gfxBreakPriority *  aBreakPriority 
)

Finds the longest substring that will fit into the given width.

Uses GetHyphenationBreaks and GetSpacing from aBreakProvider. Guarantees the following: -- 0 <= result <= aMaxLength -- result is the maximal value of N such that either N < aMaxLength && line break at N && GetAdvanceWidth(aStart, N) <= aWidth OR N < aMaxLength && hyphen break at N && GetAdvanceWidth(aStart, N) + GetHyphenWidth() <= aWidth OR N == aMaxLength && GetAdvanceWidth(aStart, N) <= aWidth where GetAdvanceWidth assumes the effect of SetLineBreaks(aStart, N, aLineBreakBefore, N < aMaxLength, aProvider) -- if no such N exists, then result is the smallest N such that N < aMaxLength && line break at N OR N < aMaxLength && hyphen break at N OR N == aMaxLength

The call has the effect of SetLineBreaks(aStart, result, aLineBreakBefore, result < aMaxLength, aProvider) and the returned metrics and the invariants above reflect this.

Parameters:
aMaxLength this can be PR_UINT32_MAX, in which case the length used is up to the end of the string
aLineBreakBefore set to true if and only if there is an actual line break at the start of this string.
aSuppressInitialBreak if true, then we assume there is no possible linebreak before aStart. If false, then we will check the internal line break opportunity state before deciding whether to return 0 as the character to break before.
aTrimWhitespace if non-null, then we allow a trailing run of spaces to be trimmed; the width of the space(s) will not be included in the measured string width for comparison with the limit aWidth, and trimmed spaces will not be included in returned metrics. The width of the trimmed spaces will be returned in aTrimWhitespace. Trimmed spaces are still counted in the "characters fit" result.
aMetrics if non-null, we fill this in for the returned substring. If a hyphenation break was used, the hyphen is NOT included in the returned metrics.
aBoundingBoxType whether to make the bounding box in aMetrics tight
aRefContextForTightBoundingBox a reference context to get the tight bounding box, if requested
aUsedHyphenation if non-null, records if we selected a hyphenation break
aLastBreak if non-null and result is aMaxLength, we set this to the maximal N such that N < aMaxLength && line break at N && GetAdvanceWidth(aStart, N) <= aWidth OR N < aMaxLength && hyphen break at N && GetAdvanceWidth(aStart, N) + GetHyphenWidth() <= aWidth or PR_UINT32_MAX if no such N exists, where GetAdvanceWidth assumes the effect of SetLineBreaks(aStart, N, aLineBreakBefore, N < aMaxLength, aProvider)
aCanWordWrap true if we can break between any two grapheme clusters. This is set by word-wrap: break-word
aBreakPriority in/out the priority of the break opportunity saved in the line. If we are prioritizing break opportunities, we will not set a break with a lower priority.
See also:
gfxBreakPriority.

Note that negative advance widths are possible especially if negative spacing is provided.

PRBool gfxTextRun::CanBreakLineBefore ( PRUint32  aPos  )  [inline]
void gfxTextRun::ClearFlagBits ( PRUint32  aFlags  )  [inline]
virtual gfxTextRun* gfxTextRun::Clone ( const gfxTextRunFactory::Parameters *  aParams,
const void *  aText,
PRUint32  aLength,
gfxFontGroup *  aFontGroup,
PRUint32  aFlags 
) [virtual]
virtual void gfxTextRun::CopyGlyphDataFrom ( gfxTextRun *  aSource,
PRUint32  aStart,
PRUint32  aLength,
PRUint32  aDest,
PRBool  aStealData 
) [virtual]
PRUint32 gfxTextRun::CountMissingGlyphs (  ) 
static gfxTextRun* gfxTextRun::Create ( const gfxTextRunFactory::Parameters *  aParams,
const void *  aText,
PRUint32  aLength,
gfxFontGroup *  aFontGroup,
PRUint32  aFlags 
) [static]
void gfxTextRun::Draw ( gfxContext *  aContext,
gfxPoint  aPt,
PRUint32  aStart,
PRUint32  aLength,
PropertyProvider *  aProvider,
gfxFloat *  aAdvanceWidth 
)

Draws a substring.

Uses only GetSpacing from aBreakProvider. The provided point is the baseline origin on the left of the string for LTR, on the right of the string for RTL.

Parameters:
aAdvanceWidth if non-null, the advance width of the substring is returned here.

Drawing should respect advance widths in the sense that for LTR runs, Draw(ctx, pt, offset1, length1, dirty, &provider, &advance) followed by Draw(ctx, gfxPoint(pt.x + advance, pt.y), offset1 + length1, length2, dirty, &provider, nsnull) should have the same effect as Draw(ctx, pt, offset1, length1+length2, dirty, &provider, nsnull). For RTL runs the rule is: Draw(ctx, pt, offset1 + length1, length2, dirty, &provider, &advance) followed by Draw(ctx, gfxPoint(pt.x + advance, pt.y), offset1, length1, dirty, &provider, nsnull) should have the same effect as Draw(ctx, pt, offset1, length1+length2, dirty, &provider, nsnull).

Glyphs should be drawn in logical content order, which can be significant if they overlap (perhaps due to negative spacing).

void gfxTextRun::DrawToPath ( gfxContext *  aContext,
gfxPoint  aPt,
PRUint32  aStart,
PRUint32  aLength,
PropertyProvider *  aBreakProvider,
gfxFloat *  aAdvanceWidth 
)

Renders a substring to a path.

Uses only GetSpacing from aBreakProvider. The provided point is the baseline origin on the left of the string for LTR, on the right of the string for RTL.

Parameters:
aAdvanceWidth if non-null, the advance width of the substring is returned here.

Drawing should respect advance widths in the way that Draw above does.

Glyphs should be drawn in logical content order.

UNLIKE Draw above, this cannot be used to render substrings that start or end inside a ligature.

void gfxTextRun::FetchGlyphExtents ( gfxContext *  aRefContext  ) 

Prefetch all the glyph extents needed to ensure that Measure calls on this textrun not requesting tight boundingBoxes will succeed.

Note that some glyph extents might not be fetched due to OOM or other errors.

PRBool gfxTextRun::FilterIfIgnorable ( PRUint32  aIndex  ) 
PRUint32 gfxTextRun::FindFirstGlyphRunContaining ( PRUint32  aOffset  ) 
gfxFloat gfxTextRun::GetAdvanceWidth ( PRUint32  aStart,
PRUint32  aLength,
PropertyProvider *  aProvider 
)

Computes just the advance width for a substring.

Uses GetSpacing from aBreakProvider.

PRUint32 gfxTextRun::GetAppUnitsPerDevUnit (  )  const [inline]
const PRUnichar gfxTextRun::GetChar ( PRUint32  i  )  const [inline]
const CompressedGlyph* gfxTextRun::GetCharacterGlyphs (  )  [inline]
const DetailedGlyph* gfxTextRun::GetDetailedGlyphs ( PRUint32  aCharIndex  )  [inline]
gfxFloat gfxTextRun::GetDirection (  )  const [inline]
nsExpirationState* gfxTextRun::GetExpirationState (  )  [inline]
PRUint32 gfxTextRun::GetFlags (  )  const [inline]
gfxFontGroup* gfxTextRun::GetFontGroup (  )  const [inline]
const GlyphRun* gfxTextRun::GetGlyphRuns ( PRUint32 *  aNumGlyphRuns  )  [inline]
PRUint32 gfxTextRun::GetHashCode (  )  const [inline]
PRUint32 gfxTextRun::GetLength (  )  [inline]
const gfxSkipChars& gfxTextRun::GetSkipChars (  )  const [inline]
const PRUint8* gfxTextRun::GetText8Bit (  )  const [inline]
const void* gfxTextRun::GetTextAt ( PRUint32  aIndex  )  [inline]
const PRUnichar* gfxTextRun::GetTextUnicode (  )  const [inline]
void* gfxTextRun::GetUserData (  )  const [inline]
PRUint64 gfxTextRun::GetUserFontSetGeneration (  )  [inline]
PRBool gfxTextRun::HasDetailedGlyphs (  )  [inline]
PRBool gfxTextRun::IsClusterStart ( PRUint32  aPos  )  [inline]
PRBool gfxTextRun::IsLigatureGroupStart ( PRUint32  aPos  )  [inline]
PRBool gfxTextRun::IsRightToLeft (  )  const [inline]
Metrics gfxTextRun::MeasureText ( PRUint32  aStart,
PRUint32  aLength,
gfxFont::BoundingBoxType  aBoundingBoxType,
gfxContext *  aRefContextForTightBoundingBox,
PropertyProvider *  aProvider 
)

Computes the ReflowMetrics for a substring.

Uses GetSpacing from aBreakProvider.

Parameters:
aBoundingBoxType which kind of bounding box (loose/tight)
void gfxTextRun::ResetGlyphRuns (  )  [inline]
void gfxTextRun::SanitizeGlyphRuns (  ) 
void gfxTextRun::SetContext ( gfxContext *  aContext  )  [inline]

Update the reference context.

XXX this is a hack. New text frame does not call this. Use only temporarily for old text frame.

void gfxTextRun::SetFlagBits ( PRUint32  aFlags  )  [inline]
void gfxTextRun::SetGlyphs ( PRUint32  aCharIndex,
CompressedGlyph  aGlyph,
const DetailedGlyph *  aGlyphs 
)
void gfxTextRun::SetHashCode ( PRUint32  aHash  )  [inline]
virtual PRBool gfxTextRun::SetLineBreaks ( PRUint32  aStart,
PRUint32  aLength,
PRBool  aLineBreakBefore,
PRBool  aLineBreakAfter,
gfxFloat *  aAdvanceWidthDelta,
gfxContext *  aRefContext 
) [virtual]

Clear all stored line breaks for the given range (both before and after), and then set the line-break state before aStart to aBreakBefore and after the last cluster to aBreakAfter.

We require that before and after line breaks be consistent. For clusters i and i+1, we require that if there is a break after cluster i, a break will be specified before cluster i+1. This may be temporarily violated (e.g. after reflowing line L and before reflowing line L+1); to handle these temporary violations, we say that there is a break betwen i and i+1 if a break is specified after i OR a break is specified before i+1.

This can change textrun geometry! The existence of a linebreak can affect the advance width of the cluster before the break (when kerning) or the geometry of one cluster before the break or any number of clusters after the break. (The one-cluster-before-the-break limit is somewhat arbitrary; if some scripts require breaking it, then we need to alter nsTextFrame::TrimTrailingWhitespace, perhaps drastically becase it could affect the layout of frames before it...)

We return true if glyphs or geometry changed, false otherwise. This function is virtual so that gfxTextRun subclasses can reshape properly.

Parameters:
aAdvanceWidthDelta if non-null, returns the change in advance width of the given range.
void gfxTextRun::SetMissingGlyph ( PRUint32  aCharIndex,
PRUint32  aUnicodeChar 
)
virtual PRBool gfxTextRun::SetPotentialLineBreaks ( PRUint32  aStart,
PRUint32  aLength,
PRPackedBool *  aBreakBefore,
gfxContext *  aRefContext 
) [virtual]

Set the potential linebreaks for a substring of the textrun.

These are the "allow break before" points. Initially, there are no potential linebreaks.

This can change glyphs and/or geometry! Some textruns' shapes depend on potential line breaks (e.g., title-case-converting textruns). This function is virtual so that those textruns can reshape themselves.

Returns:
true if this changed the linebreaks, false if the new line breaks are the same as the old
void gfxTextRun::SetSimpleGlyph ( PRUint32  aCharIndex,
CompressedGlyph  aGlyph 
) [inline]

Set the glyph data for a character.

aGlyphs may be null if aGlyph is a simple glyph or has no associated glyphs. If non-null the data is copied, the caller retains ownership.

void gfxTextRun::SetSpaceGlyph ( gfxFont *  aFont,
gfxContext *  aContext,
PRUint32  aCharIndex 
)
void gfxTextRun::SetUserData ( void *  aUserData  )  [inline]
void gfxTextRun::SortGlyphRuns (  ) 

Friends And Related Function Documentation

friend class FontSelector [friend]
friend class GlyphRunIterator [friend]

Member Data Documentation

const PRUnichar* gfxTextRun::mDouble
const PRUint8* gfxTextRun::mSingle
The documentation for this class was generated from the following file:
Generated on Thu Jan 27 2011 for Mozilla by  doxygen 1.7.1