icuSources/layoutex/layout/playout.h

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