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 OpenOffice 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