Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 396 insertions, 0 deletions

diff --git a/offapi/com/sun/star/rendering/XTextLayout.idl b/offapi/com/sun/star/rendering/XTextLayout.idl
new file mode 100644
index 000000000..dc71f857e
--- /dev/null
+++ b/offapi/com/sun/star/rendering/XTextLayout.idl
@@ -0,0 +1,396 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+#ifndef __com_sun_star_rendering_XTextLayout_idl__
+#define __com_sun_star_rendering_XTextLayout_idl__
+
+#include <com/sun/star/uno/XInterface.idl>
+#include <com/sun/star/lang/IllegalArgumentException.idl>
+#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
+#include <com/sun/star/geometry/RealPoint2D.idl>
+#include <com/sun/star/geometry/RealBezierSegment2D.idl>
+#include <com/sun/star/geometry/RealRectangle2D.idl>
+#include <com/sun/star/rendering/ViewState.idl>
+#include <com/sun/star/rendering/RenderState.idl>
+#include <com/sun/star/rendering/StringContext.idl>
+#include <com/sun/star/rendering/TextHit.idl>
+#include <com/sun/star/rendering/Caret.idl>
+
+
+module com { module sun { module star { module rendering {
+
+interface XCanvas;
+interface XCanvasFont;
+interface XPolyPolygon2D;
+
+/** This is the central interface for text layouting.<p>
+
+    This is the central interface for text-related tasks more
+    complicated than simple string rendering. Note that all query
+    methods are subject to the current layout state of this
+    object. That is, calls to XTextLayout::justify()
+    or XTextLayout::applyLogicalAdvancements() are
+    likely to change subsequent output of those query methods.<p>
+
+    Similar to XCanvasFont, all measurements and
+    coordinates accepted and returned by this interface are relative
+    to the font's local coordinate system (which only equals device
+    coordinate space, if the combined render transformation used
+    during text output is the identity transformation). Conversely, if
+    the combined transformation used during text output is
+    <em>not</em> the identity transformation, all measurements
+    returned by this interface should be subjected to that
+    transformation, to yield values in device coordinate space.
+    Depending on the underlying font technology, actual device output
+    might be off by up to one device pixel from the transformed
+    metrics.<p>
+
+    @since OOo 2.0
+ */
+interface XTextLayout : ::com::sun::star::uno::XInterface
+{
+    /** Extract the polygonal shapes of the layouted text.<p>
+
+        Each glyph is represented by a separate
+        XPolyPolygon2D in the returned sequence.<p>
+
+        @returns a sequence of XPolyPolygon2D in font
+        coordinate space, one for every glyph.
+     */
+    sequence<XPolyPolygon2D>    queryTextShapes();
+
+
+    /** Query the ink bounding boxes for every glyph in the layouted
+        text.<p>
+
+        Ink, or tight bounding boxes in this case means that for
+        e.g. an "a", the bounding box for the
+        XPolyPolygon2D describing the glyph "a" is
+        returned, not the logical dimensions of the character in the
+        font.<p>
+
+        @returns a sequence of rectangles in font coordinate space,
+        specifying the bounds, one for every glyph.
+
+        @see XTextLayout::queryMeasures()
+     */
+    sequence<::com::sun::star::geometry::RealRectangle2D >  queryInkMeasures();
+
+
+    /** Query the logical bounding boxes of every character in the
+        given text string.<p>
+
+        Logical bounding boxes means the space that the font allocates
+        for the given character, which, e.g. for a ".", might be
+        significantly broader than the bounds returned via
+        XTextLayout::queryInkMeasures().
+
+        @returns a sequence of rectangles specifying the bounds in
+        font coordinate space, one for every glyph.
+
+        @see XTextLayout::queryInkMeasures()
+     */
+    sequence<::com::sun::star::geometry::RealRectangle2D>   queryMeasures();
+
+
+    /** Query the advancements for every character in the input string.<p>
+
+        This method returns a sequence of advancements, one for each
+        character in the input string (<em>not</em> for every
+        glyph. There might be multiple glyphs per input character, or
+        multiple input characters per glyph).
+
+        An advancement value is the distance of the glyph to the beginning
+        edge, which is left for LTR text and is right for RTL text. The
+        maximum of the advancements can be deemed as the width of the whole
+        text layout.
+
+        This method can be used to query for the layout's default
+        advancements, which can subsequently be changed and applied to
+        the layout via
+        XTextLayout::applyLogicalAdvancements().<p>
+
+        @returns a sequence of double specifying the
+        advancements per character in font coordinate space.
+
+        @see XTextLayout::applyLogicalAdvancements()
+     */
+    sequence<double>            queryLogicalAdvancements();
+
+
+    /** Apply explicit advancements for every character in the layout
+        string.<p>
+
+        This method applies the specified advancements to every
+        logical character in the input string (<em>not</em> for every
+        glyph. There might be multiple glyphs per input character, or
+        multiple input characters per glyph). This is useful to
+        explicitly manipulate the exact output positions of
+        characters, e.g. relative to a reference output device.<p>
+
+        @param aAdvancements
+        A sequence of character advancements, in font coordinate
+        space.
+
+        @see XTextLayout::queryLogicalAdvancements()
+
+        @throws com::sun::star::lang::IllegalArgumentException
+        if the size of aAdvancements does not match the number of
+        characters in the text.
+     */
+    void                        applyLogicalAdvancements( [in] sequence< double > aAdvancements )
+        raises (com::sun::star::lang::IllegalArgumentException);
+
+
+    /** Query the overall bounding box of the text.<p>
+
+        This method is similar to
+        XTextLayout::queryTextMeasures(), only that the
+        overall bounds are returned by this method.<p>
+
+        @return the overall bounding box for the given layout, in font
+        coordinate space.
+     */
+    ::com::sun::star::geometry::RealRectangle2D   queryTextBounds();
+
+
+    /** Justify the text to the given size.<p>
+
+        This method is the core of the XTextLayout
+        interface, because it layouts the text in a typographically
+        correct way into the available space.<p>
+
+        @param nSize
+        The requested size of the text after justification (either
+        width or height, depending on the writing mode). This
+        parameter is interpreted in font coordinate space.
+
+        @return the actual size of the text after the justification in
+        the font coordinate space. Depending on the font and the
+        script type, this might be somewhat different from the size
+        requested. If the requested size was smaller than the
+        justification algorithm could compress the text, this value
+        might even be significantly larger than nSize.
+
+        @throws com::sun::star::lang::IllegalArgumentException
+        if nSize is 0 or negative.
+     */
+    double justify( [in] double nSize )
+        raises (com::sun::star::lang::IllegalArgumentException);
+
+
+    /** Justify a number of text layouts to the given size.<p>
+
+        This method can be used to combine the layout of a text line
+        into a single justification run. This is e.g. useful if the
+        line consists of several text portions (e.g. because of
+        different fonts or colors), but it is desirable to spread the
+        available space more globally across the different layout
+        objects. If, for example, one layout object contains
+        significantly more whitespace or Kashidas than the rest, this
+        method can assign proportionally more space to this layout
+        object.<p>
+
+        @param aNextLayouts
+        A sequence of layouts following this one in logical text
+        order.
+
+        @param nSize
+        The requested size of the text for <em>all</em>
+        XTextLayouts after justification in font
+        coordinate space (either width or height, depending on the
+        writing mode).
+
+        @return the actual size of the text after the justification,
+        in font coordinate space. Depending on the font and the
+        script type, this might be somewhat different from the size
+        requested. If the requested size was smaller than the
+        justification algorithm could compress the text, this value
+        might even be significantly larger than nSize.
+
+        @throws com::sun::star::lang::IllegalArgumentException
+        if one of the parameters are not in the valid range.
+     */
+    double combinedJustify( [in] sequence< XTextLayout > aNextLayouts, [in] double nSize )
+        raises (com::sun::star::lang::IllegalArgumentException);
+
+
+    /** This method determines the hit position in the text.<p>
+
+        This method determines the index of the character hit at the
+        specified position (in font coordinate space).<p>
+
+        @param aHitPoint
+        The position in font coordinate space to determine the
+        underlying character index for.
+
+     */
+    TextHit getTextHit( [in] ::com::sun::star::geometry::RealPoint2D aHitPoint );
+
+
+    /** This method converts an insertion index to a caret.<p>
+
+        This method generates caret information for a given insertion
+        point in the layout text.<p>
+
+        @param nInsertionIndex
+        The insertion index, as e.g. returned by
+        XTextLayout::getTextHit(). This value must be
+        in the range 0 up to the number of characters in the string.
+
+        @param bExcludeLigatures
+        Set this to `TRUE` to skip the positions inside ligatures as
+        valid caret placements. For example, this would avoid setting
+        the caret between the "f" and the "i" in a "fi" ligature.
+
+        @returns the generated Caret structure.
+
+        @throws com::sun::star::lang::IndexOutOfBoundsException
+        if nInsertionIndex is outside the permissible range.
+     */
+    Caret getCaret( [in] long nInsertionIndex,
+                    [in] boolean bExcludeLigatures )
+        raises (com::sun::star::lang::IndexOutOfBoundsException);
+
+
+    /** This method calculates a new insertion index.<p>
+
+        This method calculates a new insertion index, given a start
+        index and the number of characters to skip. This is most
+        useful for caret traveling.<p>
+
+        @param nStartIndex
+        The insertion index to start from.
+
+        @param nCaretAdvancement
+        For values greater than 0, the caret is visually moved to the
+        right. For values smaller than 0, the caret is visually moved
+        to the left.
+
+        @param bExcludeLigatures
+        Set this to `TRUE` to skip the positions inside ligatures as
+        valid caret placements. For example, this would avoid setting
+        the caret between the "f" and the "i" in a "fi" ligature.
+
+        @returns the new insertion index.
+
+        @throws com::sun::star::lang::IndexOutOfBoundsException
+        if nStartIndex or nCaretAdvancement is outside the permissible
+        range.
+     */
+    long getNextInsertionIndex( [in] long nStartIndex,
+                                [in] long nCaretAdvancement,
+                                [in] boolean bExcludeLigatures )
+        raises (com::sun::star::lang::IndexOutOfBoundsException);
+
+
+    /** This method generates a highlight polygon.<p>
+
+        This method generates a highlighting polygon from two
+        insertion indices. This polygon will be visually continuous,
+        i.e. will not have non-highlighted text in between.<p>
+
+        @param nStartIndex
+        Start of the selection range.
+
+        @param nEndIndex
+        End of the selection range.
+
+        @return the highlight polygon in the font coordinate space.
+
+        @throws com::sun::star::lang::IndexOutOfBoundsException
+        if nStartIndex or nEndIndex are outside the permissible
+        range.
+     */
+    XPolyPolygon2D queryVisualHighlighting( [in] long nStartIndex,
+                                            [in] long nEndIndex )
+        raises (com::sun::star::lang::IndexOutOfBoundsException);
+
+
+    /** This method generates a highlight polygon.<p>
+
+        This method generates a highlighting polygon from two
+        insertion indices. This polygon will not always be visually
+        continuous, if e.g. the text direction changes in the middle
+        of the selection, the might be parts visually between start
+        and end position that are not selected.<p>
+
+        @param nStartIndex
+        Start of the selection range.
+
+        @param nEndIndex
+        End of the selection range.
+
+        @return the highlight polygon in the font coordinate space.
+
+        @throws com::sun::star::lang::IndexOutOfBoundsException
+        if nStartIndex or nEndIndex are outside the permissible
+        range.
+     */
+    XPolyPolygon2D queryLogicalHighlighting( [in] long nStartIndex,
+                                             [in] long nEndIndex )
+        raises (com::sun::star::lang::IndexOutOfBoundsException);
+
+
+    /** This method yields the baseline offset.<p>
+
+        This method returns the baseline offset for this layout
+        object, either measured from the top or the left edge,
+        depending on the writing direction (horizontally or
+        vertically). Since rendering this layout via
+        XCanvas::drawTextLayout() outputs relative to
+        the layout object's baseline, this method can be used to
+        e.g. output relative to the left, top edge.<p>
+
+        @returns the distance of the main baseline from the top or the
+        left edge of this object, depending on the writing direction.
+     */
+    double getBaselineOffset();
+
+
+    /** This method returns the main writing direction.<p>
+
+        This method returns the main writing direction of this layout,
+        i.e. either LEFT_TO_RIGHT or RIGHT_TO_LEFT.<p>
+
+        @returns the main text direction of this layout.
+     */
+    byte getMainTextDirection();
+
+
+    /** Request the associated font for this layout.
+
+        @returns the associated font for this layout.
+     */
+    XCanvasFont getFont();
+
+
+    /** Request the text this layout contains.
+
+        @returns the text this layout contains.
+     */
+    StringContext getText();
+
+
+};
+
+}; }; }; };
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */