/* 
 * AT-SPI - Assistive Technology Service Provider Interface 
 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
 *
 * Copyright 2001 Sun Microsystems, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include <Accessibility.idl>

module Accessibility {

  /** 
   * Derived from interface Text, EditableText provides methods for
   * modifying textual content of components which support editing.
   * EditableText also interacts with the system clipboard via copyText,
   * cutText, and pasteText.
   * 
   * @note read-only instances of EditableText are possible; 
   *       These may be instances of a general-purpose component type which are
   *       sometimes, but not always, user-editable, or may be
   *       components which are temporarily or circumstantially
   *       in a non-editable state. 
   */
  interface EditableText : Text {
    /** 
     * Replace the text contents with a new string, discarding the old contents.
     *
     * @param newContents a UTF-8 string with which the text object's contents will be replaced.
     * @returns \c True if the text content was successfully changed, \c False otherwise.
     */
    boolean setTextContents (in string newContents);
    /** 
     * Insert new text contents into an existing text object at a given location, while retaining
     * the old contents.
     * @param position the character offset into the Text implementor's content at which the
     *        new content will be inserted.
     * @param text a UTF-8 string of which \c length characters will be inserted into the text 
     *         object's text buffer.
     * @param length the number of characters of \c text to insert.  If the character count
     *         of \c text is less than or equal to \c length, the entire contents of \c text
     *         will be inserted.
     * 
     * @returns \c True if the text content was successfully inserted, \c False otherwise.
     */
    boolean insertText (in long position, in string text, in long length);
    /**
     * Apply a particular set of attributes to a range of text.
     *
     *
     * @returns \c True if the text attributes were successfully modified, \c False otherwise.
     */
    boolean setAttributes (in string attributes, in long startPos, in long endPos);
    /**
     * Copy a range of text into the system clipboard.
     * @param startPos the character offset of the first character in the range of text being
     *        copied.
     * @param endPos the offset of the first character past the end of the range of text
     *        being copied.
     */
    void    copyText (in long startPos, in long endPos);
    /**
     * Excise a range of text from a Text object, copying it into the system clipboard.
     * @param startPos the character offset of the first character in the range of text being
     *        cut.
     * @param endPos the offset of the first character past the end of the range of text
     *        being cut.
     * @returns \c True if the text was successfully cut, \c False otherwise.
     */
    boolean cutText (in long startPos, in long endPos);
    /**
     * Excise a range of text from a Text object without copying it into the system clipboard.
     * @param startPos the character offset of the first character in the range of text being
     *        deleted.
     * @param endPos the offset of the first character past the end of the range of text
     *        being deleted.
     * @returns \c True if the text was successfully deleted, \c False otherwise.
     */
    boolean deleteText (in long startPos, in long endPos);
    /**
     * Copy the text contents of the system clipboard, if any, into a Text object, 
     * inserting it at a particular character offset.
     *
     * @param position the character offset before which the text will be inserted.
     * @returns \c True if the text was successfully pasted into the Text object, \c False otherwise.
     */
    boolean pasteText (in long position);

    /**
     * unImplemented:
     *
     * placeholders for future expansion. Note that these are named
     * 'unimplemented5 and unimplemented6' to avoid conflict with 
     * placeholders from Accessibility::Text.
     */
    void unImplemented5 ();
    void unImplemented6 ();
    void unImplemented9 ();
    void unImplemented10 ();
    void unImplemented11 ();
    void unImplemented12 ();
  };
};