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