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 Unicode
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 determine 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI UBiDiDirection U_EXPORT2
164 pl_getTextDirection(pl_paragraph *paragraph);
165 
166 /**
167  * Return 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 ascent value.
173  *
174  * @internal
175  */
176 U_CAPI le_int32 U_EXPORT2
177 pl_getAscent(const pl_paragraph *paragraph);
178 
179 /**
180  * Return the max descent value for all the fonts
181  * in the paragraph.
182  *
183  * @param paragraph the <code>pl_paragraph</code>
184  *
185  * @return the decent value.
186  *
187  * @internal
188  */
189 U_CAPI le_int32 U_EXPORT2
190 pl_getDescent(const pl_paragraph *paragraph);
191 
192 /**
193  * Return the max leading value for all the fonts
194  * in the paragraph.
195  *
196  * @param paragraph the <code>pl_paragraph</code>
197  *
198  * @return the leading value.
199  *
200  * @internal
201  */
202 U_CAPI le_int32 U_EXPORT2
203 pl_getLeading(const pl_paragraph *paragraph);
204 
205 /**
206  * Reset line breaking to start from the beginning of the paragraph.
207  *
208  * @param paragraph the <code>pl_paragraph</code>
209  *
210  * @internal
211  */
212 U_CAPI void U_EXPORT2
213 pl_reflow(pl_paragraph *paragraph);
214 
215 /**
216  * Return a <code>pl_line</code> object which represents next line
217  * in the paragraph. The width of the line is specified each time so that it can
218  * be varied to support arbitrary paragraph shapes.
219  *
220  * @param paragraph the <code>pl_paragraph</code>
221  * @param width is the width of the line. If <code>width</code> is less than or equal
222  *              to zero, a <code>ParagraphLayout::Line</code> object representing the
223  *              rest of the paragraph will be returned.
224  *
225  * @return a <code>ParagraphLayout::Line</code> object which represents the line. The caller
226  *         is responsible for deleting the object. Returns <code>NULL</code> if there are no
227  *         more lines in the paragraph.
228  *
229  * @see pl_line
230  *
231  * @internal
232  */
233 U_CAPI pl_line * U_EXPORT2
234 pl_nextLine(pl_paragraph *paragraph, float width);
235 
236 /**
237  * Close the given line object. Line objects are created
238  * by <code>pl_nextLine</code> but it is the client's responsibility
239  * to close them by calling this routine.
240  *
241  * @param line the <code>pl_line</code> object to close.
242  *
243  * @internal
244  */
245 U_CAPI void U_EXPORT2
246 pl_closeLine(pl_line *line);
247 
248 /**
249  * Count the number of visual runs in the line.
250  *
251  * @param line the <code>pl_line</code> object.
252  *
253  * @return the number of visual runs.
254  *
255  * @internal
256  */
257 U_CAPI le_int32 U_EXPORT2
258 pl_countLineRuns(const pl_line *line);
259 
260 /**
261  * Get the ascent of the line. This is the maximum ascent
262  * of all the fonts on the line.
263  *
264  * @param line the <code>pl_line</code> object.
265  *
266  * @return the ascent of the line.
267  *
268  * @internal
269  */
270 U_CAPI le_int32 U_EXPORT2
271 pl_getLineAscent(const pl_line *line);
272 
273 /**
274  * Get the descent of the line. This is the maximum descent
275  * of all the fonts on the line.
276  *
277  * @param line the <code>pl_line</code> object.
278  *
279  * @return the descent of the line.
280  *
281  * @internal
282  */
283 U_CAPI le_int32 U_EXPORT2
284 pl_getLineDescent(const pl_line *line);
285 
286 /**
287  * Get the leading of the line. This is the maximum leading
288  * of all the fonts on the line.
289  *
290  * @param line the <code>pl_line</code> object.
291  *
292  * @return the leading of the line.
293  *
294  * @internal
295  */
296 U_CAPI le_int32 U_EXPORT2
297 pl_getLineLeading(const pl_line *line);
298 
299 /**
300  * Get the width of the line. This is a convenience method
301  * which returns the last X position of the last visual run
302  * in the line.
303  *
304  * @param line the <code>pl_line</code> object.
305  *
306  * @return the width of the line.
307  *
308  * @internal
309  */
310 U_CAPI le_int32 U_EXPORT2
311 pl_getLineWidth(const pl_line *line);
312 
313 /**
314  * Get a <code>ParagraphLayout::VisualRun</code> object for a given
315  * visual run in the line.
316  *
317  * @param line the <code>pl_line</code> object.
318  * @param runIndex is the index of the run, in visual order.
319  *
320  * @return the <code>pl_visualRun</code> object representing the
321  *         visual run. This object is owned by the <code>pl_line</code> object which
322  *         created it, and will remain valid for as long as the <code>pl_line</code>
323  *         object is valid.
324  *
325  * @see pl_visualRun
326  *
327  * @internal
328  */
329 U_CAPI const pl_visualRun * U_EXPORT2
330 pl_getLineVisualRun(const pl_line *line, le_int32 runIndex);
331 
332 /**
333  * Get the <code>le_font</code> object which
334  * represents the font of the visual run. This will always
335  * be a non-composite font.
336  *
337  * @param run the <code>pl_visualRun</code> object.
338  *
339  * @return the <code>le_font</code> object which represents the
340  *         font of the visual run.
341  *
342  * @see le_font
343  *
344  * @internal
345  */
346 U_CAPI const le_font * U_EXPORT2
347 pl_getVisualRunFont(const pl_visualRun *run);
348 
349 /**
350  * Get the direction of the visual run.
351  *
352  * @param run the <code>pl_visualRun</code> object.
353  *
354  * @return the direction of the run. This will be <code>UBIDI_LTR</code> if the
355  *         run is left-to-right and <code>UBIDI_RTL</code> if the line is right-to-left.
356  *
357  * @internal
358  */
359 U_CAPI UBiDiDirection U_EXPORT2
360 pl_getVisualRunDirection(const pl_visualRun *run);
361 
362 /**
363  * Get the number of glyphs in the visual run.
364  *
365  * @param run the <code>pl_visualRun</code> object.
366  *
367  * @return the number of glyphs.
368  *
369  * @internal
370  */
371 U_CAPI le_int32 U_EXPORT2
372 pl_getVisualRunGlyphCount(const pl_visualRun *run);
373 
374 /**
375  * Get the glyphs in the visual run. Glyphs with the values <code>0xFFFE</code> and
376  * <code>0xFFFF</code> should be ignored.
377  *
378  * @param run the <code>pl_visualRun</code> object.
379  *
380  * @return the address of the array of glyphs for this visual run. The storage
381  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
382  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
383  *
384  * @internal
385  */
386 U_CAPI const LEGlyphID * U_EXPORT2
387 pl_getVisualRunGlyphs(const pl_visualRun *run);
388 
389 /**
390  * Get the (x, y) positions of the glyphs in the visual run. To simplify storage
391  * management, the x and y positions are stored in a single array with the x positions
392  * at even offsets in the array and the corresponding y position in the following odd offset.
393  * There is an extra (x, y) pair at the end of the array which represents the advance of
394  * the final glyph in the run.
395  *
396  * @param run the <code>pl_visualRun</code> object.
397  *
398  * @return the address of the array of glyph positions for this visual run. The storage
399  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
400  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
401  *
402  * @internal
403  */
404 U_CAPI const float * U_EXPORT2
405 pl_getVisualRunPositions(const pl_visualRun *run);
406 
407 /**
408  * Get the glyph-to-character map for this visual run. This maps the indices into
409  * the glyph array to indices into the character array used to create the paragraph.
410  *
411  * @param run the <code>pl_visualRun</code> object.
412  *
413  * @return the address of the character-to-glyph map for this visual run. The storage
414  *         is owned by the <code>pl_visualRun</code> object and must not be deleted.
415  *         It will remain valid as long as the <code>pl_visualRun</code> object is valid.
416  *
417  * @internal
418  */
419 U_CAPI const le_int32 * U_EXPORT2
420 pl_getVisualRunGlyphToCharMap(const pl_visualRun *run);
421 
422 /**
423  * A convenience method which returns the ascent value for the font
424  * associated with this run.
425  *
426  * @param run the <code>pl_visualRun</code> object.
427  *
428  * @return the ascent value of this run's font.
429  *
430  * @internal
431  */
432 U_CAPI le_int32 U_EXPORT2
433 pl_getVisualRunAscent(const pl_visualRun *run);
434 
435 /**
436  * A convenience method which returns the descent value for the font
437  * associated with this run.
438  *
439  * @param run the <code>pl_visualRun</code> object.
440  *
441  * @return the descent value of this run's font.
442  *
443  * @internal
444  */
445 U_CAPI le_int32 U_EXPORT2
446 pl_getVisualRunDescent(const pl_visualRun *run);
447 
448 /**
449  * A convenience method which returns the leading value for the font
450  * associated with this run.
451  *
452  * @param run the <code>pl_visualRun</code> object.
453  *
454  * @return the leading value of this run's font.
455  *
456  * @internal
457  */
458 U_CAPI le_int32 U_EXPORT2
459 pl_getVisualRunLeading(const pl_visualRun *run);
460 
461 #endif  /* U_HIDE_INTERNAL_API */
462 #endif
463 #endif
464