icuSources/layoutex/layout/playout.h

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