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 465