2
**********************************************************************
3
* Copyright (C) 2002-2010, 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();
503
* Convenience method for determining if paragraph layout processing is complete ( i.e. there
504
* are no more lines left to process. )
506
* @return true if there are no more lines to be processed
510
inline le_bool isDone() const;
513
* Return a <code>ParagraphLayout::Line</code> object which represents next line
514
* in the paragraph. The width of the line is specified each time so that it can
515
* be varied to support arbitrary paragraph shapes.
517
* @param width is the width of the line. If <code>width</code> is less than or equal
518
* to zero, a <code>ParagraphLayout::Line</code> object representing the
519
* rest of the paragraph will be returned.
521
* @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
522
* is responsible for deleting the object. Returns <code>NULL</code> if there are no
523
* more lines in the paragraph.
525
* @see ParagraphLayout::Line
529
Line *nextLine(float width);
532
* ICU "poor man's RTTI", returns a UClassID for this class.
536
static inline UClassID getStaticClassID() { return (UClassID)&fgClassID; }
539
* ICU "poor man's RTTI", returns a UClassID for the actual class.
543
virtual inline UClassID getDynamicClassID() const { return getStaticClassID(); }
549
* The address of this static class variable serves as this class's ID
550
* for ICU "poor man's RTTI".
552
static const char fgClassID;
556
LayoutEngine *engine;
557
const LEFontInstance *font;
558
const Locale *locale;
569
ParagraphLayout() {};
570
ParagraphLayout(const ParagraphLayout & /*other*/) : UObject( ){};
571
inline ParagraphLayout &operator=(const ParagraphLayout & /*other*/) { return *this; };
573
void computeLevels(UBiDiLevel paragraphLevel);
575
Line *computeVisualRuns();
576
void appendRun(Line *line, le_int32 run, le_int32 firstChar, le_int32 lastChar);
578
void computeScripts();
580
void computeLocales();
582
void computeSubFonts(const FontRuns *fontRuns, LEErrorCode &status);
584
void computeMetrics();
586
le_int32 getLanguageCode(const Locale *locale);
588
le_int32 getCharRun(le_int32 charIndex);
590
static le_bool isComplex(UScriptCode script);
592
le_int32 previousBreak(le_int32 charIndex);
595
const LEUnicode *fChars;
598
const FontRuns *fFontRuns;
599
const ValueRuns *fLevelRuns;
600
const ValueRuns *fScriptRuns;
601
const LocaleRuns *fLocaleRuns;
604
le_bool fClientLevels;
605
le_bool fClientScripts;
606
le_bool fClientLocales;
608
UBiDiLevel *fEmbeddingLevels;
614
le_int32 *fGlyphToCharMap;
615
le_int32 *fCharToMinGlyphMap;
616
le_int32 *fCharToMaxGlyphMap;
618
le_int32 fGlyphCount;
623
le_int32 *fStyleRunLimits;
624
le_int32 *fStyleIndices;
625
StyleRunInfo *fStyleRunInfo;
626
le_int32 fStyleRunCount;
628
BreakIterator *fBreakIterator;
632
le_int32 fFirstVisualRun;
633
le_int32 fLastVisualRun;
634
float fVisualRunLastX;
635
float fVisualRunLastY;
638
inline UBiDiLevel ParagraphLayout::getParagraphLevel()
640
return ubidi_getParaLevel(fParaBidi);
643
inline UBiDiDirection ParagraphLayout::getTextDirection()
645
return ubidi_getDirection(fParaBidi);
648
inline void ParagraphLayout::reflow()
653
inline ParagraphLayout::Line::Line()
654
: UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
656
// nothing else to do
659
inline ParagraphLayout::Line::Line(const Line & /*other*/)
660
: UObject(), fAscent(0), fDescent(0), fLeading(0), fRunCount(0), fRunCapacity(0), fRuns(NULL)
662
// nothing else to do
665
inline le_int32 ParagraphLayout::Line::countRuns() const
670
inline const LEFontInstance *ParagraphLayout::VisualRun::getFont() const
675
inline UBiDiDirection ParagraphLayout::VisualRun::getDirection() const
680
inline le_int32 ParagraphLayout::VisualRun::getGlyphCount() const
685
inline const LEGlyphID *ParagraphLayout::VisualRun::getGlyphs() const
690
inline const float *ParagraphLayout::VisualRun::getPositions() const
695
inline const le_int32 *ParagraphLayout::VisualRun::getGlyphToCharMap() const
697
return fGlyphToCharMap;
700
inline le_int32 ParagraphLayout::VisualRun::getAscent() const
702
return fFont->getAscent();
705
inline le_int32 ParagraphLayout::VisualRun::getDescent() const
707
return fFont->getDescent();
710
inline le_int32 ParagraphLayout::VisualRun::getLeading() const
712
return fFont->getLeading();
715
inline ParagraphLayout::VisualRun::VisualRun()
716
: UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
721
inline ParagraphLayout::VisualRun::VisualRun(const VisualRun &/*other*/)
722
: UObject(), fFont(NULL), fDirection(UBIDI_LTR), fGlyphCount(0), fGlyphs(NULL), fPositions(NULL), fGlyphToCharMap(NULL)
727
inline ParagraphLayout::VisualRun::VisualRun(const LEFontInstance *font, UBiDiDirection direction, le_int32 glyphCount,
728
const LEGlyphID glyphs[], const float positions[], const le_int32 glyphToCharMap[])
729
: fFont(font), fDirection(direction), fGlyphCount(glyphCount),
730
fGlyphs(glyphs), fPositions(positions), fGlyphToCharMap(glyphToCharMap)
732
// nothing else needs to be done!