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 */
34typedef void pl_paragraph;
35
36/**
37 * The opaque type for a line in a paragraph layout.
38 *
39 * @internal
40 */
41typedef void pl_line;
42
43/**
44 * The opaque type for a visual run in a line.
45 *
46 * @internal
47 */
48typedef 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 */
95U_INTERNAL pl_paragraph * U_EXPORT2
96pl_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 */
115U_INTERNAL void U_EXPORT2
116pl_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
131U_INTERNAL le_bool U_EXPORT2
132pl_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 */
146U_INTERNAL UBiDiLevel U_EXPORT2
147pl_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 */
160U_INTERNAL UBiDiDirection U_EXPORT2
161pl_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 */
178U_INTERNAL le_int32 U_EXPORT2
179pl_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 */
191U_INTERNAL le_int32 U_EXPORT2
192pl_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 */
204U_INTERNAL le_int32 U_EXPORT2
205pl_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 */
214U_INTERNAL void U_EXPORT2
215pl_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 */
235U_INTERNAL pl_line * U_EXPORT2
236pl_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 */
247U_INTERNAL void U_EXPORT2
248pl_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 */
259U_INTERNAL le_int32 U_EXPORT2
260pl_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 */
272U_INTERNAL le_int32 U_EXPORT2
273pl_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 */
285U_INTERNAL le_int32 U_EXPORT2
286pl_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 */
298U_INTERNAL le_int32 U_EXPORT2
299pl_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 */
312U_INTERNAL le_int32 U_EXPORT2
313pl_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 */
331U_INTERNAL const pl_visualRun * U_EXPORT2
332pl_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 */
348U_INTERNAL const le_font * U_EXPORT2
349pl_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 */
361U_INTERNAL UBiDiDirection U_EXPORT2
362pl_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 */
373U_INTERNAL le_int32 U_EXPORT2
374pl_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 */
388U_INTERNAL const LEGlyphID * U_EXPORT2
389pl_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 */
406U_INTERNAL const float * U_EXPORT2
407pl_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 */
421U_INTERNAL const le_int32 * U_EXPORT2
422pl_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 */
434U_INTERNAL le_int32 U_EXPORT2
435pl_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 */
447U_INTERNAL le_int32 U_EXPORT2
448pl_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 */
460U_INTERNAL le_int32 U_EXPORT2
461pl_getVisualRunLeading(const pl_visualRun *run);
462
463#endif
464#endif
465