jars/icu4j-4_2_1-src/src/com/ibm/richtext/textpanel/MTextPanel.java

   1 /*\r
   2  * (C) Copyright IBM Corp. 1998-2004.  All Rights Reserved.\r
   3  *\r
   4  * The program is provided "as is" without any warranty express or\r
   5  * implied, including the warranty of non-infringement and the implied\r
   6  * warranties of merchantibility and fitness for a particular purpose.\r
   7  * IBM will not be liable for any damages suffered by you as a result\r
   8  * of using the Program. In no event will IBM be liable for any\r
   9  * special, indirect or consequential damages or lost profits even if\r
  10  * IBM has been advised of the possibility of their occurrence. IBM\r
  11  * will not be liable for any third party claims against you.\r
  12  */\r
  13 package com.ibm.richtext.textpanel;\r
  14 \r
  15 import com.ibm.richtext.textlayout.attributes.AttributeMap;\r
  16 \r
  17 import com.ibm.richtext.styledtext.StyleModifier;\r
  18 import com.ibm.richtext.styledtext.MConstText;\r
  19 \r
  20 /**\r
  21  * MTextPanel is implemented by Components which provide selectable\r
  22  * editable styled text.\r
  23  * <p>\r
  24  * Implementations of MTextPanel provide a simple, standard user interface\r
  25  * for text editing.  MTextPanel supplies scrollable display, typing, \r
  26  * arrow-key support, character selection, word-\r
  27  * and sentence-selection (by double-clicking and triple-clicking, \r
  28  * respectively), text styles, clipboard operations (cut, copy and paste)\r
  29  * and a log of changes for undo-redo.\r
  30  * <p>\r
  31  * MTextPanel implementations do not provide user interface elements\r
  32  * such as an edit menu or style menu.  This support is provided in\r
  33  * different packages, and is implemented with MTextPanel's API.\r
  34  * MTextPanel includes methods for setting selections and styles on text,\r
  35  * and using the clipboard and command-log functionality.\r
  36  * MTextPanel's API for selection and text handling is similar to that\r
  37  * of <tt>java.awt.TextArea</tt> and\r
  38  * <tt>java.awt.TextComponent</tt>.\r
  39  * <p>\r
  40  * MTextPanel supports bidirectional and complex text.  In bidirectional\r
  41  * text, offsets at direction boundaries have dual carets.  Logical selection\r
  42  * is used, so selections across run directions may not be contiguous in\r
  43  * display.\r
  44  */\r
  45 public interface MTextPanel {\r
  46     \r
  47     static final String COPYRIGHT =\r
  48                 "(C) Copyright IBM Corp. 1998-1999 - All Rights Reserved";\r
  49 \r
  50     /**\r
  51      * This value is returned from <tt>getCharacterStyleOverSelection</tt>\r
  52      * and <tt>getParagraphStyleOverSelection</tt> to indicate that the\r
  53      * selection range contains multiple values for a key.\r
  54      * <p>\r
  55      * There is no reason for this Object ever to appear in an AttributeMap\r
  56      * as a value.  Obviously, if it does there will be no way to distinguish\r
  57      * between multiple values across the selection and a consistent value of\r
  58      * <tt>MULTIPLE_VALUES</tt> for the key.\r
  59      * @see #getCharacterStyleOverSelection\r
  60      * @see #getParagraphStyleOverSelection\r
  61      */\r
  62     public static final Object MULTIPLE_VALUES = new Object();\r
  63     \r
  64     /**\r
  65      * Add the given TextPanelListener to the listeners which will\r
  66      * receive update notifications from this MTextPanel.\r
  67      * @param listener the listener to add\r
  68      */\r
  69     public void addListener(TextPanelListener listener);\r
  70 \r
  71     /**\r
  72      * Remove the given TextPanelListener from the listeners which will\r
  73      * receive update notifications from this MTextPanel.\r
  74      * @param listener the listener to remove\r
  75      */\r
  76     public void removeListener(TextPanelListener listener);\r
  77 \r
  78     /**\r
  79      * Set the document to <tt>newText</tt>.  This operation\r
  80      * modifies the text in the MTextPanel.  It does not modify or adopt\r
  81      * <tt>newText</tt>.  This method sets the selection an insertion point at\r
  82      * the end of the text.\r
  83      * @param newText the text which will replace the current text.\r
  84      */\r
  85     public void setText(MConstText newText);\r
  86     \r
  87     /**\r
  88      * Append the given text to the end of the document.  Equivalent to\r
  89      * <tt>insert(newText, getTextLength())</tt>.\r
  90      * @param newText the text to append to the document\r
  91      */\r
  92     public void append(MConstText newText);\r
  93     \r
  94     /**\r
  95      * Insert the given text into the document at the given position.\r
  96      * Equivalent to\r
  97      * <tt>replaceRange(newText, position, position)</tt>.\r
  98      * @param newText the text to insert into the document.\r
  99      * @param position the position in the document where the\r
 100      *     text will be inserted\r
 101      */\r
 102     public void insert(MConstText newText, int position);\r
 103 \r
 104     /**\r
 105      * Replace the given range with <tt>newText</tt>.  After this\r
 106      * operation the selection range is an insertion point at the\r
 107      * end of the new text.\r
 108      * @param newText the text with which to replace the range\r
 109      * @param start the beginning of the range to replace\r
 110      * @param end the end of the range to replace\r
 111      */\r
 112     public void replaceRange(MConstText newText, int start, int end);\r
 113 \r
 114     /**\r
 115      * Return the length of the text document in the MTextPanel.\r
 116      * @return the length of the text document in the MTextPanel\r
 117      */\r
 118     public int getTextLength();\r
 119 \r
 120     /**\r
 121      * Return the text document in the MTextPanel.\r
 122      * @return the text document in the MTextPanel.\r
 123      */\r
 124     public MConstText getText();\r
 125     \r
 126 //============\r
 127 // Selection Access\r
 128 //============\r
 129 \r
 130     /**\r
 131      * Return the offset of the start of the selection.\r
 132      */\r
 133     public int getSelectionStart();\r
 134 \r
 135     /**\r
 136      * Return the offset of the end of the selection.\r
 137      */\r
 138     public int getSelectionEnd();\r
 139     \r
 140     /**\r
 141      * Set the beginning of the selection range.  This is\r
 142      * equivalent to <tt>select(selectionStart, getSelectionEnd())</tt>.\r
 143      * @param selectionStart the start of the new selection range\r
 144      */\r
 145     public void setSelectionStart(int selectionStart);\r
 146     \r
 147     /**\r
 148      * Set the end of the selection range.  This is\r
 149      * equivalent to <tt>select(getSelectionStart(), selectionEnd)</tt>.\r
 150      * @param selectionEnd the end of the new selection range\r
 151      */\r
 152     public void setSelectionEnd(int selectionEnd);\r
 153     \r
 154     /**\r
 155      * Set the selection range to an insertion point at the given\r
 156      * offset.  This is equivalent to\r
 157      * <tt>select(position, position)</tt>.\r
 158      * @param position the offset of the new insertion point\r
 159      */\r
 160     public void setCaretPosition(int position);\r
 161     \r
 162     /**\r
 163      * Set the selection range to the given range.  The range start\r
 164      * is pinned between 0 and the text length;  the range end is pinned\r
 165      * between the range start and the end of the text.  These semantics\r
 166      * are identical to those of <tt>java.awt.TextComponent</tt>.\r
 167      * This method has no effect if the text is not selectable.\r
 168      * @param selectionStart the beginning of the selection range\r
 169      * @param selectionEnd the end of the selection range\r
 170      */\r
 171     public void select(int selectionStart, int selectionEnd);\r
 172     \r
 173     /**\r
 174      * Select all of the text in the document.  This method has no effect if\r
 175      * the text is not selectable.\r
 176      */\r
 177     public void selectAll();\r
 178     \r
 179 \r
 180 //============\r
 181 // Format Width\r
 182 //============\r
 183 \r
 184     /**\r
 185      * Return the total format width, in pixels.  The format width is the\r
 186      * width to which text is wrapped.\r
 187      * @return the format width\r
 188      */\r
 189     public int getFormatWidth();\r
 190     \r
 191     /**\r
 192      * Return true if the paragraph at the given offset is left-to-right.\r
 193      * @param offset an offset in the text\r
 194      * @return true if the paragraph at the given offset is left-to-right\r
 195      */\r
 196     public boolean paragraphIsLeftToRight(int offset);\r
 197 \r
 198     /**\r
 199      * Return true if there is a change which can be undone.\r
 200      * @return true if there is a change which can be undone.\r
 201      */\r
 202     public boolean canUndo();\r
 203     \r
 204     /**\r
 205      * Return true if there is a change which can be redone.\r
 206      * @return true if there is a change which can be redone.\r
 207      */\r
 208     public boolean canRedo();\r
 209     \r
 210     /**\r
 211      * Return true if the clipboard contains contents which could be\r
 212      * transfered into the text.\r
 213      * @return true if the clipboard has text content.\r
 214      */\r
 215     public boolean clipboardNotEmpty();\r
 216     \r
 217 \r
 218 //============\r
 219 // Styles\r
 220 //============\r
 221 \r
 222     /**\r
 223      * Return an AttributeMap of keys with default values.  The default\r
 224      * values are used when displaying text for values which are not\r
 225      * specified in the text.\r
 226      * @return an AttributeMap of default key-value pairs\r
 227      */\r
 228     public AttributeMap getDefaultValues();\r
 229     \r
 230     /**\r
 231      * This method inspects the character style runs in the selection\r
 232      * range (or the typing style at the insertion point).  It returns:\r
 233      * <ul>\r
 234      * <li>The value of <tt>key</tt>, if the value of <tt>key</tt>\r
 235      * is the same in all of the style runs in the selection, or</li>\r
 236      * <li><tt>MULTIPLE_VALUES</tt>, if two or more style runs have different \r
 237      * values for <tt>key</tt>.</li>\r
 238      * </ul>\r
 239      * If a style run does not contain <tt>key</tt>,\r
 240      * its value is considered to be the default style for <tt>key</tt>,\r
 241      * as defined by the default values AttributeMap.  Note that if\r
 242      * <tt>key</tt> does not have a default value this method may return\r
 243      * null.\r
 244      * This method is useful for configuring style menus.\r
 245      * @param key the key used to retrieve values for comparison\r
 246      * @see #MULTIPLE_VALUES\r
 247      */\r
 248     public Object getCharacterStyleOverSelection(Object key);\r
 249     \r
 250     /**\r
 251      * This method inspects the paragraph style runs in the selection\r
 252      * range (or the typing style at the insertion point).  It returns:\r
 253      * <ul>\r
 254      * <li>The value of <tt>key</tt>, if the value of <tt>key</tt>\r
 255      * is the same in all of the style runs in the selection, or</li>\r
 256      * <li><tt>MULTIPLE_VALUES</tt>, if two or more style runs have \r
 257      * different values for <tt>key</tt>.</li>\r
 258      * </ul>\r
 259      * If a style run does not contain <tt>key</tt>,\r
 260      * its value is considered to be the default style for <tt>key</tt>,\r
 261      * as defined by the default values AttributeMap.  Note that if\r
 262      * <tt>key</tt> does not have a default value this method may return\r
 263      * null.\r
 264      * This method is useful for configuring style menus.\r
 265      * @param key the key used to retrieve values for comparison\r
 266      * @see #MULTIPLE_VALUES\r
 267      */\r
 268     public Object getParagraphStyleOverSelection(Object key);\r
 269     \r
 270     /**\r
 271      * Remove the selected text from the document and place it\r
 272      * on the clipboard.  This method has no effect if the text\r
 273      * is not editable, or if no text is selected.\r
 274      */\r
 275     public void cut();\r
 276     \r
 277     /**\r
 278      * Place the selected text on the clipboard.  This method has\r
 279      * no effect if no text is selected.\r
 280      */\r
 281     public void copy();\r
 282     \r
 283     /**\r
 284      * Replace the currently selected text with the text on the clipboard.\r
 285      * This method has no effect if the text is not editable, or if no\r
 286      * text is on the clipboard.\r
 287      */\r
 288     public void paste();\r
 289     \r
 290     /**\r
 291      * Remove selected text from the document, without altering the clipboard.\r
 292      * This method has no effect if the\r
 293      * text is not editable.\r
 294      */\r
 295     public void clear();\r
 296     \r
 297     /**\r
 298      * Undo the most recent text change.  This method has no effect if\r
 299      * there is no change to undo.\r
 300      */\r
 301     public void undo();\r
 302     \r
 303     /**\r
 304      * Redo the most recent text change.  This method has no effect if\r
 305      * there is no change to redo.\r
 306      */\r
 307     public void redo();\r
 308     \r
 309     /**\r
 310      * Return the number of commands the command log can hold.\r
 311      * @return the number of commands the command log can hold\r
 312      */\r
 313     public int getCommandLogSize();\r
 314     \r
 315     /**\r
 316      * Set the number of commands the command log can hold.  All\r
 317      * redoable commands are removed when this method is called.\r
 318      * @param size the number of commands kept in the command log\r
 319      */\r
 320     public void setCommandLogSize(int size);\r
 321     \r
 322     /**\r
 323      * Remove all commands from the command log.\r
 324      */\r
 325     public void clearCommandLog();\r
 326     \r
 327     /**\r
 328      * Modify the character styles on the selected characters.  If no characters\r
 329      * are selected, modify the typing style.\r
 330      * @param modifier the StyleModifier with which to modify the styles\r
 331      */\r
 332     public void modifyCharacterStyleOnSelection(StyleModifier modifier);\r
 333     \r
 334     /**\r
 335      * Modify the paragraph styles in paragraphs containing selected characters, or\r
 336      * the paragraph containing the insertion point.\r
 337      * @param modifier the StyleModifier with which to modify the styles\r
 338      */\r
 339     public void modifyParagraphStyleOnSelection(StyleModifier modifier);\r
 340     \r
 341     /**\r
 342      * Return the KeyRemap used to process key events.\r
 343      * @return the key remap used to process key events\r
 344      * @see #setKeyRemap\r
 345      */\r
 346     public KeyRemap getKeyRemap();\r
 347     \r
 348     /**\r
 349      * Use the given KeyRemap to map key events to characters.\r
 350      * Only key\r
 351      * events are affected by the remap;  other text entering the\r
 352      * control (via the clipboard, for example) is not affected\r
 353      * by the KeyRemap.\r
 354      * <p>\r
 355      * Do not pass <tt>null</tt> to this method to leave key\r
 356      * events unmapped.  Instead, use <tt>KeyRemap.getIdentityRemap()</tt>\r
 357      * @param remap the KeyRemap to use for mapping key events to characters\r
 358      * @exception java.lang.NullPointerException if parameter is null\r
 359      * @see KeyRemap\r
 360      */\r
 361     public void setKeyRemap(KeyRemap remap);\r
 362     \r
 363     /**\r
 364      * Return the modification flag of the current text change.\r
 365      * @see #setModified\r
 366      */\r
 367     public boolean isModified();\r
 368     \r
 369     /**\r
 370      * Set the modification flag of the current text change.\r
 371      */\r
 372     public void setModified(boolean modified);\r
 373 }\r