Home | History | Annotate | Download | only in layout
      1 //  2016 and later: Unicode, Inc. and others.
      2 // License & terms of use: http://www.unicode.org/copyright.html
      3 /*
      4  *
      5  * (C) Copyright IBM Corp. 1998-2011 - All Rights Reserved
      6  *
      7  */
      8 
      9 #ifndef __PLAYOUT_H
     10 #define __PLAYOUT_H
     11 
     12 /*
     13  * ParagraphLayout doesn't make much sense without
     14  * BreakIterator...
     15  */
     16 #include "unicode/ubidi.h"
     17 #if ! UCONFIG_NO_BREAK_ITERATION
     18 #ifndef U_HIDE_INTERNAL_API
     19 
     20 #include "layout/LETypes.h"
     21 #include "plruns.h"
     22 
     23 /**
     24  * \file
     25  * \brief C API for paragraph layout.
     26  *
     27  * This is a technology preview. The API may
     28  * change significantly.
     29  *
     30  */
     31 
     32 /**
     33  * The opaque type for a paragraph layout.
     34  *
     35  * @internal
     36  */
     37 typedef void pl_paragraph;
     38 
     39 /**
     40  * The opaque type for a line in a paragraph layout.
     41  *
     42  * @internal
     43  */
     44 typedef void pl_line;
     45 
     46 /**
     47  * The opaque type for a visual run in a line.
     48  *
     49  * @internal
     50  */
     51 typedef void pl_visualRun;
     52 
     53 /**
     54  * Construct a <code>ParagraphLayout</code> object for a styled paragraph. The paragraph is specified
     55  * as runs of text all in the same font. An <code>LEFontInstance</code> object and a limit offset
     56  * are specified for each font run. The limit offset is the offset of the character immediately
     57  * after the font run.
     58  *
     59  * Clients can optionally specify directional runs and / or script runs. If these aren't specified
     60  * they will be computed.
     61  *
     62  * If any errors are encountered during construction, <code>status</code> will be set, and the object
     63  * will be set to be empty.
     64  *
     65  * @param chars is an array of the characters in the paragraph
     66  *
     67  * @param count is the number of characters in the paragraph.
     68  *
     69  * @param fontRuns a pointer to a <code>pl_fontRuns</code> object representing the font runs.
     70  *
     71  * @param levelRuns is a pointer to a <code>pl_valueRuns</code> object representing the directional levels.
     72  *        If this pointer in <code>NULL</code> the levels will be determined by running the Unicde
     73  *        Bidi algorithm.
     74  *
     75  * @param scriptRuns is a pointer to a <code>pl_valueRuns</code> object representing script runs.
     76  *        If this pointer in <code>NULL</code> the script runs will be determined using the
     77  *        Unicode code points.
     78  *
     79  * @param localeRuns is a pointer to a <code>pl_localeRuns</code> object representing locale runs.
     80  *        The <code>Locale</code> objects are used to determind the language of the text. If this
     81  *        pointer is <code>NULL</code> the default locale will be used for all of the text.
     82  *
     83  * @param paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
     84  *
     85  * @param vertical is <code>TRUE</code> if the paragraph should be set vertically.
     86  *
     87  * @param status will be set to any error code encountered during construction.
     88  *
     89  * @return a pointer to the newly created <code>pl_paragraph</code> object. The object
     90  *         will remain valid until <code>pl_close</code> is called.
     91  *
     92  * @see ubidi.h
     93  * @see longine.h
     94  * @see plruns.h
     95  *
     96  * @internal
     97  */
     98 U_INTERNAL pl_paragraph * U_EXPORT2
     99 pl_create(const LEUnicode chars[],
    100           le_int32 count,
    101           const pl_fontRuns *fontRuns,
    102           const pl_valueRuns *levelRuns,
    103           const pl_valueRuns *scriptRuns,
    104           const pl_localeRuns *localeRuns,
    105           UBiDiLevel paragraphLevel,
    106           le_bool vertical,
    107           LEErrorCode *status);
    108 
    109 /**
    110  * Close the given paragraph layout object.
    111  *
    112  * @param paragraph the <code>pl_paragraph</code> object to be
    113  *                  closed. Once this routine returns the object
    114  *                  can no longer be referenced
    115  *
    116  * @internal
    117  */
    118 U_INTERNAL void U_EXPORT2
    119 pl_close(pl_paragraph *paragraph);
    120 
    121 /**
    122  * Examine the given text and determine if it contains characters in any
    123  * script which requires complex processing to be rendered correctly.
    124  *
    125  * @param chars is an array of the characters in the paragraph
    126  *
    127  * @param count is the number of characters in the paragraph.
    128  *
    129  * @return <code>TRUE</code> if any of the text requires complex processing.
    130  *
    131  * @internal
    132  */
    133 
    134 U_INTERNAL le_bool U_EXPORT2
    135 pl_isComplex(const LEUnicode chars[],
    136           le_int32 count);
    137 
    138 /**
    139  * Return the resolved paragraph level. This is useful for those cases
    140  * where the bidi analysis has determined the level based on the first
    141  * strong character in the paragraph.
    142  *
    143  * @param paragraph the <code>pl_paragraph</code>
    144  *
    145  * @return the resolved paragraph level.
    146  *
    147  * @internal
    148  */
    149 U_INTERNAL UBiDiLevel U_EXPORT2
    150 pl_getParagraphLevel(pl_paragraph *paragraph);
    151 
    152 /**
    153  * Return the directionality of the text in the paragraph.
    154  *
    155  * @param paragraph the <code>pl_paragraph</code>
    156  *
    157  * @return <code>UBIDI_LTR</code> if the text is all left to right,
    158  *         <code>UBIDI_RTL</code> if the text is all right to left,
    159  *         or <code>UBIDI_MIXED</code> if the text has mixed direction.
    160  *
    161  * @internal
    162  */
    163 U_INTERNAL UBiDiDirection U_EXPORT2
    164 pl_getTextDirection(pl_paragraph *paragraph);
    165 
    166 /**
    167  * Get the max ascent value for all the fonts
    168  * in the paragraph.
    169  *
    170  * @param paragraph the <code>pl_paragraph</code>
    171  *
    172  * Return the max ascent value for all the fonts
    173  * in the paragraph.
    174  *
    175  * @param paragraph the <code>pl_paragraph</code>
    176  *
    177  * @return the ascent value.
    178  *
    179  * @internal
    180  */
    181 U_INTERNAL le_int32 U_EXPORT2
    182 pl_getAscent(const pl_paragraph *paragraph);
    183 
    184 /**
    185  * Return the max descent value for all the fonts
    186  * in the paragraph.
    187  *
    188  * @param paragraph the <code>pl_paragraph</code>
    189  *
    190  * @return the decent value.
    191  *
    192  * @internal
    193  */
    194 U_INTERNAL le_int32 U_EXPORT2
    195 pl_getDescent(const pl_paragraph *paragraph);
    196 
    197 /**
    198  * Return the max leading value for all the fonts
    199  * in the paragraph.
    200  *
    201  * @param paragraph the <code>pl_paragraph</code>
    202  *
    203  * @return the leading value.
    204  *
    205  * @internal
    206  */
    207 U_INTERNAL le_int32 U_EXPORT2
    208 pl_getLeading(const pl_paragraph *paragraph);
    209 
    210 /**
    211  * Reset line breaking to start from the beginning of the paragraph.
    212  *
    213  * @param paragraph the <code>pl_paragraph</code>
    214  *
    215  * @internal
    216  */
    217 U_INTERNAL void U_EXPORT2
    218 pl_reflow(pl_paragraph *paragraph);
    219 
    220 /**
    221  * Return a <code>pl_line</code> object which represents next line
    222  * in the paragraph. The width of the line is specified each time so that it can
    223  * be varied to support arbitrary paragraph shapes.
    224  *
    225  * @param paragraph the <code>pl_paragraph</code>
    226  * @param width is the width of the line. If <code>width</code> is less than or equal
    227  *              to zero, a <code>ParagraphLayout::Line</code> object representing the
    228  *              rest of the paragraph will be returned.
    229  *
    230  * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
    231  *         is responsible for deleting the object. Returns <code>NULL</code> if there are no
    232  *         more lines in the paragraph.
    233  *
    234  * @see pl_line
    235  *
    236  * @internal
    237  */
    238 U_INTERNAL pl_line * U_EXPORT2
    239 pl_nextLine(pl_paragraph *paragraph, float width);
    240 
    241 /**
    242  * Close the given line object. Line objects are created
    243  * by <code>pl_nextLine</code> but it is the client's responsibility
    244  * to close them by calling this routine.
    245  *
    246  * @param line the <code>pl_line</code> object to close.
    247  *
    248  * @internal
    249  */
    250 U_INTERNAL void U_EXPORT2
    251 pl_closeLine(pl_line *line);
    252 
    253 /**
    254  * Count the number of visual runs in the line.
    255  *
    256  * @param line the <code>pl_line</code> object.
    257  *
    258  * @return the number of visual runs.
    259  *
    260  * @internal
    261  */
    262 U_INTERNAL le_int32 U_EXPORT2
    263 pl_countLineRuns(const pl_line *line);
    264 
    265 /**
    266  * Get the ascent of the line. This is the maximum ascent
    267  * of all the fonts on the line.
    268  *
    269  * @param line the <code>pl_line</code> object.
    270  *
    271  * @return the ascent of the line.
    272  *
    273  * @internal
    274  */
    275 U_INTERNAL le_int32 U_EXPORT2
    276 pl_getLineAscent(const pl_line *line);
    277 
    278 /**
    279  * Get the descent of the line. This is the maximum descent
    280  * of all the fonts on the line.
    281  *
    282  * @param line the <code>pl_line</code> object.
    283  *
    284  * @return the descent of the line.
    285  *
    286  * @internal
    287  */
    288 U_INTERNAL le_int32 U_EXPORT2
    289 pl_getLineDescent(const pl_line *line);
    290 
    291 /**
    292  * Get the leading of the line. This is the maximum leading
    293  * of all the fonts on the line.
    294  *
    295  * @param line the <code>pl_line</code> object.
    296  *
    297  * @return the leading of the line.
    298  *
    299  * @internal
    300  */
    301 U_INTERNAL le_int32 U_EXPORT2
    302 pl_getLineLeading(const pl_line *line);
    303 
    304 /**
    305  * Get the width of the line. This is a convenience method
    306  * which returns the last X position of the last visual run
    307  * in the line.
    308  *
    309  * @param line the <code>pl_line</code> object.
    310  *
    311  * @return the width of the line.
    312  *
    313  * @internal
    314  */
    315 U_INTERNAL le_int32 U_EXPORT2
    316 pl_getLineWidth(const pl_line *line);
    317 
    318 /**
    319  * Get a <code>ParagraphLayout::VisualRun</code> object for a given
    320  * visual run in the line.
    321  *
    322  * @param line the <code>pl_line</code> object.
    323  * @param runIndex is the index of the run, in visual order.
    324  *
    325  * @return the <code>pl_visualRun</code> object representing the
    326  *         visual run. This object is owned by the <code>pl_line</code> object which
    327  *         created it, and will remain valid for as long as the <code>pl_line</code>
    328  *         object is valid.
    329  *
    330  * @see pl_visualRun
    331  *
    332  * @internal
    333  */
    334 U_INTERNAL const pl_visualRun * U_EXPORT2
    335 pl_getLineVisualRun(const pl_line *line, le_int32 runIndex);
    336 
    337 /**
    338  * Get the <code>le_font</code> object which
    339  * represents the font of the visual run. This will always
    340  * be a non-composite font.
    341  *
    342  * @param run the <code>pl_visualRun</code> object.
    343  *
    344  * @return the <code>le_font</code> object which represents the
    345  *         font of the visual run.
    346  *
    347  * @see le_font
    348  *
    349  * @internal
    350  */
    351 U_INTERNAL const le_font * U_EXPORT2
    352 pl_getVisualRunFont(const pl_visualRun *run);
    353 
    354 /**
    355  * Get the direction of the visual run.
    356  *
    357  * @param run the <code>pl_visualRun</code> object.
    358  *
    359  * @return the direction of the run. This will be <code>UBIDI_LTR</code> if the
    360  *         run is left-to-right and <code>UBIDI_RTL</code> if the line is right-to-left.
    361  *
    362  * @internal
    363  */
    364 U_INTERNAL UBiDiDirection U_EXPORT2
    365 pl_getVisualRunDirection(const pl_visualRun *run);
    366 
    367 /**
    368  * Get the number of glyphs in the visual run.
    369  *
    370  * @param run the <code>pl_visualRun</code> object.
    371  *
    372  * @return the number of glyphs.
    373  *
    374  * @internal
    375  */
    376 U_INTERNAL le_int32 U_EXPORT2
    377 pl_getVisualRunGlyphCount(const pl_visualRun *run);
    378 
    379 /**
    380  * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
    381  * <code>0xFFFF</code> should be ignored.
    382  *
    383  * @param run the <code>pl_visualRun</code> object.
    384  *
    385  * @return the address of the array of glyphs for this visual run. The storage
    386  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
    387  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
    388  *
    389  * @internal
    390  */
    391 U_INTERNAL const LEGlyphID * U_EXPORT2
    392 pl_getVisualRunGlyphs(const pl_visualRun *run);
    393 
    394 /**
    395  * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
    396  * management, the x and y positions are stored in a single array with the x positions
    397  * at even offsets in the array and the corresponding y position in the following odd offset.
    398  * There is an extra (x, y) pair at the end of the array which represents the advance of
    399  * the final glyph in the run.
    400  *
    401  * @param run the <code>pl_visualRun</code> object.
    402  *
    403  * @return the address of the array of glyph positions for this visual run. The storage
    404  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
    405  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
    406  *
    407  * @internal
    408  */
    409 U_INTERNAL const float * U_EXPORT2
    410 pl_getVisualRunPositions(const pl_visualRun *run);
    411 
    412 /**
    413  * Get the glyph-to-character map for this visual run. This maps the indices into
    414  * the glyph array to indices into the character array used to create the paragraph.
    415  *
    416  * @param run the <code>pl_visualRun</code> object.
    417  *
    418  * @return the address of the character-to-glyph map for this visual run. The storage
    419  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
    420  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
    421  *
    422  * @internal
    423  */
    424 U_INTERNAL const le_int32 * U_EXPORT2
    425 pl_getVisualRunGlyphToCharMap(const pl_visualRun *run);
    426 
    427 /**
    428  * A convenience method which returns the ascent value for the font
    429  * associated with this run.
    430  *
    431  * @param run the <code>pl_visualRun</code> object.
    432  *
    433  * @return the ascent value of this run's font.
    434  *
    435  * @internal
    436  */
    437 U_INTERNAL le_int32 U_EXPORT2
    438 pl_getVisualRunAscent(const pl_visualRun *run);
    439 
    440 /**
    441  * A convenience method which returns the descent value for the font
    442  * associated with this run.
    443  *
    444  * @param run the <code>pl_visualRun</code> object.
    445  *
    446  * @return the descent value of this run's font.
    447  *
    448  * @internal
    449  */
    450 U_INTERNAL le_int32 U_EXPORT2
    451 pl_getVisualRunDescent(const pl_visualRun *run);
    452 
    453 /**
    454  * A convenience method which returns the leading value for the font
    455  * associated with this run.
    456  *
    457  * @param run the <code>pl_visualRun</code> object.
    458  *
    459  * @return the leading value of this run's font.
    460  *
    461  * @internal
    462  */
    463 U_INTERNAL le_int32 U_EXPORT2
    464 pl_getVisualRunLeading(const pl_visualRun *run);
    465 
    466 #endif  /* U_HIDE_INTERNAL_API */
    467 #endif
    468 #endif
    469