offapi/com/sun/star/accessibility/XAccessibleMultiLineText.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: XAccessibleMultiLineText.idl,v $
  10  * $Revision: 1.2 $
  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
  31 #ifndef __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
  32 #define __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
  33
  34 #ifndef __com_sun_star_accessibility_XAccessibleText_idl__
  35 #include <com/sun/star/accessibility/XAccessibleText.idl>
  36 #endif
  37 #ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
  38 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  39 #endif
  40 #ifndef __com_sun_star_beans_PropertyValue_idl__
  41 #include <com/sun/star/beans/PropertyValue.idl>
  42 #endif
  43
  44 module com { module sun { module star { module accessibility {
  45
  46 /** Implement this interface to give provide a mapping between text index
  47     and line numbers.
  48
  49     <p>This interface is typically used in conjunction with the
  50     <type>XAccessibleText</type> interface and extents it with a notion
  51     of line numbers</p>
  52
  53     @since OOo 3.0.0
  54 */
  55
  56 /// not yet published
  57 interface XAccessibleMultiLineText
  58     : ::com::sun::star::accessibility::XAccessibleText
  59 {
  60     /** Returns the line number at the specified index.
  61
  62         <p>For a text object that is spread over multiple lines, this method
  63         provides a mapping from a text index to the corresponding line number.
  64         </p>
  65
  66         @param nIndex
  67             Index for which the line number should be returned.
  68             The valid range is 0..length.
  69
  70         @return
  71             Returns the line number of the specified text index.
  72
  73         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  74             if the index is invalid.
  75     */
  76     long getLineNumberAtIndex([in] long nIndex)
  77         raises (::com::sun::star::lang::IndexOutOfBoundsException);
  78
  79     /** Retuns the text of the specified line.
  80
  81         <p>Returns the substring of text that makes up the specified line
  82         number.</p>
  83
  84         <p>The number of lines can be obtained by calling
  85         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
  86         with the index of the last character. In a loop, the last line
  87         has been reached when <member>TextSegment::SegmentEnd</member>
  88         of the returned value is equal to the index of the last
  89         character of the text.</p>
  90
  91         @param nLineNo
  92             The number of the line to return the substring from.
  93             The valid range is 0..getLineNumberAtIndex(getCharacterCount()).
  94
  95         @return
  96             Returns the requested text portion.  This portion may be empty
  97             or invalid when no appropriate text portion is found.
  98
  99         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 100             if the line number is invalid
 101     */
 102
 103     TextSegment getTextAtLineNumber([in] long nLineNo)
 104         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 105
 106     /** Returns the text of the line in which the caret is located.
 107
 108         <p>The substring returned will most of the time be identical to
 109         calling <member>XAccessibleText::getTextAtIndex</member> with
 110         the index returned by <member>XAccessibleText::getCaretPosition</member>
 111         and type  <const scope="AccessibleTextType">LINE</type> beside the
 112         following special case:</p>
 113
 114         <p>Some text implementations place the caret at the end of the current
 115         line when the <b>End</b> key gets pressed. Since the index of this position
 116         is identical to the one of the first character of the following line,
 117         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
 118         return the line following the current one in this case.</p>
 119
 120         @return
 121             Returns the requested text portion. This portion may be empty
 122             or invalid if the paragraph object does not have a valid caret
 123             position.
 124     */
 125
 126     TextSegment getTextAtLineWithCaret();
 127
 128     /** Returns the number of the line in which the caret is located.
 129
 130         <p>The line number returned will most of the time be identical to
 131         calling <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
 132         with the index returned by <member>XAccessibleText::getCaretPosition</member>
 133         beside the following special case:</p>
 134
 135         <p>Some text implementations place the caret at the end of the current
 136         line when the <b>End</b> key gets pressed. Since the index of this position
 137         is identical to the one of the first character of the following line,
 138         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
 139         return the line following the current one in this case.</p>
 140
 141         @return
 142             Returns the index of the line in which the caret is located or -1
 143             if the paragraph does not have a valid caret position.
 144     */
 145
 146     long getNumberOfLineWithCaret();
 147 };
 148
 149 }; }; }; };
 150
 151 #endif