1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 **********************************************************************
5 * Copyright (C) 2002-2014, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 **********************************************************************
10 #ifndef __PARAGRAPHLAYOUT_H
12 #define __PARAGRAPHLAYOUT_H
16 * \brief C++ API: Paragraph Layout
20 * ParagraphLayout doesn't make much sense without
23 #include "unicode/uscript.h"
24 #if ! UCONFIG_NO_BREAK_ITERATION
26 #include "layout/LETypes.h"
27 #include "layout/LEFontInstance.h"
28 #include "layout/LayoutEngine.h"
29 #include "unicode/ubidi.h"
30 #include "unicode/brkiter.h"
32 #include "layout/RunArrays.h"
39 * The <code>ParagraphLayout</code> object will analyze the text into runs of text in the
40 * same font, script and direction, and will create a <code>LayoutEngine</code> object for each run.
41 * The <code>LayoutEngine</code> will transform the characters into glyph codes in visual order.
43 * Clients can use this to break a paragraph into lines, and to display the glyphs in each line.
45 * Note that {@link icu::LayoutEngine} is deprecated, but this class is not.
46 * You may use this class with the HarfBuzz icu-le-hb wrapper,
47 * see http://www.freedesktop.org/wiki/Software/HarfBuzz/
49 * See http://userguide.icu-project.org/layoutengine for special build instructions.
51 * @see icu::LayoutEngine
53 class U_LAYOUTEX_API ParagraphLayout : public UObject
59 * This class represents a single line of text in a <code>ParagraphLayout</code>. They
60 * can only be created by calling <code>ParagraphLayout::nextLine()</code>. Each line
61 * consists of multiple visual runs, represented by <code>ParagraphLayout::VisualRun</code>
64 * @see ParagraphLayout
65 * @see ParagraphLayout::VisualRun
69 class U_LAYOUTEX_API Line : public UObject
73 * The constructor is private since these objects can only be
74 * created by <code>ParagraphLayout</code>. However, it is the
75 * clients responsibility to destroy the objects, so the destructor
83 * Count the number of visual runs in the line.
85 * @return the number of visual runs.
89 inline le_int32 countRuns() const;
92 * Get the ascent of the line. This is the maximum ascent
93 * of all the fonts on the line.
95 * @return the ascent of the line.
99 le_int32 getAscent() const;
102 * Get the descent of the line. This is the maximum descent
103 * of all the fonts on the line.
105 * @return the descent of the line.
109 le_int32 getDescent() const;
112 * Get the leading of the line. This is the maximum leading
113 * of all the fonts on the line.
115 * @return the leading of the line.
119 le_int32 getLeading() const;
122 * Get the width of the line. This is a convenience method
123 * which returns the last X position of the last visual run
126 * @return the width of the line.
130 le_int32 getWidth() const;
133 * Get a <code>ParagraphLayout::VisualRun</code> object for a given
134 * visual run in the line.
136 * @param runIndex is the index of the run, in visual order.
138 * @return the <code>ParagraphLayout::VisualRun</code> object representing the
139 * visual run. This object is owned by the <code>Line</code> object which
140 * created it, and will remain valid for as long as the <code>Line</code>
143 * @see ParagraphLayout::VisualRun
147 const VisualRun *getVisualRun(le_int32 runIndex) const;
150 * ICU "poor man's RTTI", returns a UClassID for this class.
154 static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
157 * ICU "poor man's RTTI", returns a UClassID for the actual class.
161 virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
166 * The address of this static class variable serves as this class's ID
167 * for ICU "poor man's RTTI".
169 static const char fgClassID;
171 friend class ParagraphLayout;
178 le_int32 fRunCapacity;
183 inline Line(const Line &other);
184 inline Line &operator=(const Line & /*other*/) { return *this; };
186 void computeMetrics();
188 void append(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
189 const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
193 * This object represents a single visual run in a line of text in
194 * a paragraph. A visual run is text which is in the same font,
195 * script, and direction. The text is represented by an array of
196 * <code>LEGlyphIDs</code>, an array of (x, y) glyph positions and
197 * a table which maps indices into the glyph array to indices into
198 * the original character array which was used to create the paragraph.
200 * These objects are only created by <code>ParagraphLayout::Line</code> objects,
201 * so their constructors and destructors are private.
203 * @see ParagraphLayout::Line
207 class U_LAYOUTEX_API VisualRun : public UObject
211 * Get the <code>LEFontInstance</code> object which
212 * represents the font of the visual run. This will always
213 * be a non-composite font.
215 * @return the <code>LEFontInstance</code> object which represents the
216 * font of the visual run.
218 * @see LEFontInstance
222 inline const LEFontInstance *getFont() const;
225 * Get the direction of the visual run.
227 * @return the direction of the run. This will be UBIDI_LTR if the
228 * run is left-to-right and UBIDI_RTL if the line is right-to-left.
232 inline UBiDiDirection getDirection() const;
235 * Get the number of glyphs in the visual run.
237 * @return the number of glyphs.
241 inline le_int32 getGlyphCount() const;
244 * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
245 * <code>0xFFFF</code> should be ignored.
247 * @return the address of the array of glyphs for this visual run. The storage
248 * is owned by the <code>VisualRun</code> object and must not be deleted.
249 * It will remain valid as long as the <code>VisualRun</code> object is valid.
253 inline const LEGlyphID *getGlyphs() const;
256 * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
257 * management, the x and y positions are stored in a single array with the x positions
258 * at even offsets in the array and the corresponding y position in the following odd offset.
259 * There is an extra (x, y) pair at the end of the array which represents the advance of
260 * the final glyph in the run.
262 * @return the address of the array of glyph positions for this visual run. The storage
263 * is owned by the <code>VisualRun</code> object and must not be deleted.
264 * It will remain valid as long as the <code>VisualRun</code> object is valid.
268 inline const float *getPositions() const;
271 * Get the glyph-to-character map for this visual run. This maps the indices into
272 * the glyph array to indices into the character array used to create the paragraph.
274 * @return the address of the character-to-glyph map for this visual run. The storage
275 * is owned by the <code>VisualRun</code> object and must not be deleted.
276 * It will remain valid as long as the <code>VisualRun</code> object is valid.
280 inline const le_int32 *getGlyphToCharMap() const;
283 * A convenience method which returns the ascent value for the font
284 * associated with this run.
286 * @return the ascent value of this run's font.
290 inline le_int32 getAscent() const;
293 * A convenience method which returns the descent value for the font
294 * associated with this run.
296 * @return the descent value of this run's font.
300 inline le_int32 getDescent() const;
303 * A convenience method which returns the leading value for the font
304 * associated with this run.
306 * @return the leading value of this run's font.
310 inline le_int32 getLeading() const;
313 * ICU "poor man's RTTI", returns a UClassID for this class.
317 static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
320 * ICU "poor man's RTTI", returns a UClassID for the actual class.
324 virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
329 * The address of this static class variable serves as this class's ID
330 * for ICU "poor man's RTTI".
332 static const char fgClassID;
334 const LEFontInstance *fFont;
335 const UBiDiDirection fDirection;
337 const le_int32 fGlyphCount;
339 const LEGlyphID *fGlyphs;
340 const float *fPositions;
341 const le_int32 *fGlyphToCharMap;
346 inline VisualRun(const VisualRun &other);
347 inline VisualRun &operator=(const VisualRun &/*other*/) { return *this; };
349 inline VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
350 const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[]);
356 * Construct a <code>ParagraphLayout</code> object for a styled paragraph. The paragraph is specified
357 * as runs of text all in the same font. An <code>LEFontInstance</code> object and a limit offset
358 * are specified for each font run. The limit offset is the offset of the character immediately
359 * after the font run.
361 * Clients can optionally specify directional runs and / or script runs. If these aren't specified
362 * they will be computed.
364 * If any errors are encountered during construction, <code>status</code> will be set, and the object
365 * will be set to be empty.
367 * @param chars is an array of the characters in the paragraph
369 * @param count is the number of characters in the paragraph.
371 * @param fontRuns a pointer to a <code>FontRuns</code> object representing the font runs.
373 * @param levelRuns is a pointer to a <code>ValueRuns</code> object representing the directional levels.
374 * If this pointer in <code>NULL</code> the levels will be determined by running the Unicde
377 * @param scriptRuns is a pointer to a <code>ValueRuns</code> object representing script runs.
378 * If this pointer in <code>NULL</code> the script runs will be determined using the
379 * Unicode code points.
381 * @param localeRuns is a pointer to a <code>LocaleRuns</code> object representing locale runs.
382 * The <code>Locale</code> objects are used to determind the language of the text. If this
383 * pointer is <code>NULL</code> the default locale will be used for all of the text.
385 * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
387 * @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
389 * @param status will be set to any error code encountered during construction.
392 * @see LEFontInstance.h
393 * @see LayoutEngine.h
398 ParagraphLayout(const LEUnicode chars[], le_int32 count,
399 const FontRuns *fontRuns,
400 const ValueRuns *levelRuns,
401 const ValueRuns *scriptRuns,
402 const LocaleRuns *localeRuns,
403 UBiDiLevel paragraphLevel, le_bool vertical,
404 LEErrorCode &status);
407 * The destructor. Virtual so that it works correctly with
414 // Note: the following is #if 0'd out because there's no good
415 // way to implement it without either calling layoutEngineFactory()
416 // or duplicating the logic there...
419 * Examine the given styled paragraph and determine if it contains any text which
420 * requires complex processing. (i.e. that cannot be correctly rendered by
421 * just mapping the characters to glyphs and rendering them in order)
423 * @param chars is an array of the characters in the paragraph
425 * @param count is the number of characters in the paragraph.
427 * @param fontRuns is a pointer to a <code>FontRuns</code> object representing the font runs.
429 * @return <code>TRUE</code> if the paragraph contains complex text.
433 static le_bool isComplex(const LEUnicode chars[], le_int32 count, const FontRuns *fontRuns);
436 * Examine the given text and determine if it contains characters in any
437 * script which requires complex processing to be rendered correctly.
439 * @param chars is an array of the characters in the paragraph
441 * @param count is the number of characters in the paragraph.
443 * @return <code>TRUE</code> if any of the text requires complex processing.
447 static le_bool isComplex(const LEUnicode chars[], le_int32 count);
452 * Return the resolved paragraph level. This is useful for those cases
453 * where the bidi analysis has determined the level based on the first
454 * strong character in the paragraph.
456 * @return the resolved paragraph level.
460 inline UBiDiLevel getParagraphLevel();
463 * Return the directionality of the text in the paragraph.
465 * @return <code>UBIDI_LTR</code> if the text is all left to right,
466 * <code>UBIDI_RTL</code> if the text is all right to left,
467 * or <code>UBIDI_MIXED</code> if the text has mixed direction.
471 inline UBiDiDirection getTextDirection();
474 * Return the max ascent value for all the fonts
477 * @return the ascent value.
481 virtual le_int32 getAscent() const;
484 * Return the max descent value for all the fonts
487 * @return the decent value.
491 virtual le_int32 getDescent() const;
494 * Return the max leading value for all the fonts
497 * @return the leading value.
501 virtual le_int32 getLeading() const;
504 * Reset line breaking to start from the beginning of the paragraph.
509 inline void reflow();
511 #ifndef U_HIDE_INTERNAL_API
514 * Convenience method for determining if paragraph layout processing is complete ( i.e. there
515 * are no more lines left to process. )
517 * @return true if there are no more lines to be processed
521 inline le_bool isDone() const;
522 #endif /* U_HIDE_INTERNAL_API */
525 * Return a <code>ParagraphLayout::Line</code> object which represents next line
526 * in the paragraph. The width of the line is specified each time so that it can
527 * be varied to support arbitrary paragraph shapes.
529 * @param width is the width of the line. If <code>width</code> is less than or equal
530 * to zero, a <code>ParagraphLayout::Line</code> object representing the
531 * rest of the paragraph will be returned.
533 * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
534 * is responsible for deleting the object. Returns <code>NULL</code> if there are no
535 * more lines in the paragraph.
537 * @see ParagraphLayout::Line
541 Line *nextLine(float width);
544 * ICU "poor man's RTTI", returns a UClassID for this class.
548 static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
551 * ICU "poor man's RTTI", returns a UClassID for the actual class.
555 virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
561 * The address of this static class variable serves as this class's ID
562 * for ICU "poor man's RTTI".
564 static const char fgClassID;
568 LayoutEngine *engine;
569 const LEFontInstance *font;
570 const Locale *locale;
581 ParagraphLayout() {};
582 ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};
583 inline ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };
585 void computeLevels(UBiDiLevel paragraphLevel);
587 Line *computeVisualRuns();
588 void appendRun(Line *line, le_int32 run, le_int32 firstChar, le_int32 lastChar);
590 void computeScripts();
592 void computeLocales();
594 void computeSubFonts(const FontRuns *fontRuns, LEErrorCode &status);
596 void computeMetrics();
598 le_int32 getLanguageCode(const Locale *locale);
600 le_int32 getCharRun(le_int32 charIndex);
602 static le_bool isComplex(UScriptCode script);
604 le_int32 previousBreak(le_int32 charIndex);
607 const LEUnicode *fChars;
610 const FontRuns *fFontRuns;
611 const ValueRuns *fLevelRuns;
612 const ValueRuns *fScriptRuns;
613 const LocaleRuns *fLocaleRuns;
616 le_bool fClientLevels;
617 le_bool fClientScripts;
618 le_bool fClientLocales;
620 UBiDiLevel *fEmbeddingLevels;
626 le_int32 *fGlyphToCharMap;
627 le_int32 *fCharToMinGlyphMap;
628 le_int32 *fCharToMaxGlyphMap;
630 le_int32 fGlyphCount;
635 le_int32 *fStyleRunLimits;
636 le_int32 *fStyleIndices;
637 StyleRunInfo *fStyleRunInfo;
638 le_int32 fStyleRunCount;
640 BreakIterator *fBreakIterator;
644 le_int32 fFirstVisualRun;
645 le_int32 fLastVisualRun;
646 float fVisualRunLastX;
647 float fVisualRunLastY;
650 inline UBiDiLevel ParagraphLayout::getParagraphLevel()
652 return ubidi_getParaLevel(fParaBidi);
655 inline UBiDiDirection ParagraphLayout::getTextDirection()
657 return ubidi_getDirection(fParaBidi);
660 inline void ParagraphLayout::reflow()
665 inline ParagraphLayout::Line::Line()
666 : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
668 // nothing else to do
671 inline ParagraphLayout::Line::Line(const Line & /*other*/)
672 : UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
674 // nothing else to do
677 inline le_int32 ParagraphLayout::Line::countRuns() const
682 inline const LEFontInstance *ParagraphLayout::VisualRun::getFont() const
687 inline UBiDiDirection ParagraphLayout::VisualRun::getDirection() const
692 inline le_int32 ParagraphLayout::VisualRun::getGlyphCount() const
697 inline const LEGlyphID *ParagraphLayout::VisualRun::getGlyphs() const
702 inline const float *ParagraphLayout::VisualRun::getPositions() const
707 inline const le_int32 *ParagraphLayout::VisualRun::getGlyphToCharMap() const
709 return fGlyphToCharMap;
712 inline le_int32 ParagraphLayout::VisualRun::getAscent() const
714 return fFont->getAscent();
717 inline le_int32 ParagraphLayout::VisualRun::getDescent() const
719 return fFont->getDescent();
722 inline le_int32 ParagraphLayout::VisualRun::getLeading() const
724 return fFont->getLeading();
727 inline ParagraphLayout::VisualRun::VisualRun()
728 : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
733 inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &/*other*/)
734 : UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
739 inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
740 const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[])
741 : fFont(font), fDirection(direction), fGlyphCount(glyphCount),
742 fGlyphs(glyphs), fPositions(positions), fGlyphToCharMap(glyphToCharMap)
744 // nothing else needs to be done!