/*
**********************************************************************
* Copyright (C) 2002-2011, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
*/
#ifndef __PARAGRAPHLAYOUT_H
#define __PARAGRAPHLAYOUT_H
/**
* \file
* \brief C++ API: Paragraph Layout
*/
/*
* ParagraphLayout doesn't make much sense without
* BreakIterator...
*/
#include "unicode/uscript.h"
#if ! UCONFIG_NO_BREAK_ITERATION
#include "layout/LETypes.h"
#include "layout/LEFontInstance.h"
#include "layout/LayoutEngine.h"
#include "unicode/ubidi.h"
#include "unicode/brkiter.h"
#include "layout/RunArrays.h"
U_NAMESPACE_BEGIN
/**
* ParagraphLayout.
*
* The <code>ParagraphLayout</code> object will analyze the text into runs of text in the
* same font, script and direction, and will create a <code>LayoutEngine</code> object for each run.
* The <code>LayoutEngine</code> will transform the characters into glyph codes in visual order.
*
* Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
*
*/
class U_LAYOUTEX_API ParagraphLayout : public UObject
{
public:
class VisualRun;
/**
* This class represents a single line of text in a <code>ParagraphLayout</code>. They
* can only be created by calling <code>ParagraphLayout::nextLine()</code>. Each line
* consists of multiple visual runs, represented by <code>ParagraphLayout::VisualRun</code>
* objects.
*
* @see ParagraphLayout
* @see ParagraphLayout::VisualRun
*
* @stable ICU 3.2
*/
class U_LAYOUTEX_API Line : public UObject
{
public:
/**
* The constructor is private since these objects can only be
* created by <code>ParagraphLayout</code>. However, it is the
* clients responsibility to destroy the objects, so the destructor
* is public.
*
* @stable ICU 3.2
*/
~Line();
/**
* Count the number of visual runs in the line.
*
* @return the number of visual runs.
*
* @stable ICU 3.2
*/
inline le_int32 countRuns() const;
/**
* Get the ascent of the line. This is the maximum ascent
* of all the fonts on the line.
*
* @return the ascent of the line.
*
* @stable ICU 3.2
*/
le_int32 getAscent() const;
/**
* Get the descent of the line. This is the maximum descent
* of all the fonts on the line.
*
* @return the descent of the line.
*
* @stable ICU 3.2
*/
le_int32 getDescent() const;
/**
* Get the leading of the line. This is the maximum leading
* of all the fonts on the line.
*
* @return the leading of the line.
*
* @stable ICU 3.2
*/
le_int32 getLeading() const;
/**
* Get the width of the line. This is a convenience method
* which returns the last X position of the last visual run
* in the line.
*
* @return the width of the line.
*
* @stable ICU 2.8
*/
le_int32 getWidth() const;
/**
* Get a <code>ParagraphLayout::VisualRun</code> object for a given
* visual run in the line.
*
* @param runIndex is the index of the run, in visual order.
*
* @return the <code>ParagraphLayout::VisualRun</code> object representing the
* visual run. This object is owned by the <code>Line</code> object which
* created it, and will remain valid for as long as the <code>Line</code>
* object is valid.
*
* @see ParagraphLayout::VisualRun
*
* @stable ICU 3.2
*/
const VisualRun *getVisualRun(le_int32 runIndex) const;
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
* @stable ICU 3.2
*/
static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
* @stable ICU 3.2
*/
virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
private:
/**
* The address of this static class variable serves as this class's ID
* for ICU "poor man's RTTI".
*/
static const char fgClassID;
friend class ParagraphLayout;
le_int32 fAscent;
le_int32 fDescent;
le_int32 fLeading;
le_int32 fRunCount;
le_int32 fRunCapacity;
VisualRun **fRuns;
inline Line();
inline Line(const Line &other);
inline Line &operator=(const Line & /*other*/) { return *this; };
void computeMetrics();
void append(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
};
/**
* This object represents a single visual run in a line of text in
* a paragraph. A visual run is text which is in the same font,
* script, and direction. The text is represented by an array of
* <code>LEGlyphIDs</code>, an array of (x, y) glyph positions and
* a table which maps indices into the glyph array to indices into
* the original character array which was used to create the paragraph.
*
* These objects are only created by <code>ParagraphLayout::Line</code> objects,
* so their constructors and destructors are private.
*
* @see ParagraphLayout::Line
*
* @stable ICU 3.2
*/
class U_LAYOUTEX_API VisualRun : public UObject
{
public:
/**
* Get the <code>LEFontInstance</code> object which
* represents the font of the visual run. This will always
* be a non-composite font.
*
* @return the <code>LEFontInstance</code> object which represents the
* font of the visual run.
*
* @see LEFontInstance
*
* @stable ICU 3.2
*/
inline const LEFontInstance *getFont() const;
/**
* Get the direction of the visual run.
*
* @return the direction of the run. This will be UBIDI_LTR if the
* run is left-to-right and UBIDI_RTL if the line is right-to-left.
*
* @stable ICU 3.2
*/
inline UBiDiDirection getDirection() const;
/**
* Get the number of glyphs in the visual run.
*
* @return the number of glyphs.
*
* @stable ICU 3.2
*/
inline le_int32 getGlyphCount() const;
/**
* Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
* <code>0xFFFF</code> should be ignored.
*
* @return the address of the array of glyphs for this visual run. The storage
* is owned by the <code>VisualRun</code> object and must not be deleted.
* It will remain valid as long as the <code>VisualRun</code> object is valid.
*
* @stable ICU 3.2
*/
inline const LEGlyphID *getGlyphs() const;
/**
* Get the (x, y) positions of the glyphs in the visual run. To simplify storage
* management, the x and y positions are stored in a single array with the x positions
* at even offsets in the array and the corresponding y position in the following odd offset.
* There is an extra (x, y) pair at the end of the array which represents the advance of
* the final glyph in the run.
*
* @return the address of the array of glyph positions for this visual run. The storage
* is owned by the <code>VisualRun</code> object and must not be deleted.
* It will remain valid as long as the <code>VisualRun</code> object is valid.
*
* @stable ICU 3.2
*/
inline const float *getPositions() const;
/**
* Get the glyph-to-character map for this visual run. This maps the indices into
* the glyph array to indices into the character array used to create the paragraph.
*
* @return the address of the character-to-glyph map for this visual run. The storage
* is owned by the <code>VisualRun</code> object and must not be deleted.
* It will remain valid as long as the <code>VisualRun</code> object is valid.
*
* @stable ICU 3.2
*/
inline const le_int32 *getGlyphToCharMap() const;
/**
* A convenience method which returns the ascent value for the font
* associated with this run.
*
* @return the ascent value of this run's font.
*
* @stable ICU 3.2
*/
inline le_int32 getAscent() const;
/**
* A convenience method which returns the descent value for the font
* associated with this run.
*
* @return the descent value of this run's font.
*
* @stable ICU 3.2
*/
inline le_int32 getDescent() const;
/**
* A convenience method which returns the leading value for the font
* associated with this run.
*
* @return the leading value of this run's font.
*
* @stable ICU 3.2
*/
inline le_int32 getLeading() const;
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
* @stable ICU 3.2
*/
static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
* @stable ICU 3.2
*/
virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
private:
/**
* The address of this static class variable serves as this class's ID
* for ICU "poor man's RTTI".
*/
static const char fgClassID;
const LEFontInstance *fFont;
const UBiDiDirection fDirection;
const le_int32 fGlyphCount;
const LEGlyphID *fGlyphs;
const float *fPositions;
const le_int32 *fGlyphToCharMap;
friend class Line;
inline VisualRun();
inline VisualRun(const VisualRun &other);
inline VisualRun &operator=(const VisualRun &/*other*/) { return *this; };
inline VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
~VisualRun();
};
/**
* Construct a <code>ParagraphLayout</code> object for a styled paragraph. The paragraph is specified
* as runs of text all in the same font. An <code>LEFontInstance</code> object and a limit offset
* are specified for each font run. The limit offset is the offset of the character immediately
* after the font run.
*
* Clients can optionally specify directional runs and / or script runs. If these aren't specified
* they will be computed.
*
* If any errors are encountered during construction, <code>status</code> will be set, and the object
* will be set to be empty.
*
* @param chars is an array of the characters in the paragraph
*
* @param count is the number of characters in the paragraph.
*
* @param fontRuns a pointer to a <code>FontRuns</code> object representing the font runs.
*
* @param levelRuns is a pointer to a <code>ValueRuns</code> object representing the directional levels.
* If this pointer in <code>NULL</code> the levels will be determined by running the Unicde
* Bidi algorithm.
*
* @param scriptRuns is a pointer to a <code>ValueRuns</code> object representing script runs.
* If this pointer in <code>NULL</code> the script runs will be determined using the
* Unicode code points.
*
* @param localeRuns is a pointer to a <code>LocaleRuns</code> object representing locale runs.
* The <code>Locale</code> objects are used to determind the language of the text. If this
* pointer is <code>NULL</code> the default locale will be used for all of the text.
*
* @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
*
* @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
*
* @param status will be set to any error code encountered during construction.
*
* @see ubidi.h
* @see LEFontInstance.h
* @see LayoutEngine.h
* @see RunArrays.h
*
* @stable ICU 2.8
*/
ParagraphLayout(const LEUnicode chars[], le_int32 count,
const FontRuns *fontRuns,
const ValueRuns *levelRuns,
const ValueRuns *scriptRuns,
const LocaleRuns *localeRuns,
UBiDiLevel paragraphLevel, le_bool vertical,
LEErrorCode &status);
/**
* The destructor. Virtual so that it works correctly with
* sublcasses.
*
* @stable ICU 3.2
*/
~ParagraphLayout();
// Note: the following is #if 0'd out because there's no good
// way to implement it without either calling layoutEngineFactory()
// or duplicating the logic there...
#if 0
/**
* Examine the given styled paragraph and determine if it contains any text which
* requires complex processing. (i.e. that cannot be correctly rendered by
* just mapping the characters to glyphs and rendering them in order)
*
* @param chars is an array of the characters in the paragraph
*
* @param count is the number of characters in the paragraph.
*
* @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
*
* @return <code>TRUE</code> if the paragraph contains complex text.
*
* @stable ICU 3.2
*/
static le_bool isComplex(const LEUnicode chars[], le_int32 count, const FontRuns *fontRuns);
#else
/**
* Examine the given text and determine if it contains characters in any
* script which requires complex processing to be rendered correctly.
*
* @param chars is an array of the characters in the paragraph
*
* @param count is the number of characters in the paragraph.
*
* @return <code>TRUE</code> if any of the text requires complex processing.
*
* @stable ICU 3.2
*/
static le_bool isComplex(const LEUnicode chars[], le_int32 count);
#endif
/**
* Return the resolved paragraph level. This is useful for those cases
* where the bidi analysis has determined the level based on the first
* strong character in the paragraph.
*
* @return the resolved paragraph level.
*
* @stable ICU 3.2
*/
inline UBiDiLevel getParagraphLevel();
/**
* Return the directionality of the text in the paragraph.
*
* @return <code>UBIDI_LTR</code> if the text is all left to right,
* <code>UBIDI_RTL</code> if the text is all right to left,
* or <code>UBIDI_MIXED</code> if the text has mixed direction.
*
* @stable ICU 3.2
*/
inline UBiDiDirection getTextDirection();
/**
* Return the max ascent value for all the fonts
* in the paragraph.
*
* @return the ascent value.
*
* @stable ICU 3.2
*/
virtual le_int32 getAscent() const;
/**
* Return the max descent value for all the fonts
* in the paragraph.
*
* @return the decent value.
*
* @stable ICU 3.2
*/
virtual le_int32 getDescent() const;
/**
* Return the max leading value for all the fonts
* in the paragraph.
*
* @return the leading value.
*
* @stable ICU 3.2
*/
virtual le_int32 getLeading() const;
/**
* Reset line breaking to start from the beginning of the paragraph.
*
*
* @stable ICU 3.2
*/
inline void reflow();
#ifndef U_HIDE_INTERNAL_API
/**
*
* Convenience method for determining if paragraph layout processing is complete ( i.e. there
* are no more lines left to process. )
*
* @return true if there are no more lines to be processed
*
* @internal
*/
inline le_bool isDone() const;
#endif /* U_HIDE_INTERNAL_API */
/**
* Return a <code>ParagraphLayout::Line</code> object which represents next line
* in the paragraph. The width of the line is specified each time so that it can
* be varied to support arbitrary paragraph shapes.
*
* @param width is the width of the line. If <code>width</code> is less than or equal
* to zero, a <code>ParagraphLayout::Line</code> object representing the
* rest of the paragraph will be returned.
*
* @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
* is responsible for deleting the object. Returns <code>NULL</code> if there are no
* more lines in the paragraph.
*
* @see ParagraphLayout::Line
*
* @stable ICU 3.2
*/
Line *nextLine(float width);
/**
* ICU "poor man's RTTI", returns a UClassID for this class.
*
* @stable ICU 3.2
*/
static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
/**
* ICU "poor man's RTTI", returns a UClassID for the actual class.
*
* @stable ICU 3.2
*/
virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
private:
/**
* The address of this static class variable serves as this class's ID
* for ICU "poor man's RTTI".
*/
static const char fgClassID;
struct StyleRunInfo
{
LayoutEngine *engine;
const LEFontInstance *font;
const Locale *locale;
LEGlyphID *glyphs;
float *positions;
UScriptCode script;
UBiDiLevel level;
le_int32 runBase;
le_int32 runLimit;
le_int32 glyphBase;
le_int32 glyphCount;
};
ParagraphLayout() {};
ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};
inline ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };
void computeLevels(UBiDiLevel paragraphLevel);
Line *computeVisualRuns();
void appendRun(Line *line, le_int32 run, le_int32 firstChar, le_int32 lastChar);
void computeScripts();
void computeLocales();
void computeSubFonts(const FontRuns *fontRuns, LEErrorCode &status);
void computeMetrics();
le_int32 getLanguageCode(const Locale *locale);
le_int32 getCharRun(le_int32 charIndex);
static le_bool isComplex(UScriptCode script);
le_int32 previousBreak(le_int32 charIndex);
const LEUnicode *fChars;
le_int32 fCharCount;
const FontRuns *fFontRuns;
const ValueRuns *fLevelRuns;
const ValueRuns *fScriptRuns;
const LocaleRuns *fLocaleRuns;
le_bool fVertical;
le_bool fClientLevels;
le_bool fClientScripts;
le_bool fClientLocales;
UBiDiLevel *fEmbeddingLevels;
le_int32 fAscent;
le_int32 fDescent;
le_int32 fLeading;
le_int32 *fGlyphToCharMap;
le_int32 *fCharToMinGlyphMap;
le_int32 *fCharToMaxGlyphMap;
float *fGlyphWidths;
le_int32 fGlyphCount;
UBiDi *fParaBidi;
UBiDi *fLineBidi;
le_int32 *fStyleRunLimits;
le_int32 *fStyleIndices;
StyleRunInfo *fStyleRunInfo;
le_int32 fStyleRunCount;
BreakIterator *fBreakIterator;
le_int32 fLineStart;
le_int32 fLineEnd;
le_int32 fFirstVisualRun;
le_int32 fLastVisualRun;
float fVisualRunLastX;
float fVisualRunLastY;
};
inline UBiDiLevel ParagraphLayout::getParagraphLevel()
{
return ubidi_getParaLevel(fParaBidi);
}
inline UBiDiDirection ParagraphLayout::getTextDirection()
{
return ubidi_getDirection(fParaBidi);
}
inline void ParagraphLayout::reflow()
{
fLineEnd = 0;
}
inline ParagraphLayout::Line::Line()
: UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
{
// nothing else to do
}
inline ParagraphLayout::Line::Line(const Line & /*other*/)
: UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
{
// nothing else to do
}
inline le_int32 ParagraphLayout::Line::countRuns() const
{
return fRunCount;
}
inline const LEFontInstance *ParagraphLayout::VisualRun::getFont() const
{
return fFont;
}
inline UBiDiDirection ParagraphLayout::VisualRun::getDirection() const
{
return fDirection;
}
inline le_int32 ParagraphLayout::VisualRun::getGlyphCount() const
{
return fGlyphCount;
}
inline const LEGlyphID *ParagraphLayout::VisualRun::getGlyphs() const
{
return fGlyphs;
}
inline const float *ParagraphLayout::VisualRun::getPositions() const
{
return fPositions;
}
inline const le_int32 *ParagraphLayout::VisualRun::getGlyphToCharMap() const
{
return fGlyphToCharMap;
}
inline le_int32 ParagraphLayout::VisualRun::getAscent() const
{
return fFont->getAscent();
}
inline le_int32 ParagraphLayout::VisualRun::getDescent() const
{
return fFont->getDescent();
}
inline le_int32 ParagraphLayout::VisualRun::getLeading() const
{
return fFont->getLeading();
}
inline ParagraphLayout::VisualRun::VisualRun()
: UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
{
// nothing
}
inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &/*other*/)
: UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
{
// nothing
}
inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[])
: fFont(font), fDirection(direction), fGlyphCount(glyphCount),
fGlyphs(glyphs), fPositions(positions), fGlyphToCharMap(glyphToCharMap)
{
// nothing else needs to be done!
}
U_NAMESPACE_END
#endif
#endif