offapi/com/sun/star/rendering/XTextLayout.idl

   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
  65 module com { module sun { module star { module rendering {
  66
  67 interface XCanvas;
  68 interface XCanvasFont;
  69 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.0
  94  */
  95 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