1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_rendering_XTextLayout_idl__
28#define __com_sun_star_rendering_XTextLayout_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
34#include <com/sun/star/lang/IllegalArgumentException.idl>
35#endif
36#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
37#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
38#endif
39#ifndef __com_sun_star_geometry_RealPoint2D_idl__
40#include <com/sun/star/geometry/RealPoint2D.idl>
41#endif
42#ifndef __com_sun_star_geometry_RealBezierSegment2D_idl__
43#include <com/sun/star/geometry/RealBezierSegment2D.idl>
44#endif
45#ifndef __com_sun_star_geometry_RealRectangle2D_idl__
46#include <com/sun/star/geometry/RealRectangle2D.idl>
47#endif
48#ifndef __com_sun_star_rendering_ViewState_idl__
49#include <com/sun/star/rendering/ViewState.idl>
50#endif
51#ifndef __com_sun_star_rendering_RenderState_idl__
52#include <com/sun/star/rendering/RenderState.idl>
53#endif
54#ifndef __com_sun_star_rendering_StringContext_idl__
55#include <com/sun/star/rendering/StringContext.idl>
56#endif
57#ifndef __com_sun_star_rendering_TextHit_idl__
58#include <com/sun/star/rendering/TextHit.idl>
59#endif
60#ifndef __com_sun_star_rendering_Caret_idl__
61#include <com/sun/star/rendering/Caret.idl>
62#endif
63
64
65module com { module sun { module star { module rendering {
66
67published interface XCanvas;
68published interface XCanvasFont;
69published interface XPolyPolygon2D;
70
71/** This is the central interface for text layouting.<p>
72
73    This is the central interface for text-related tasks more
74    complicated than simple string rendering. Note that all query
75    methods are subject to the current layout state of this
76    object. That is, calls to <member>XTextLayout::justify()</member>
77    or <member>XTextLayout::applyLogicalAdvancements()</member> are
78    likely to change subsequent output of those query methods.<p>
79
80    Similar to <type>XCanvasFont</type>, all measurements and
81    coordinates accepted and returned by this interface are relative
82    to the font's local coordinate system (which only equals device
83    coordinate space, if the combined render transformation used
84    during text output is the identity transformation). Conversely, if
85    the combined transformation used during text output is
86    <em>not</em> the identity transformation, all measurements
87    returned by this interface should be subjected to that
88    transformation, to yield values in device coordinate space.
89    Depending on the underlying font technology, actual device output
90    might be off by up to one device pixel from the transformed
91    metrics.<p>
92
93    @since OOo 2.0
94 */
95published interface XTextLayout : ::com::sun::star::uno::XInterface
96{
97    /** Extract the polygonal shapes of the layouted text.<p>
98
99        Each glyph is represented by a separate
100        <type>XPolyPolygon2D</type> in the returned sequence.<p>
101
102        @returns a sequence of <type>XPolyPolygon2D</type> in font
103        coordinate space, one for every glyph.
104     */
105    sequence<XPolyPolygon2D>	queryTextShapes();
106
107    //-------------------------------------------------------------------------
108
109    /** Query the ink bounding boxes for every glyph in the layouted
110        text.<p>
111
112        Ink, or tight bounding boxes in this case means that for
113        e.g. an 'a', the bounding box for the
114        <type>XPolyPolygon2D</type> describing the glyph 'a' is
115        returned, not the logical dimensions of the character in the
116        font.<p>
117
118        @returns a sequence of rectangles in font coordinate space,
119        specifying the bounds, one for every glyph.
120
121        @see <member>XTextLayout::queryMeasures()</member>
122     */
123    sequence<::com::sun::star::geometry::RealRectangle2D >	queryInkMeasures();
124
125    //-------------------------------------------------------------------------
126
127    /** Query the logical bounding boxes of every character in the
128        given text string.<p>
129
130        Logical bounding boxes means the space that the font allocates
131        for the given character, which, e.g. for a '.', might be
132        significantly broader than the bounds returned via
133        <member>XTextLayout::queryInkMeasures()</member>.
134
135        @returns a sequence of rectangles specifying the bounds in
136        font coordinate space, one for every glyph.
137
138        @see <member>XTextLayout::queryInkMeasures()</member>
139     */
140    sequence<::com::sun::star::geometry::RealRectangle2D>	queryMeasures();
141
142    //-------------------------------------------------------------------------
143
144    /** Query the advancements for every character in the input string.<p>
145
146        This method returns a sequence of advancements, one for each
147        character in the input string (<em>not</em> for every
148        glyph. There might be multiple glyphs per input character, or
149        multiple input characters per glyph). Adding up all
150        advancements yields the total advancement of this layout. To
151        manipulate the layout of a string on the level of characters,
152        this method can be used to query for the layout's default
153        advancements, which can subsequently be changed and applied to
154        the layout via
155        <member>XTextLayout::applyLogicalAdvancements()</member>.<p>
156
157        @returns a sequence of <type>double</type> specifying the
158        advancements per character in font coordinate space.
159
160        @see <member>XTextLayout::applyLogicalAdvancements()</member>
161     */
162    sequence<double>			queryLogicalAdvancements();
163
164    //-------------------------------------------------------------------------
165
166    /** Apply explicit advancements for every character in the layout
167        string.<p>
168
169        This method applies the specified advancements to every
170        logical character in the input string (<em>not</em> for every
171        glyph. There might be multiple glyphs per input character, or
172        multiple input characters per glyph). This is useful to
173        explicitely manipulate the exact output positions of
174        characters, e.g. relative to a reference output device.<p>
175
176        @param aAdvancements
177        A sequence of character advancements, in font coordinate
178        space.
179
180        @see <member>XTextLayout::queryLogicalAdvancements()</member>
181
182        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
183        if the size of aAdvancements does not match the number of
184        characters in the text.
185     */
186    void						applyLogicalAdvancements( [in] sequence< double > aAdvancements )
187        raises (com::sun::star::lang::IllegalArgumentException);
188
189    //-------------------------------------------------------------------------
190
191    /** Query the overall bounding box of the text.<p>
192
193        This method is similar to
194        <member>XTextLayout::queryTextMeasures</member>, only that the
195        overall bounds are returned by this method.<p>
196
197        @return the overall bounding box for the given layout, in font
198        coordinate space.
199     */
200    ::com::sun::star::geometry::RealRectangle2D   queryTextBounds();
201
202    //-------------------------------------------------------------------------
203
204    /** Justify the text to the given size.<p>
205
206        This method is the core of the <type>XTextLayout</type>
207        interface, because it layouts the text in a typographically
208        correct way into the available space.<p>
209
210        @param nSize
211        The requested size of the text after justification (either
212        width or height, depending on the writing mode). This
213        parameter is interpreted in font coordinate space.
214
215        @return the actual size of the text after the justification in
216        the font coordinate space. Depending on the font and the
217        script type, this might be somewhat different from the size
218        requested. If the requested size was smaller than the
219        justification algorithm could compress the text, this value
220        might even be significantly larger than nSize.
221
222        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
223        if nSize is 0 or negative.
224     */
225    double justify( [in] double nSize )
226        raises (com::sun::star::lang::IllegalArgumentException);
227
228    //-------------------------------------------------------------------------
229
230    /** Justify a number of text layouts to the given size.<p>
231
232        This method can be used to combine the layout of a text line
233        into a single justification run. This is e.g. useful if the
234        line consists of several text portions (e.g. because of
235        different fonts or colors), but it is desirable to spread the
236        available space more globally across the different layout
237        objects. If, for example, one layout object contains
238        significantly more whitespace or Kashidas than the rest, this
239        method can assign proportionally more space to this layout
240        object.<p>
241
242        @param aNextLayouts
243        A sequence of layouts following this one in logical text
244        order.
245
246        @param nSize
247        The requested size of the text for <em>all</em>
248        <type>XTextLayout</type>s after justification in font
249        coordinate space (either width or height, depending on the
250        writing mode).
251
252        @return the actual size of the text after the justification,
253        in font coordinate space. Depending on the font and the
254        script type, this might be somewhat different from the size
255        requested. If the requested size was smaller than the
256        justification algorithm could compress the text, this value
257        might even be significantly larger than nSize.
258
259        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
260        if one of the parameters are not in the valid range.
261     */
262    double combinedJustify( [in] sequence< XTextLayout > aNextLayouts, [in] double nSize )
263        raises (com::sun::star::lang::IllegalArgumentException);
264
265    //-------------------------------------------------------------------------
266
267    /** This method determines the hit position in the text.<p>
268
269        This method determines the index of the character hit at the
270        specified position (in font coordinate space).<p>
271
272        @param aHitPoint
273        The position in font coordinate space to determine the
274        underlying character index for.
275
276     */
277    TextHit getTextHit( [in] ::com::sun::star::geometry::RealPoint2D aHitPoint );
278
279    //-------------------------------------------------------------------------
280
281    /** This method converts an insertion index to a caret.<p>
282
283        This method generates caret information for a given insertion
284        point in the layout text.<p>
285
286        @param nInsertionIndex
287        The insertion index, as e.g. returned by
288        <member>XTextLayout::getTextHit()</member>. This value must be
289        in the range 0 up to the number of characters in the string.
290
291        @param bExcludeLigatures
292        Set this to <TRUE/>, to skip the positions inside ligatures as
293        valid caret placements. That means, on cannot e.g. set the
294        caret between the 'f' and the 'i' in a 'fi' ligature.
295
296        @returns the generated Caret structure.
297
298        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
299        if nInsertionIndex is outside the permissible range.
300     */
301    Caret getCaret( [in] long nInsertionIndex,
302                    [in] boolean bExcludeLigatures )
303        raises (com::sun::star::lang::IndexOutOfBoundsException);
304
305    //-------------------------------------------------------------------------
306
307    /** This method calculates a new insertion index.<p>
308
309        This method calculates a new insertion index, given a start
310        index and the number of characters to skip. This is most
311        useful for caret traveling.<p>
312
313        @param nStartIndex
314        The insertion index to start from.
315
316        @param nCaretAdvancement
317        For values greater than 0, the caret is visually moved to the
318        right. For values smaller than 0, the caret is visually moved
319        to the left.
320
321        @returns the new insertion index.
322
323        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
324        if nStartIndex or nCaretAdvancement is outside the permissible
325        range.
326     */
327    long getNextInsertionIndex( [in] long nStartIndex,
328                                [in] long nCaretAdvancement,
329                                [in] boolean bExcludeLigatures )
330        raises (com::sun::star::lang::IndexOutOfBoundsException);
331
332    //-------------------------------------------------------------------------
333
334    /** This method generates a highlight polygon.<p>
335
336        This method generates a highlighting polygon from two
337        insertion indices. This polygon will be visually continuous,
338        i.e. will not have non-highlighted text in between.<p>
339
340        @param nStartIndex
341        Start of the selection range.
342
343        @param nEndIndex
344        End of the selection range.
345
346        @return the highlight polygon in the font coordinate space.
347
348        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
349        if nStartIndex or nEndIndex are outside the permissible
350        range.
351     */
352    XPolyPolygon2D queryVisualHighlighting( [in] long nStartIndex,
353                                            [in] long nEndIndex )
354        raises (com::sun::star::lang::IndexOutOfBoundsException);
355
356    //-------------------------------------------------------------------------
357
358    /** This method generates a highlight polygon.<p>
359
360        This method generates a highlighting polygon from two
361        insertion indices. This polygon will not always be visually
362        continuous, if e.g. the text direction changes in the middle
363        of the selection, the might be parts visually between start
364        and end position that are not selected.<p>
365
366        @param nStartIndex
367        Start of the selection range.
368
369        @param nEndIndex
370        End of the selection range.
371
372        @return the highlight polygon in the font coordinate space.
373
374        @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
375        if nStartIndex or nEndIndex are outside the permissible
376        range.
377     */
378    XPolyPolygon2D queryLogicalHighlighting( [in] long nStartIndex,
379                                             [in] long nEndIndex )
380        raises (com::sun::star::lang::IndexOutOfBoundsException);
381
382    //-------------------------------------------------------------------------
383
384    /** This method yields the baseline offset.<p>
385
386        This method returns the baseline offset for this layout
387        object, either measured from the top or the left edge,
388        depending on the writing direction (horizontally or
389        vertically). Since rendering this layout via
390        <member>XCanvas::drawTextLayout()</member> outputs relative to
391        the layout object's baseline, this method can be used to
392        e.g. output relative to the left, top edge.<p>
393
394        @returns the distance of the main baseline from the top or the
395        left edge of this object, depending on the writing direction.
396     */
397    double getBaselineOffset();
398
399    //-------------------------------------------------------------------------
400
401    /** This method returns the main writing direction.<p>
402
403        This method returns the main writing direction of this layout,
404        i.e. either LEFT_TO_RIGHT or RIGHT_TO_LEFT.<p>
405
406        @returns the main text direction of this layout.
407     */
408    byte getMainTextDirection();
409
410    //-------------------------------------------------------------------------
411
412    /** Request the associated font for this layout..
413
414        @returns the associated font for this layout.
415     */
416    XCanvasFont getFont();
417
418    //-------------------------------------------------------------------------
419
420    /** Request the text this layout contains.
421
422        @returns the text this layout contains.
423     */
424    StringContext getText();
425
426    //-------------------------------------------------------------------------
427
428};
429
430}; }; }; };
431
432#endif
433