]> git.saurik.com Git - apple/icu.git/blob - icuSources/layoutex/layout/playout.h
ICU-62107.0.1.tar.gz
[apple/icu.git] / icuSources / layoutex / layout / playout.h
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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL 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_INTERNAL le_int32 U_EXPORT2
464 pl_getVisualRunLeading(const pl_visualRun *run);
465
466 #endif /* U_HIDE_INTERNAL_API */
467 #endif
468 #endif