• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
469