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