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 Unicode 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 determine 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 * Return 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 ascent value. 173 * 174 * @internal 175 */ 176 U_CAPI le_int32 U_EXPORT2 177 pl_getAscent(const pl_paragraph *paragraph); 178 179 /** 180 * Return the max descent value for all the fonts 181 * in the paragraph. 182 * 183 * @param paragraph the <code>pl_paragraph</code> 184 * 185 * @return the decent value. 186 * 187 * @internal 188 */ 189 U_CAPI le_int32 U_EXPORT2 190 pl_getDescent(const pl_paragraph *paragraph); 191 192 /** 193 * Return the max leading value for all the fonts 194 * in the paragraph. 195 * 196 * @param paragraph the <code>pl_paragraph</code> 197 * 198 * @return the leading value. 199 * 200 * @internal 201 */ 202 U_CAPI le_int32 U_EXPORT2 203 pl_getLeading(const pl_paragraph *paragraph); 204 205 /** 206 * Reset line breaking to start from the beginning of the paragraph. 207 * 208 * @param paragraph the <code>pl_paragraph</code> 209 * 210 * @internal 211 */ 212 U_CAPI void U_EXPORT2 213 pl_reflow(pl_paragraph *paragraph); 214 215 /** 216 * Return a <code>pl_line</code> object which represents next line 217 * in the paragraph. The width of the line is specified each time so that it can 218 * be varied to support arbitrary paragraph shapes. 219 * 220 * @param paragraph the <code>pl_paragraph</code> 221 * @param width is the width of the line. If <code>width</code> is less than or equal 222 * to zero, a <code>ParagraphLayout::Line</code> object representing the 223 * rest of the paragraph will be returned. 224 * 225 * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller 226 * is responsible for deleting the object. Returns <code>NULL</code> if there are no 227 * more lines in the paragraph. 228 * 229 * @see pl_line 230 * 231 * @internal 232 */ 233 U_CAPI pl_line * U_EXPORT2 234 pl_nextLine(pl_paragraph *paragraph, float width); 235 236 /** 237 * Close the given line object. Line objects are created 238 * by <code>pl_nextLine</code> but it is the client's responsibility 239 * to close them by calling this routine. 240 * 241 * @param line the <code>pl_line</code> object to close. 242 * 243 * @internal 244 */ 245 U_CAPI void U_EXPORT2 246 pl_closeLine(pl_line *line); 247 248 /** 249 * Count the number of visual runs in the line. 250 * 251 * @param line the <code>pl_line</code> object. 252 * 253 * @return the number of visual runs. 254 * 255 * @internal 256 */ 257 U_CAPI le_int32 U_EXPORT2 258 pl_countLineRuns(const pl_line *line); 259 260 /** 261 * Get the ascent of the line. This is the maximum ascent 262 * of all the fonts on the line. 263 * 264 * @param line the <code>pl_line</code> object. 265 * 266 * @return the ascent of the line. 267 * 268 * @internal 269 */ 270 U_CAPI le_int32 U_EXPORT2 271 pl_getLineAscent(const pl_line *line); 272 273 /** 274 * Get the descent of the line. This is the maximum descent 275 * of all the fonts on the line. 276 * 277 * @param line the <code>pl_line</code> object. 278 * 279 * @return the descent of the line. 280 * 281 * @internal 282 */ 283 U_CAPI le_int32 U_EXPORT2 284 pl_getLineDescent(const pl_line *line); 285 286 /** 287 * Get the leading of the line. This is the maximum leading 288 * of all the fonts on the line. 289 * 290 * @param line the <code>pl_line</code> object. 291 * 292 * @return the leading of the line. 293 * 294 * @internal 295 */ 296 U_CAPI le_int32 U_EXPORT2 297 pl_getLineLeading(const pl_line *line); 298 299 /** 300 * Get the width of the line. This is a convenience method 301 * which returns the last X position of the last visual run 302 * in the line. 303 * 304 * @param line the <code>pl_line</code> object. 305 * 306 * @return the width of the line. 307 * 308 * @internal 309 */ 310 U_CAPI le_int32 U_EXPORT2 311 pl_getLineWidth(const pl_line *line); 312 313 /** 314 * Get a <code>ParagraphLayout::VisualRun</code> object for a given 315 * visual run in the line. 316 * 317 * @param line the <code>pl_line</code> object. 318 * @param runIndex is the index of the run, in visual order. 319 * 320 * @return the <code>pl_visualRun</code> object representing the 321 * visual run. This object is owned by the <code>pl_line</code> object which 322 * created it, and will remain valid for as long as the <code>pl_line</code> 323 * object is valid. 324 * 325 * @see pl_visualRun 326 * 327 * @internal 328 */ 329 U_CAPI const pl_visualRun * U_EXPORT2 330 pl_getLineVisualRun(const pl_line *line, le_int32 runIndex); 331 332 /** 333 * Get the <code>le_font</code> object which 334 * represents the font of the visual run. This will always 335 * be a non-composite font. 336 * 337 * @param run the <code>pl_visualRun</code> object. 338 * 339 * @return the <code>le_font</code> object which represents the 340 * font of the visual run. 341 * 342 * @see le_font 343 * 344 * @internal 345 */ 346 U_CAPI const le_font * U_EXPORT2 347 pl_getVisualRunFont(const pl_visualRun *run); 348 349 /** 350 * Get the direction of the visual run. 351 * 352 * @param run the <code>pl_visualRun</code> object. 353 * 354 * @return the direction of the run. This will be <code>UBIDI_LTR</code> if the 355 * run is left-to-right and <code>UBIDI_RTL</code> if the line is right-to-left. 356 * 357 * @internal 358 */ 359 U_CAPI UBiDiDirection U_EXPORT2 360 pl_getVisualRunDirection(const pl_visualRun *run); 361 362 /** 363 * Get the number of glyphs in the visual run. 364 * 365 * @param run the <code>pl_visualRun</code> object. 366 * 367 * @return the number of glyphs. 368 * 369 * @internal 370 */ 371 U_CAPI le_int32 U_EXPORT2 372 pl_getVisualRunGlyphCount(const pl_visualRun *run); 373 374 /** 375 * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and 376 * <code>0xFFFF</code> should be ignored. 377 * 378 * @param run the <code>pl_visualRun</code> object. 379 * 380 * @return the address of the array of glyphs for this visual run. The storage 381 * is owned by the <code>pl_visualRun</code> object and must not be deleted. 382 * It will remain valid as long as the <code>pl_visualRun</code> object is valid. 383 * 384 * @internal 385 */ 386 U_CAPI const LEGlyphID * U_EXPORT2 387 pl_getVisualRunGlyphs(const pl_visualRun *run); 388 389 /** 390 * Get the (x, y) positions of the glyphs in the visual run. To simplify storage 391 * management, the x and y positions are stored in a single array with the x positions 392 * at even offsets in the array and the corresponding y position in the following odd offset. 393 * There is an extra (x, y) pair at the end of the array which represents the advance of 394 * the final glyph in the run. 395 * 396 * @param run the <code>pl_visualRun</code> object. 397 * 398 * @return the address of the array of glyph positions for this visual run. The storage 399 * is owned by the <code>pl_visualRun</code> object and must not be deleted. 400 * It will remain valid as long as the <code>pl_visualRun</code> object is valid. 401 * 402 * @internal 403 */ 404 U_CAPI const float * U_EXPORT2 405 pl_getVisualRunPositions(const pl_visualRun *run); 406 407 /** 408 * Get the glyph-to-character map for this visual run. This maps the indices into 409 * the glyph array to indices into the character array used to create the paragraph. 410 * 411 * @param run the <code>pl_visualRun</code> object. 412 * 413 * @return the address of the character-to-glyph map for this visual run. The storage 414 * is owned by the <code>pl_visualRun</code> object and must not be deleted. 415 * It will remain valid as long as the <code>pl_visualRun</code> object is valid. 416 * 417 * @internal 418 */ 419 U_CAPI const le_int32 * U_EXPORT2 420 pl_getVisualRunGlyphToCharMap(const pl_visualRun *run); 421 422 /** 423 * A convenience method which returns the ascent value for the font 424 * associated with this run. 425 * 426 * @param run the <code>pl_visualRun</code> object. 427 * 428 * @return the ascent value of this run's font. 429 * 430 * @internal 431 */ 432 U_CAPI le_int32 U_EXPORT2 433 pl_getVisualRunAscent(const pl_visualRun *run); 434 435 /** 436 * A convenience method which returns the descent value for the font 437 * associated with this run. 438 * 439 * @param run the <code>pl_visualRun</code> object. 440 * 441 * @return the descent value of this run's font. 442 * 443 * @internal 444 */ 445 U_CAPI le_int32 U_EXPORT2 446 pl_getVisualRunDescent(const pl_visualRun *run); 447 448 /** 449 * A convenience method which returns the leading value for the font 450 * associated with this run. 451 * 452 * @param run the <code>pl_visualRun</code> object. 453 * 454 * @return the leading value of this run's font. 455 * 456 * @internal 457 */ 458 U_CAPI le_int32 U_EXPORT2 459 pl_getVisualRunLeading(const pl_visualRun *run); 460 461 #endif /* U_HIDE_INTERNAL_API */ 462 #endif 463 #endif 464