2008-05-28 Mark Doffman <mark.doffman@codethink.co.uk>

[platform/core/uifw/at-spi2-atk.git] / idl / Accessibility_EditableText.idl

diff --git a/idl/Accessibility_EditableText.idl b/idl/Accessibility_EditableText.idl
index dc8218f..6e878ad 100644 (file)
--- a/idl/Accessibility_EditableText.idl
+++ b/idl/Accessibility_EditableText.idl
@@ -24,14 +24,94 @@
 
 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 {
-
-    void    setTextContents (in string newContents);
-    void    insertText (in long position, in string text, in long length);
+    /** 
+     * 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);
-    void    cutText (in long startPos, in long endPos);
-    void    deleteText (in long startPos, in long endPos);
-    void    pasteText (in long position);
+    /**
+     * 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 ();
   };
 };