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

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