path: root/offapi/com/sun/star/rendering/XTextLayout.idl

/* -*- 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 .
 */


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 Kashida insertion positions in the input string.<p>

        This method returns a sequence of Kashida insertion positions, 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).<p>

        A Kashida insertion position is a boolean indicating if Kashida should
        inserted after this character.<p>

        This method can be used to query for the layout's default Kashida
        insertion positions, which can subsequently be changed and applied to
        the layout via
        XTextLayout::applyKashidaPositions().<p>

        @returns a sequence of booleans specifying the Kashida insertion
        positions per character.

        @see XTextLayout::applyKashidaPositions)

        @since LibreOffice 7.6
     */
    sequence<boolean>            queryKashidaPositions();


    /** Apply Kashida insertion positions for the layout string.<p>

        This method applies the specified Kashida insertion positions 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).<p>

        @param aPositions
        A sequence of booleans specifying Kashida insertion positions.

        @see XTextLayout::queryKashidaPositions()

        @throws com::sun::star::lang::IllegalArgumentException
        if the size of aPositions is not zero and does not match the number of
        characters in the text.

        @since LibreOffice 7.6
     */
    void                        applyKashidaPositions( [in] sequence< boolean > aPositions )
        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();


};

}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */