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 */
35typedef void pl_paragraph;
36
37/**
38 * The opaque type for a line in a paragraph layout.
39 *
40 * @internal
41 */
42typedef void pl_line;
43
44/**
45 * The opaque type for a visual run in a line.
46 *
47 * @internal
48 */
49typedef 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 */
96U_INTERNAL pl_paragraph * U_EXPORT2
97pl_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 */
116U_INTERNAL void U_EXPORT2
117pl_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
132U_INTERNAL le_bool U_EXPORT2
133pl_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 */
147U_INTERNAL UBiDiLevel U_EXPORT2
148pl_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 */
161U_INTERNAL UBiDiDirection U_EXPORT2
162pl_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 */
179U_INTERNAL le_int32 U_EXPORT2
180pl_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 */
192U_INTERNAL le_int32 U_EXPORT2
193pl_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 */
205U_INTERNAL le_int32 U_EXPORT2
206pl_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 */
215U_INTERNAL void U_EXPORT2
216pl_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 */
236U_INTERNAL pl_line * U_EXPORT2
237pl_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 */
248U_INTERNAL void U_EXPORT2
249pl_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 */
260U_INTERNAL le_int32 U_EXPORT2
261pl_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 */
273U_INTERNAL le_int32 U_EXPORT2
274pl_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 */
286U_INTERNAL le_int32 U_EXPORT2
287pl_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 */
299U_INTERNAL le_int32 U_EXPORT2
300pl_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 */
313U_INTERNAL le_int32 U_EXPORT2
314pl_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 */
332U_INTERNAL const pl_visualRun * U_EXPORT2
333pl_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 */
349U_INTERNAL const le_font * U_EXPORT2
350pl_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 */
362U_INTERNAL UBiDiDirection U_EXPORT2
363pl_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 */
374U_INTERNAL le_int32 U_EXPORT2
375pl_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 */
389U_INTERNAL const LEGlyphID * U_EXPORT2
390pl_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 */
407U_INTERNAL const float * U_EXPORT2
408pl_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 */
422U_INTERNAL const le_int32 * U_EXPORT2
423pl_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 */
435U_INTERNAL le_int32 U_EXPORT2
436pl_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 */
448U_INTERNAL le_int32 U_EXPORT2
449pl_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 */
461U_INTERNAL le_int32 U_EXPORT2
462pl_getVisualRunLeading(const pl_visualRun *run);
463
464#endif  /* U_HIDE_INTERNAL_API */
465#endif
466#endif
467