idl/Accessibility_EditableText.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <Accessibility.idl>
  24
  25 module Accessibility {
  26
  27   /**
  28    * Derived from interface Text, EditableText provides methods for
  29    * modifying textual content of components which support editing.
  30    * EditableText also interacts with the system clipboard via copyText,
  31    * cutText, and pasteText.
  32    *
  33    * @note read-only instances of EditableText are possible;
  34    *       These may be instances of a general-purpose component type which are
  35    *       sometimes, but not always, user-editable, or may be
  36    *       components which are temporarily or circumstantially
  37    *       in a non-editable state.
  38    */
  39   interface EditableText : Text {
  40     /**
  41      * Replace the text contents with a new string, discarding the old contents.
  42      *
  43      * @param newContents a UTF-8 string with which the text object's contents will be replaced.
  44      * @returns \c True if the text content was successfully changed, \c False otherwise.
  45      */
  46     boolean setTextContents (in string newContents);
  47     /**
  48      * Insert new text contents into an existing text object at a given location, while retaining
  49      * the old contents.
  50      * @param position the character offset into the Text implementor's content at which the
  51      *        new content will be inserted.
  52      * @param text a UTF-8 string of which \c length characters will be inserted into the text
  53      *         object's text buffer.
  54      * @param length the number of characters of \c text to insert.  If the character count
  55      *         of \c text is less than or equal to \c length, the entire contents of \c text
  56      *         will be inserted.
  57      *
  58      * @returns \c True if the text content was successfully inserted, \c False otherwise.
  59      */
  60     boolean insertText (in long position, in string text, in long length);
  61     /**
  62      * Apply a particular set of attributes to a range of text.
  63      *
  64      *
  65      * @returns \c True if the text attributes were successfully modified, \c False otherwise.
  66      */
  67     boolean setAttributes (in string attributes, in long startPos, in long endPos);
  68     /**
  69      * Copy a range of text into the system clipboard.
  70      * @param startPos the character offset of the first character in the range of text being
  71      *        copied.
  72      * @param endPos the offset of the first character past the end of the range of text
  73      *        being copied.
  74      */
  75     void    copyText (in long startPos, in long endPos);
  76     /**
  77      * Excise a range of text from a Text object, copying it into the system clipboard.
  78      * @param startPos the character offset of the first character in the range of text being
  79      *        cut.
  80      * @param endPos the offset of the first character past the end of the range of text
  81      *        being cut.
  82      * @returns \c True if the text was successfully cut, \c False otherwise.
  83      */
  84     boolean cutText (in long startPos, in long endPos);
  85     /**
  86      * Excise a range of text from a Text object without copying it into the system clipboard.
  87      * @param startPos the character offset of the first character in the range of text being
  88      *        deleted.
  89      * @param endPos the offset of the first character past the end of the range of text
  90      *        being deleted.
  91      * @returns \c True if the text was successfully deleted, \c False otherwise.
  92      */
  93     boolean deleteText (in long startPos, in long endPos);
  94     /**
  95      * Copy the text contents of the system clipboard, if any, into a Text object,
  96      * inserting it at a particular character offset.
  97      *
  98      * @param position the character offset before which the text will be inserted.
  99      * @returns \c True if the text was successfully pasted into the Text object, \c False otherwise.
 100      */
 101     boolean pasteText (in long position);
 102
 103     /**
 104      * unImplemented:
 105      *
 106      * placeholders for future expansion. Note that these are named
 107      * 'unimplemented5 and unimplemented6' to avoid conflict with
 108      * placeholders from Accessibility::Text.
 109      */
 110     void unImplemented5 ();
 111     void unImplemented6 ();
 112     void unImplemented9 ();
 113     void unImplemented10 ();
 114     void unImplemented11 ();
 115     void unImplemented12 ();
 116   };
 117 };