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

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