001: /*
002: * (C) Copyright IBM Corp. 1998-2004. All Rights Reserved.
003: *
004: * The program is provided "as is" without any warranty express or
005: * implied, including the warranty of non-infringement and the implied
006: * warranties of merchantibility and fitness for a particular purpose.
007: * IBM will not be liable for any damages suffered by you as a result
008: * of using the Program. In no event will IBM be liable for any
009: * special, indirect or consequential damages or lost profits even if
010: * IBM has been advised of the possibility of their occurrence. IBM
011: * will not be liable for any third party claims against you.
012: */
013: package com.ibm.richtext.styledtext;
014:
015: import com.ibm.richtext.textlayout.attributes.AttributeMap;
016:
017: /*
018: Change history:
019:
020: 10/29/96 jef split the character and paragraph style access functions
021: 8/14/96 sfb eliminated StyleSheetIterator
022: 8/21/96 jef completed abstract interface (changed iterator classes etc.)
023: 1/30/97 rtg cleaned up interface, brought in functions from SimpleTextView
024: 7/31/98 jbr switched from Style to AttributeMap
025:
026: */
027:
028: /**
029: * This class is a mutable extension of MConstText. It has methods for
030: * inserting, appending, replacing, and removing styled text. Additionally,
031: * it has methods for modifying paragraph and character styles.
032: * <p>
033: * Styled characters (from another <code>MConstText</code> instance) added
034: * to the text retain their original character styles. The style of plain characters
035: * (specified as a <code>char</code> or <code>char[]</code>) is always
036: * specified explicitly when they are added to the text. MText does not do
037: * character style "propagation", where unstyled characters take on the
038: * style of previous characters. Clients can implement this behavior by
039: * specifying the styles to propagate.
040: * <p>
041: * When unstyled characters are added to the text, their paragraph style
042: * is the paragraph style in effect immediately after the last new character.
043: * If the characters contain paragraph separators, then every new paragraph
044: * will have the same paragraph style. When styled characters are added
045: * to the text, their resulting paragraph style is determined by the
046: * following rule:
047: * <blockquote>
048: * The paragraph styles in the new text
049: * become the paragraph styles in the target text, with the exception of the
050: * last paragraph in the new text, which takes on the paragraph style in
051: * effect immediately after the inserted text.
052: * If the new text is added at the end of the target text, the new text's
053: * paragraph styles take effect in any paragraph affected by the addition.
054: * </blockquote>
055: * For example, suppose there is a single paragraph of text with style 'A',
056: * delimited with a paragraph separator 'P':
057: * <blockquote>
058: * AAAAAAP
059: * </blockquote>
060: * Suppose the following styled paragraphs are inserted into the above text
061: * after the fourth character:
062: * <blockquote>
063: * BBBBPCCCPDDD
064: * </blockquote>
065: * Then the original paragraph style of each character is:
066: * <blockquote>
067: * AAAABBBBPCCCPDDDAAP
068: * </blockquote>
069: * The resulting paragraph styles are:
070: * <blockquote>
071: * BBBBBBBBPCCCPAAAAAP
072: * </blockquote>
073: * Similarly, if characters are deleted, the paragraph style immediately
074: * after the deletion takes effect on the paragraph containing the deletion.
075: * So, if characters 4-16 were deleted in the example above, the paragraph
076: * styles would be:
077: * <blockquote>
078: * AAAAAAP
079: * </blockquote>
080: * This paragraph-style propagation policy is sometimes referred to as <strong>
081: * following styles win</strong>, since styles at the end of the paragraph
082: * become the style for the entire paragraph.
083: * <p>
084: * This class can accumulate a <strong>damaged range</strong> - an interval in
085: * which characters, character styles, or paragraph styles have changed. This is
086: * useful for clients such as text editors which reformat and draw text after
087: * changes. Usually the damaged range is exactly the range of characters
088: * operated upon; however, larger ranges may be damaged if paragraph styles
089: * change.
090: * @see StyleModifier
091: */
092:
093: public abstract class MText extends MConstText {
094: static final String COPYRIGHT = "(C) Copyright IBM Corp. 1998-1999 - All Rights Reserved";
095:
096: protected MText() {
097: }
098:
099: //==================================================
100: // MAIN CHARACTER MODIFICATION FUNCTIONS
101: //==================================================
102: /**
103: * Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters
104: * and styles in <code>srcText</code> in the range [<code>srcStart</code>, <code>srcLimit</code>). <code>srcText</code> is not
105: * modified.
106: * @param start the offset at which the replace operation begins
107: * @param limit the offset at which the replace operation ends. The character and style at
108: * <code>limit</code> is not modified.
109: * @param srcText the source for the new characters and styles
110: * @param srcStart the offset into <code>srcText</code> where new characters and styles will be obtained
111: * @param srcLimit the offset into <code>srcText</code> where the new characters and styles end
112: */
113: public abstract void replace(int start, int limit,
114: MConstText srcText, int srcStart, int srcLimit);
115:
116: /**
117: * Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters
118: * and styles in <code>srcText</code>. <code>srcText</code> is not
119: * modified.
120: * @param start the offset at which the replace operation begins
121: * @param limit the offset at which the replace operation ends. The character and style at
122: * <code>limit</code> is not modified.
123: * @param text the source for the new characters and styles
124: */
125: public abstract void replace(int start, int limit, MConstText text);
126:
127: /**
128: * Replace the characters in the range [<code>start</code>, <code>limit</code>) with the characters
129: * in <code>srcChars</code> in the range [<code>srcStart</code>, <code>srcLimit</code>). New characters take on the style
130: * <code>charsStyle</code>.
131: * <code>srcChars</code> is not modified.
132: * @param start the offset at which the replace operation begins
133: * @param limit the offset at which the replace operation ends. The character at
134: * <code>limit</code> is not modified.
135: * @param srcChars the source for the new characters
136: * @param srcStart the offset into <code>srcChars</code> where new characters will be obtained
137: * @param srcLimit the offset into <code>srcChars</code> where the new characters end
138: * @param charsStyle the style of the new characters
139: */
140: public abstract void replace(int start, int limit, char[] srcChars,
141: int srcStart, int srcLimit, AttributeMap charsStyle);
142:
143: /**
144: * Replace the characters in the range [<code>start</code>, <code>limit</code>) with the character <code>srcChar</code>.
145: * The new character takes on the style <code>charStyle</code>
146: * @param start the offset at which the replace operation begins
147: * @param limit the offset at which the replace operation ends. The character at
148: * <code>limit</code> is not modified.
149: * @param srcChar the new character
150: * @param charStyle the style of the new character
151: */
152: public abstract void replace(int start, int limit, char srcChar,
153: AttributeMap charStyle);
154:
155: /**
156: * Replace the entire contents of this MText (both characters and styles) with
157: * the contents of <code>srcText</code>.
158: * @param srcText the source for the new characters and styles
159: */
160: public abstract void replaceAll(MConstText srcText);
161:
162: /**
163: * Insert the contents of <code>srcText</code> (both characters and styles) into this
164: * MText at the position specified by <code>pos</code>.
165: * @param pos The character offset where the new text is to be inserted.
166: * @param srcText The text to insert. */
167: public abstract void insert(int pos, MConstText srcText);
168:
169: /**
170: * Append the contents of <code>srcText</code> (both characters and styles) to the
171: * end of this MText.
172: * @param srcText The text to append. */
173: public abstract void append(MConstText srcText);
174:
175: /**
176: * Delete the specified range of characters (and styles).
177: * @param start Offset of the first character to delete.
178: * @param limit Offset of the first character after the range to delete. */
179: public abstract void remove(int start, int limit);
180:
181: /**
182: * Delete all characters and styles.
183: */
184: public abstract void remove();
185:
186: /**
187: * Create an MText containing the characters and styles in the range
188: * [<code>start</code>, <code>limit</code>).
189: * @param start offset of first character in the new text
190: * @param limit offset immediately after the last character in the new text
191: * @return an MConstText object containing the characters and styles in the given range
192: */
193: public abstract MText extractWritable(int start, int limit);
194:
195: //==================================================
196: // STORAGE MANAGEMENT
197: //==================================================
198:
199: /**
200: * Minimize the amount of memory used by the MText object.
201: */
202: public abstract void compress();
203:
204: //==================================================
205: // STYLE MODIFICATION
206: //==================================================
207:
208: /**
209: * Set the character style of all characters in the MText object to
210: * <code>AttributeMap.EMPTY_ATTRIBUTE_MAP</code>.
211: */
212: public abstract void removeCharacterStyles();
213:
214: /**
215: * Invoke the given modifier on all character styles from start to limit.
216: * @param modifier the modifier to apply to the range.
217: * @param start the start of the range of text to modify.
218: * @param limit the limit of the range of text to modify.
219: */
220: public abstract void modifyCharacterStyles(int start, int limit,
221: StyleModifier modifier);
222:
223: /**
224: * Invoke the given modifier on all paragraph styles in paragraphs
225: * containing characters in the range [start, limit).
226: * @param modifier the modifier to apply to the range.
227: * @param start the start of the range of text to modify.
228: * @param limit the limit of the range of text to modify.
229: */
230: public abstract void modifyParagraphStyles(int start, int limit,
231: StyleModifier modifier);
232:
233: //==================================================
234: // DAMAGED RANGE
235: //==================================================
236: /**
237: * Reset the damaged range to an empty interval, and begin accumulating the damaged
238: * range. The damaged range includes every index where a character, character style,
239: * or paragraph style has changed.
240: * @see #damagedRangeStart
241: * @see #damagedRangeLimit
242: */
243: public abstract void resetDamagedRange();
244: }
|