2 **********************************************************************
3 * Copyright (C) 2002-2011, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
8 #ifndef __PARAGRAPHLAYOUT_H
10 #define __PARAGRAPHLAYOUT_H
14 * \brief C++ API: Paragraph Layout
18 * ParagraphLayout doesn't make much sense without
21 #include "unicode/uscript.h"
22 #if ! UCONFIG_NO_BREAK_ITERATION
24 #include "layout/LETypes.h"
25 #include "layout/LEFontInstance.h"
26 #include "layout/LayoutEngine.h"
27 #include "unicode/ubidi.h"
28 #include "unicode/brkiter.h"
30 #include "layout/RunArrays.h"
37 * The <code>ParagraphLayout</code> object will analyze the text into runs of text in the
38 * same font, script and direction, and will create a <code>LayoutEngine</code> object for each run.
39 * The <code>LayoutEngine</code> will transform the characters into glyph codes in visual order.
41 * Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
44 class U_LAYOUTEX_API ParagraphLayout
: public UObject
50 * This class represents a single line of text in a <code>ParagraphLayout</code>. They
51 * can only be created by calling <code>ParagraphLayout::nextLine()</code>. Each line
52 * consists of multiple visual runs, represented by <code>ParagraphLayout::VisualRun</code>
55 * @see ParagraphLayout
56 * @see ParagraphLayout::VisualRun
60 class U_LAYOUTEX_API Line
: public UObject
64 * The constructor is private since these objects can only be
65 * created by <code>ParagraphLayout</code>. However, it is the
66 * clients responsibility to destroy the objects, so the destructor
74 * Count the number of visual runs in the line.
76 * @return the number of visual runs.
80 inline le_int32
countRuns() const;
83 * Get the ascent of the line. This is the maximum ascent
84 * of all the fonts on the line.
86 * @return the ascent of the line.
90 le_int32
getAscent() const;
93 * Get the descent of the line. This is the maximum descent
94 * of all the fonts on the line.
96 * @return the descent of the line.
100 le_int32
getDescent() const;
103 * Get the leading of the line. This is the maximum leading
104 * of all the fonts on the line.
106 * @return the leading of the line.
110 le_int32
getLeading() const;
113 * Get the width of the line. This is a convenience method
114 * which returns the last X position of the last visual run
117 * @return the width of the line.
121 le_int32
getWidth() const;
124 * Get a <code>ParagraphLayout::VisualRun</code> object for a given
125 * visual run in the line.
127 * @param runIndex is the index of the run, in visual order.
129 * @return the <code>ParagraphLayout::VisualRun</code> object representing the
130 * visual run. This object is owned by the <code>Line</code> object which
131 * created it, and will remain valid for as long as the <code>Line</code>
134 * @see ParagraphLayout::VisualRun
138 const VisualRun
*getVisualRun(le_int32 runIndex
) const;
141 * ICU "poor man's RTTI", returns a UClassID for this class.
145 static inline UClassID
getStaticClassID() { return (UClassID
)&fgClassID
; }
148 * ICU "poor man's RTTI", returns a UClassID for the actual class.
152 virtual inline UClassID
getDynamicClassID() const { return getStaticClassID(); }
157 * The address of this static class variable serves as this class's ID
158 * for ICU "poor man's RTTI".
160 static const char fgClassID
;
162 friend class ParagraphLayout
;
169 le_int32 fRunCapacity
;
174 inline Line(const Line
&other
);
175 inline Line
&operator=(const Line
& /*other*/) { return *this; };
177 void computeMetrics();
179 void append(const LEFontInstance
*font
, UBiDiDirection direction
, le_int32 glyphCount
,
180 const LEGlyphID glyphs
[], const float positions
[], const le_int32 glyphToCharMap
[]);
184 * This object represents a single visual run in a line of text in
185 * a paragraph. A visual run is text which is in the same font,
186 * script, and direction. The text is represented by an array of
187 * <code>LEGlyphIDs</code>, an array of (x, y) glyph positions and
188 * a table which maps indices into the glyph array to indices into
189 * the original character array which was used to create the paragraph.
191 * These objects are only created by <code>ParagraphLayout::Line</code> objects,
192 * so their constructors and destructors are private.
194 * @see ParagraphLayout::Line
198 class U_LAYOUTEX_API VisualRun
: public UObject
202 * Get the <code>LEFontInstance</code> object which
203 * represents the font of the visual run. This will always
204 * be a non-composite font.
206 * @return the <code>LEFontInstance</code> object which represents the
207 * font of the visual run.
209 * @see LEFontInstance
213 inline const LEFontInstance
*getFont() const;
216 * Get the direction of the visual run.
218 * @return the direction of the run. This will be UBIDI_LTR if the
219 * run is left-to-right and UBIDI_RTL if the line is right-to-left.
223 inline UBiDiDirection
getDirection() const;
226 * Get the number of glyphs in the visual run.
228 * @return the number of glyphs.
232 inline le_int32
getGlyphCount() const;
235 * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
236 * <code>0xFFFF</code> should be ignored.
238 * @return the address of the array of glyphs for this visual run. The storage
239 * is owned by the <code>VisualRun</code> object and must not be deleted.
240 * It will remain valid as long as the <code>VisualRun</code> object is valid.
244 inline const LEGlyphID
*getGlyphs() const;
247 * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
248 * management, the x and y positions are stored in a single array with the x positions
249 * at even offsets in the array and the corresponding y position in the following odd offset.
250 * There is an extra (x, y) pair at the end of the array which represents the advance of
251 * the final glyph in the run.
253 * @return the address of the array of glyph positions for this visual run. The storage
254 * is owned by the <code>VisualRun</code> object and must not be deleted.
255 * It will remain valid as long as the <code>VisualRun</code> object is valid.
259 inline const float *getPositions() const;
262 * Get the glyph-to-character map for this visual run. This maps the indices into
263 * the glyph array to indices into the character array used to create the paragraph.
265 * @return the address of the character-to-glyph map for this visual run. The storage
266 * is owned by the <code>VisualRun</code> object and must not be deleted.
267 * It will remain valid as long as the <code>VisualRun</code> object is valid.
271 inline const le_int32
*getGlyphToCharMap() const;
274 * A convenience method which returns the ascent value for the font
275 * associated with this run.
277 * @return the ascent value of this run's font.
281 inline le_int32
getAscent() const;
284 * A convenience method which returns the descent value for the font
285 * associated with this run.
287 * @return the descent value of this run's font.
291 inline le_int32
getDescent() const;
294 * A convenience method which returns the leading value for the font
295 * associated with this run.
297 * @return the leading value of this run's font.
301 inline le_int32
getLeading() const;
304 * ICU "poor man's RTTI", returns a UClassID for this class.
308 static inline UClassID
getStaticClassID() { return (UClassID
)&fgClassID
; }
311 * ICU "poor man's RTTI", returns a UClassID for the actual class.
315 virtual inline UClassID
getDynamicClassID() const { return getStaticClassID(); }
320 * The address of this static class variable serves as this class's ID
321 * for ICU "poor man's RTTI".
323 static const char fgClassID
;
325 const LEFontInstance
*fFont
;
326 const UBiDiDirection fDirection
;
328 const le_int32 fGlyphCount
;
330 const LEGlyphID
*fGlyphs
;
331 const float *fPositions
;
332 const le_int32
*fGlyphToCharMap
;
337 inline VisualRun(const VisualRun
&other
);
338 inline VisualRun
&operator=(const VisualRun
&/*other*/) { return *this; };
340 inline VisualRun(const LEFontInstance
*font
, UBiDiDirection direction
, le_int32 glyphCount
,
341 const LEGlyphID glyphs
[], const float positions
[], const le_int32 glyphToCharMap
[]);
347 * Construct a <code>ParagraphLayout</code> object for a styled paragraph. The paragraph is specified
348 * as runs of text all in the same font. An <code>LEFontInstance</code> object and a limit offset
349 * are specified for each font run. The limit offset is the offset of the character immediately
350 * after the font run.
352 * Clients can optionally specify directional runs and / or script runs. If these aren't specified
353 * they will be computed.
355 * If any errors are encountered during construction, <code>status</code> will be set, and the object
356 * will be set to be empty.
358 * @param chars is an array of the characters in the paragraph
360 * @param count is the number of characters in the paragraph.
362 * @param fontRuns a pointer to a <code>FontRuns</code> object representing the font runs.
364 * @param levelRuns is a pointer to a <code>ValueRuns</code> object representing the directional levels.
365 * If this pointer in <code>NULL</code> the levels will be determined by running the Unicde
368 * @param scriptRuns is a pointer to a <code>ValueRuns</code> object representing script runs.
369 * If this pointer in <code>NULL</code> the script runs will be determined using the
370 * Unicode code points.
372 * @param localeRuns is a pointer to a <code>LocaleRuns</code> object representing locale runs.
373 * The <code>Locale</code> objects are used to determind the language of the text. If this
374 * pointer is <code>NULL</code> the default locale will be used for all of the text.
376 * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
378 * @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
380 * @param status will be set to any error code encountered during construction.
383 * @see LEFontInstance.h
384 * @see LayoutEngine.h
389 ParagraphLayout(const LEUnicode chars
[], le_int32 count
,
390 const FontRuns
*fontRuns
,
391 const ValueRuns
*levelRuns
,
392 const ValueRuns
*scriptRuns
,
393 const LocaleRuns
*localeRuns
,
394 UBiDiLevel paragraphLevel
, le_bool vertical
,
395 LEErrorCode
&status
);
398 * The destructor. Virtual so that it works correctly with
405 // Note: the following is #if 0'd out because there's no good
406 // way to implement it without either calling layoutEngineFactory()
407 // or duplicating the logic there...
410 * Examine the given styled paragraph and determine if it contains any text which
411 * requires complex processing. (i.e. that cannot be correctly rendered by
412 * just mapping the characters to glyphs and rendering them in order)
414 * @param chars is an array of the characters in the paragraph
416 * @param count is the number of characters in the paragraph.
418 * @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
420 * @return <code>TRUE</code> if the paragraph contains complex text.
424 static le_bool
isComplex(const LEUnicode chars
[], le_int32 count
, const FontRuns
*fontRuns
);
427 * Examine the given text and determine if it contains characters in any
428 * script which requires complex processing to be rendered correctly.
430 * @param chars is an array of the characters in the paragraph
432 * @param count is the number of characters in the paragraph.
434 * @return <code>TRUE</code> if any of the text requires complex processing.
438 static le_bool
isComplex(const LEUnicode chars
[], le_int32 count
);
443 * Return the resolved paragraph level. This is useful for those cases
444 * where the bidi analysis has determined the level based on the first
445 * strong character in the paragraph.
447 * @return the resolved paragraph level.
451 inline UBiDiLevel
getParagraphLevel();
454 * Return the directionality of the text in the paragraph.
456 * @return <code>UBIDI_LTR</code> if the text is all left to right,
457 * <code>UBIDI_RTL</code> if the text is all right to left,
458 * or <code>UBIDI_MIXED</code> if the text has mixed direction.
462 inline UBiDiDirection
getTextDirection();
465 * Return the max ascent value for all the fonts
468 * @return the ascent value.
472 virtual le_int32
getAscent() const;
475 * Return the max descent value for all the fonts
478 * @return the decent value.
482 virtual le_int32
getDescent() const;
485 * Return the max leading value for all the fonts
488 * @return the leading value.
492 virtual le_int32
getLeading() const;
495 * Reset line breaking to start from the beginning of the paragraph.
500 inline void reflow();
502 #ifndef U_HIDE_INTERNAL_API
505 * Convenience method for determining if paragraph layout processing is complete ( i.e. there
506 * are no more lines left to process. )
508 * @return true if there are no more lines to be processed
512 inline le_bool
isDone() const;
513 #endif /* U_HIDE_INTERNAL_API */
516 * Return a <code>ParagraphLayout::Line</code> object which represents next line
517 * in the paragraph. The width of the line is specified each time so that it can
518 * be varied to support arbitrary paragraph shapes.
520 * @param width is the width of the line. If <code>width</code> is less than or equal
521 * to zero, a <code>ParagraphLayout::Line</code> object representing the
522 * rest of the paragraph will be returned.
524 * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
525 * is responsible for deleting the object. Returns <code>NULL</code> if there are no
526 * more lines in the paragraph.
528 * @see ParagraphLayout::Line
532 Line
*nextLine(float width
);
535 * ICU "poor man's RTTI", returns a UClassID for this class.
539 static inline UClassID
getStaticClassID() { return (UClassID
)&fgClassID
; }
542 * ICU "poor man's RTTI", returns a UClassID for the actual class.
546 virtual inline UClassID
getDynamicClassID() const { return getStaticClassID(); }
552 * The address of this static class variable serves as this class's ID
553 * for ICU "poor man's RTTI".
555 static const char fgClassID
;
559 LayoutEngine
*engine
;
560 const LEFontInstance
*font
;
561 const Locale
*locale
;
572 ParagraphLayout() {};
573 ParagraphLayout(const ParagraphLayout
& /*other*/) : UObject( ){};
574 inline ParagraphLayout
&operator=(const ParagraphLayout
& /*other*/) { return *this; };
576 void computeLevels(UBiDiLevel paragraphLevel
);
578 Line
*computeVisualRuns();
579 void appendRun(Line
*line
, le_int32 run
, le_int32 firstChar
, le_int32 lastChar
);
581 void computeScripts();
583 void computeLocales();
585 void computeSubFonts(const FontRuns
*fontRuns
, LEErrorCode
&status
);
587 void computeMetrics();
589 le_int32
getLanguageCode(const Locale
*locale
);
591 le_int32
getCharRun(le_int32 charIndex
);
593 static le_bool
isComplex(UScriptCode script
);
595 le_int32
previousBreak(le_int32 charIndex
);
598 const LEUnicode
*fChars
;
601 const FontRuns
*fFontRuns
;
602 const ValueRuns
*fLevelRuns
;
603 const ValueRuns
*fScriptRuns
;
604 const LocaleRuns
*fLocaleRuns
;
607 le_bool fClientLevels
;
608 le_bool fClientScripts
;
609 le_bool fClientLocales
;
611 UBiDiLevel
*fEmbeddingLevels
;
617 le_int32
*fGlyphToCharMap
;
618 le_int32
*fCharToMinGlyphMap
;
619 le_int32
*fCharToMaxGlyphMap
;
621 le_int32 fGlyphCount
;
626 le_int32
*fStyleRunLimits
;
627 le_int32
*fStyleIndices
;
628 StyleRunInfo
*fStyleRunInfo
;
629 le_int32 fStyleRunCount
;
631 BreakIterator
*fBreakIterator
;
635 le_int32 fFirstVisualRun
;
636 le_int32 fLastVisualRun
;
637 float fVisualRunLastX
;
638 float fVisualRunLastY
;
641 inline UBiDiLevel
ParagraphLayout::getParagraphLevel()
643 return ubidi_getParaLevel(fParaBidi
);
646 inline UBiDiDirection
ParagraphLayout::getTextDirection()
648 return ubidi_getDirection(fParaBidi
);
651 inline void ParagraphLayout::reflow()
656 inline ParagraphLayout::Line::Line()
657 : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL
)
659 // nothing else to do
662 inline ParagraphLayout::Line::Line(const Line
& /*other*/)
663 : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL
)
665 // nothing else to do
668 inline le_int32
ParagraphLayout::Line::countRuns() const
673 inline const LEFontInstance
*ParagraphLayout::VisualRun::getFont() const
678 inline UBiDiDirection
ParagraphLayout::VisualRun::getDirection() const
683 inline le_int32
ParagraphLayout::VisualRun::getGlyphCount() const
688 inline const LEGlyphID
*ParagraphLayout::VisualRun::getGlyphs() const
693 inline const float *ParagraphLayout::VisualRun::getPositions() const
698 inline const le_int32
*ParagraphLayout::VisualRun::getGlyphToCharMap() const
700 return fGlyphToCharMap
;
703 inline le_int32
ParagraphLayout::VisualRun::getAscent() const
705 return fFont
->getAscent();
708 inline le_int32
ParagraphLayout::VisualRun::getDescent() const
710 return fFont
->getDescent();
713 inline le_int32
ParagraphLayout::VisualRun::getLeading() const
715 return fFont
->getLeading();
718 inline ParagraphLayout::VisualRun::VisualRun()
719 : UObject(), fFont(NULL
), fDirection(UBIDI_LTR
), fGlyphCount(0), fGlyphs(NULL
), fPositions(NULL
), fGlyphToCharMap(NULL
)
724 inline ParagraphLayout::VisualRun::VisualRun(const VisualRun
&/*other*/)
725 : UObject(), fFont(NULL
), fDirection(UBIDI_LTR
), fGlyphCount(0), fGlyphs(NULL
), fPositions(NULL
), fGlyphToCharMap(NULL
)
730 inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance
*font
, UBiDiDirection direction
, le_int32 glyphCount
,
731 const LEGlyphID glyphs
[], const float positions
[], const le_int32 glyphToCharMap
[])
732 : fFont(font
), fDirection(direction
), fGlyphCount(glyphCount
),
733 fGlyphs(glyphs
), fPositions(positions
), fGlyphToCharMap(glyphToCharMap
)
735 // nothing else needs to be done!