offapi/com/sun/star/accessibility/XAccessibleMultiLineText.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
  29 #define __com_sun_star_accessibility_XAccessibleMultiLineText_idl__
  30
  31 #ifndef __com_sun_star_accessibility_XAccessibleText_idl__
  32 #include <com/sun/star/accessibility/XAccessibleText.idl>
  33 #endif
  34 #ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
  35 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  36 #endif
  37 #ifndef __com_sun_star_beans_PropertyValue_idl__
  38 #include <com/sun/star/beans/PropertyValue.idl>
  39 #endif
  40
  41 module com { module sun { module star { module accessibility {
  42
  43 /** Implement this interface to give provide a mapping between text index
  44     and line numbers.
  45
  46     <p>This interface is typically used in conjunction with the
  47     <type>XAccessibleText</type> interface and extents it with a notion
  48     of line numbers</p>
  49
  50     @since OOo 3.0.0
  51 */
  52
  53 /// not yet published
  54 interface XAccessibleMultiLineText
  55     : ::com::sun::star::accessibility::XAccessibleText
  56 {
  57     /** Returns the line number at the specified index.
  58
  59         <p>For a text object that is spread over multiple lines, this method
  60         provides a mapping from a text index to the corresponding line number.
  61         </p>
  62
  63         @param nIndex
  64             Index for which the line number should be returned.
  65             The valid range is 0..length.
  66
  67         @return
  68             Returns the line number of the specified text index.
  69
  70         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  71             if the index is invalid.
  72     */
  73     long getLineNumberAtIndex([in] long nIndex)
  74         raises (::com::sun::star::lang::IndexOutOfBoundsException);
  75
  76     /** Retuns the text of the specified line.
  77
  78         <p>Returns the substring of text that makes up the specified line
  79         number.</p>
  80
  81         <p>The number of lines can be obtained by calling
  82         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
  83         with the index of the last character. In a loop, the last line
  84         has been reached when <member>TextSegment::SegmentEnd</member>
  85         of the returned value is equal to the index of the last
  86         character of the text.</p>
  87
  88         @param nLineNo
  89             The number of the line to return the substring from.
  90             The valid range is 0..getLineNumberAtIndex(getCharacterCount()).
  91
  92         @return
  93             Returns the requested text portion.  This portion may be empty
  94             or invalid when no appropriate text portion is found.
  95
  96         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  97             if the line number is invalid
  98     */
  99
 100     TextSegment getTextAtLineNumber([in] long nLineNo)
 101         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 102
 103     /** Returns the text of the line in which the caret is located.
 104
 105         <p>The substring returned will most of the time be identical to
 106         calling <member>XAccessibleText::getTextAtIndex</member> with
 107         the index returned by <member>XAccessibleText::getCaretPosition</member>
 108         and type  <const scope="AccessibleTextType">LINE</type> beside the
 109         following special case:</p>
 110
 111         <p>Some text implementations place the caret at the end of the current
 112         line when the <b>End</b> key gets pressed. Since the index of this position
 113         is identical to the one of the first character of the following line,
 114         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
 115         return the line following the current one in this case.</p>
 116
 117         @return
 118             Returns the requested text portion. This portion may be empty
 119             or invalid if the paragraph object does not have a valid caret
 120             position.
 121     */
 122
 123     TextSegment getTextAtLineWithCaret();
 124
 125     /** Returns the number of the line in which the caret is located.
 126
 127         <p>The line number returned will most of the time be identical to
 128         calling <member>XAccessibleMultiLineText::getLineNumberAtIndex</member>
 129         with the index returned by <member>XAccessibleText::getCaretPosition</member>
 130         beside the following special case:</p>
 131
 132         <p>Some text implementations place the caret at the end of the current
 133         line when the <b>End</b> key gets pressed. Since the index of this position
 134         is identical to the one of the first character of the following line,
 135         <member>XAccessibleMultiLineText::getLineNumberAtIndex</member> will
 136         return the line following the current one in this case.</p>
 137
 138         @return
 139             Returns the index of the line in which the caret is located or -1
 140             if the paragraph does not have a valid caret position.
 141     */
 142
 143     long getNumberOfLineWithCaret();
 144 };
 145
 146 }; }; }; };
 147
 148 #endif