icuSources/layoutex/layout/playout.h

   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