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 467