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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI le_int32 U_EXPORT2 464 pl_getVisualRunLeading(const pl_visualRun *run); 465 466 #endif /* U_HIDE_INTERNAL_API */ 467 #endif 468 #endif 469