jars/icu4j-4_2_1-src/src/com/ibm/richtext/styledtext/MText.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.styledtext;\r
  14 \r
  15 import com.ibm.richtext.textlayout.attributes.AttributeMap;\r
  16 \r
  17 /*\r
  18     Change history:\r
  19 \r
  20     10/29/96 jef    split the character and paragraph style access functions\r
  21     8/14/96 sfb     eliminated StyleSheetIterator\r
  22     8/21/96 jef        completed abstract interface (changed iterator classes etc.)\r
  23     1/30/97 rtg     cleaned up interface, brought in functions from SimpleTextView\r
  24     7/31/98 jbr switched from Style to AttributeMap\r
  25 \r
  26 */\r
  27 \r
  28 /**\r
  29  * This class is a mutable extension of MConstText.  It has methods for\r
  30  * inserting, appending, replacing, and removing styled text.  Additionally,\r
  31  * it has methods for modifying paragraph and character styles.\r
  32  * <p>\r
  33  * Styled characters (from another <code>MConstText</code> instance) added\r
  34  * to the text retain their original character styles.  The style of plain characters\r
  35  * (specified as a <code>char</code> or <code>char[]</code>) is always\r
  36  * specified explicitly when they are added to the text.  MText does not do\r
  37  * character style "propagation", where unstyled characters take on the\r
  38  * style of previous characters.  Clients can implement this behavior by\r
  39  * specifying the styles to propagate.\r
  40  * <p>\r
  41  * When unstyled characters are added to the text, their paragraph style\r
  42  * is the paragraph style in effect immediately after the last new character.\r
  43  * If the characters contain paragraph separators, then every new paragraph\r
  44  * will have the same paragraph style.  When styled characters are added\r
  45  * to the text, their resulting paragraph style is determined by the\r
  46  * following rule:\r
  47  * <blockquote>\r
  48  * The paragraph styles in the new text\r
  49  * become the paragraph styles in the target text, with the exception of the\r
  50  * last paragraph in the new text, which takes on the paragraph style in\r
  51  * effect immediately after the inserted text.\r
  52  * If the new text is added at the end of the target text, the new text's\r
  53  * paragraph styles take effect in any paragraph affected by the addition.\r
  54  * </blockquote>\r
  55  * For example, suppose there is a single paragraph of text with style 'A',\r
  56  * delimited with a paragraph separator 'P':\r
  57  * <blockquote>\r
  58  * AAAAAAP\r
  59  * </blockquote>\r
  60  * Suppose the following styled paragraphs are inserted into the above text\r
  61  * after the fourth character:\r
  62  * <blockquote>\r
  63  * BBBBPCCCPDDD\r
  64  * </blockquote>\r
  65  * Then the original paragraph style of each character is:\r
  66  * <blockquote>\r
  67  * AAAABBBBPCCCPDDDAAP\r
  68  * </blockquote>\r
  69  * The resulting paragraph styles are:\r
  70  * <blockquote>\r
  71  * BBBBBBBBPCCCPAAAAAP\r
  72  * </blockquote>\r
  73  * Similarly, if characters are deleted, the paragraph style immediately\r
  74  * after the deletion takes effect on the paragraph containing the deletion.\r
  75  * So, if characters 4-16 were deleted in the example above, the paragraph\r
  76  * styles would be:\r
  77  * <blockquote>\r
  78  * AAAAAAP\r
  79  * </blockquote>\r
  80  * This paragraph-style propagation policy is sometimes referred to as <strong>\r
  81  * following styles win</strong>, since styles at the end of the paragraph\r
  82  * become the style for the entire paragraph.\r
  83  * <p>\r
  84  * This class can accumulate a <strong>damaged range</strong> - an interval in\r
  85  * which characters, character styles, or paragraph styles have changed.  This is\r
  86  * useful for clients such as text editors which reformat and draw text after\r
  87  * changes.  Usually the damaged range is exactly the range of characters\r
  88  * operated upon;  however, larger ranges may be damaged if paragraph styles\r
  89  * change.\r
  90  * @see StyleModifier\r
  91  */\r
  92 \r
  93 public abstract class MText extends MConstText\r
  94 {\r
  95     static final String COPYRIGHT =\r
  96                 "(C) Copyright IBM Corp. 1998-1999 - All Rights Reserved";\r
  97     protected MText() {\r
  98     }\r
  99 \r
 100 //==================================================\r
 101 // MAIN CHARACTER MODIFICATION FUNCTIONS\r
 102 //==================================================\r
 103 /**\r
 104 * Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters\r
 105 * and styles in <code>srcText</code> in the range [<code>srcStart</code>, <code>srcLimit</code>).  <code>srcText</code> is not\r
 106 * modified.\r
 107 * @param start the offset at which the replace operation begins\r
 108 * @param limit the offset at which the replace operation ends.  The character and style at\r
 109 * <code>limit</code> is not modified.\r
 110 * @param srcText the source for the new characters and styles\r
 111 * @param srcStart the offset into <code>srcText</code> where new characters and styles will be obtained\r
 112 * @param srcLimit the offset into <code>srcText</code> where the new characters and styles end\r
 113 */\r
 114     public abstract void replace(int start, int limit, MConstText srcText, int srcStart, int srcLimit);\r
 115 \r
 116 /**\r
 117 * Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters\r
 118 * and styles in <code>srcText</code>.  <code>srcText</code> is not\r
 119 * modified.\r
 120 * @param start the offset at which the replace operation begins\r
 121 * @param limit the offset at which the replace operation ends.  The character and style at\r
 122 * <code>limit</code> is not modified.\r
 123 * @param text the source for the new characters and styles\r
 124 */\r
 125     public abstract void replace(int start, int limit, MConstText text);\r
 126 \r
 127 /**\r
 128 * Replace the characters in the range [<code>start</code>, <code>limit</code>) with the characters\r
 129 * in <code>srcChars</code> in the range [<code>srcStart</code>, <code>srcLimit</code>).  New characters take on the style\r
 130 * <code>charsStyle</code>.\r
 131 * <code>srcChars</code> is not modified.\r
 132 * @param start the offset at which the replace operation begins\r
 133 * @param limit the offset at which the replace operation ends.  The character at\r
 134 * <code>limit</code> is not modified.\r
 135 * @param srcChars the source for the new characters\r
 136 * @param srcStart the offset into <code>srcChars</code> where new characters will be obtained\r
 137 * @param srcLimit the offset into <code>srcChars</code> where the new characters end\r
 138 * @param charsStyle the style of the new characters\r
 139 */\r
 140     public abstract void replace(int start, int limit, char[] srcChars, int srcStart, int srcLimit, AttributeMap charsStyle);\r
 141 \r
 142 /**\r
 143 * Replace the characters in the range [<code>start</code>, <code>limit</code>) with the character <code>srcChar</code>.\r
 144 * The new character takes on the style <code>charStyle</code>\r
 145 * @param start the offset at which the replace operation begins\r
 146 * @param limit the offset at which the replace operation ends.  The character at\r
 147 * <code>limit</code> is not modified.\r
 148 * @param srcChar the new character\r
 149 * @param charStyle the style of the new character\r
 150 */\r
 151     public abstract void replace(int start, int limit, char srcChar, AttributeMap charStyle);\r
 152 \r
 153 /**\r
 154 * Replace the entire contents of this MText (both characters and styles) with\r
 155 * the contents of <code>srcText</code>.\r
 156 * @param srcText the source for the new characters and styles\r
 157 */\r
 158     public abstract void replaceAll(MConstText srcText);\r
 159 \r
 160 /**\r
 161 * Insert the contents of <code>srcText</code> (both characters and styles) into this\r
 162 * MText at the position specified by <code>pos</code>.\r
 163 * @param pos The character offset where the new text is to be inserted.\r
 164 * @param srcText The text to insert. */\r
 165     public abstract void insert(int pos, MConstText srcText);\r
 166 \r
 167 /**\r
 168 * Append the contents of <code>srcText</code> (both characters and styles) to the\r
 169 * end of this MText.\r
 170 * @param srcText The text to append. */\r
 171     public abstract void append(MConstText srcText);\r
 172 \r
 173 /**\r
 174 * Delete the specified range of characters (and styles).\r
 175 * @param start Offset of the first character to delete.\r
 176 * @param limit Offset of the first character after the range to delete. */\r
 177     public abstract void remove(int start, int limit);\r
 178 \r
 179 /**\r
 180 * Delete all characters and styles.\r
 181 */\r
 182     public abstract void remove();\r
 183 \r
 184 /**\r
 185 * Create an MText containing the characters and styles in the range\r
 186 * [<code>start</code>, <code>limit</code>).\r
 187 * @param start offset of first character in the new text\r
 188 * @param limit offset immediately after the last character in the new text\r
 189 * @return an MConstText object containing the characters and styles in the given range\r
 190 */\r
 191     public abstract MText extractWritable(int start, int limit);\r
 192 \r
 193 \r
 194 //==================================================\r
 195 // STORAGE MANAGEMENT\r
 196 //==================================================\r
 197 \r
 198 /**\r
 199 * Minimize the amount of memory used by the MText object.\r
 200 */\r
 201     public abstract void compress();\r
 202 \r
 203 //==================================================\r
 204 // STYLE MODIFICATION\r
 205 //==================================================\r
 206 \r
 207 /**\r
 208 * Set the character style of all characters in the MText object to\r
 209 * <code>AttributeMap.EMPTY_ATTRIBUTE_MAP</code>.\r
 210 */\r
 211     public abstract void removeCharacterStyles();\r
 212 \r
 213 /**\r
 214 * Invoke the given modifier on all character styles from start to limit.\r
 215 * @param modifier the modifier to apply to the range.\r
 216 * @param start the start of the range of text to modify.\r
 217 * @param limit the limit of the range of text to modify.\r
 218 */\r
 219     public abstract void modifyCharacterStyles(int start, int limit, StyleModifier modifier);\r
 220 \r
 221 /**\r
 222 * Invoke the given modifier on all paragraph styles in paragraphs\r
 223 * containing characters in the range [start, limit).\r
 224 * @param modifier the modifier to apply to the range.\r
 225 * @param start the start of the range of text to modify.\r
 226 * @param limit the limit of the range of text to modify.\r
 227 */\r
 228     public abstract void modifyParagraphStyles(int start, int limit, StyleModifier modifier);\r
 229 \r
 230 //==================================================\r
 231 // DAMAGED RANGE\r
 232 //==================================================\r
 233 /**\r
 234 * Reset the damaged range to an empty interval, and begin accumulating the damaged\r
 235 * range.  The damaged range includes every index where a character, character style,\r
 236 * or paragraph style has changed.\r
 237 * @see #damagedRangeStart\r
 238 * @see #damagedRangeLimit\r
 239 */\r
 240     public abstract void resetDamagedRange();\r
 241 }\r