/*
* (C) Copyright IBM Corp. 1998-2004. All Rights Reserved.
*
* The program is provided "as is" without any warranty express or
* implied, including the warranty of non-infringement and the implied
* warranties of merchantibility and fitness for a particular purpose.
* IBM will not be liable for any damages suffered by you as a result
* of using the Program. In no event will IBM be liable for any
* special, indirect or consequential damages or lost profits even if
* IBM has been advised of the possibility of their occurrence. IBM
* will not be liable for any third party claims against you.
*/
package com.ibm.richtext.styledtext;
import com.ibm.richtext.textlayout.attributes.AttributeMap;
/*
Change history:
10/29/96 jef split the character and paragraph style access functions
8/14/96 sfb eliminated StyleSheetIterator
8/21/96 jef completed abstract interface (changed iterator classes etc.)
1/30/97 rtg cleaned up interface, brought in functions from SimpleTextView
7/31/98 jbr switched from Style to AttributeMap
*/
/**
* This class is a mutable extension of MConstText. It has methods for
* inserting, appending, replacing, and removing styled text. Additionally,
* it has methods for modifying paragraph and character styles.
* <p>
* Styled characters (from another <code>MConstText</code> instance) added
* to the text retain their original character styles. The style of plain characters
* (specified as a <code>char</code> or <code>char[]</code>) is always
* specified explicitly when they are added to the text. MText does not do
* character style "propagation", where unstyled characters take on the
* style of previous characters. Clients can implement this behavior by
* specifying the styles to propagate.
* <p>
* When unstyled characters are added to the text, their paragraph style
* is the paragraph style in effect immediately after the last new character.
* If the characters contain paragraph separators, then every new paragraph
* will have the same paragraph style. When styled characters are added
* to the text, their resulting paragraph style is determined by the
* following rule:
* <blockquote>
* The paragraph styles in the new text
* become the paragraph styles in the target text, with the exception of the
* last paragraph in the new text, which takes on the paragraph style in
* effect immediately after the inserted text.
* If the new text is added at the end of the target text, the new text's
* paragraph styles take effect in any paragraph affected by the addition.
* </blockquote>
* For example, suppose there is a single paragraph of text with style 'A',
* delimited with a paragraph separator 'P':
* <blockquote>
* AAAAAAP
* </blockquote>
* Suppose the following styled paragraphs are inserted into the above text
* after the fourth character:
* <blockquote>
* BBBBPCCCPDDD
* </blockquote>
* Then the original paragraph style of each character is:
* <blockquote>
* AAAABBBBPCCCPDDDAAP
* </blockquote>
* The resulting paragraph styles are:
* <blockquote>
* BBBBBBBBPCCCPAAAAAP
* </blockquote>
* Similarly, if characters are deleted, the paragraph style immediately
* after the deletion takes effect on the paragraph containing the deletion.
* So, if characters 4-16 were deleted in the example above, the paragraph
* styles would be:
* <blockquote>
* AAAAAAP
* </blockquote>
* This paragraph-style propagation policy is sometimes referred to as <strong>
* following styles win</strong>, since styles at the end of the paragraph
* become the style for the entire paragraph.
* <p>
* This class can accumulate a <strong>damaged range</strong> - an interval in
* which characters, character styles, or paragraph styles have changed. This is
* useful for clients such as text editors which reformat and draw text after
* changes. Usually the damaged range is exactly the range of characters
* operated upon; however, larger ranges may be damaged if paragraph styles
* change.
* @see StyleModifier
*/
public abstract class MText extends MConstText
{
static final String COPYRIGHT =
"(C) Copyright IBM Corp. 1998-1999 - All Rights Reserved";
protected MText() {
}
//==================================================
// MAIN CHARACTER MODIFICATION FUNCTIONS
//==================================================
/**
* Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters
* and styles in <code>srcText</code> in the range [<code>srcStart</code>, <code>srcLimit</code>). <code>srcText</code> is not
* modified.
* @param start the offset at which the replace operation begins
* @param limit the offset at which the replace operation ends. The character and style at
* <code>limit</code> is not modified.
* @param srcText the source for the new characters and styles
* @param srcStart the offset into <code>srcText</code> where new characters and styles will be obtained
* @param srcLimit the offset into <code>srcText</code> where the new characters and styles end
*/
public abstract void replace(int start, int limit, MConstText srcText, int srcStart, int srcLimit);
/**
* Replace the characters and styles in the range [<code>start</code>, <code>limit</code>) with the characters
* and styles in <code>srcText</code>. <code>srcText</code> is not
* modified.
* @param start the offset at which the replace operation begins
* @param limit the offset at which the replace operation ends. The character and style at
* <code>limit</code> is not modified.
* @param text the source for the new characters and styles
*/
public abstract void replace(int start, int limit, MConstText text);
/**
* Replace the characters in the range [<code>start</code>, <code>limit</code>) with the characters
* in <code>srcChars</code> in the range [<code>srcStart</code>, <code>srcLimit</code>). New characters take on the style
* <code>charsStyle</code>.
* <code>srcChars</code> is not modified.
* @param start the offset at which the replace operation begins
* @param limit the offset at which the replace operation ends. The character at
* <code>limit</code> is not modified.
* @param srcChars the source for the new characters
* @param srcStart the offset into <code>srcChars</code> where new characters will be obtained
* @param srcLimit the offset into <code>srcChars</code> where the new characters end
* @param charsStyle the style of the new characters
*/
public abstract void replace(int start, int limit, char[] srcChars, int srcStart, int srcLimit, AttributeMap charsStyle);
/**
* Replace the characters in the range [<code>start</code>, <code>limit</code>) with the character <code>srcChar</code>.
* The new character takes on the style <code>charStyle</code>
* @param start the offset at which the replace operation begins
* @param limit the offset at which the replace operation ends. The character at
* <code>limit</code> is not modified.
* @param srcChar the new character
* @param charStyle the style of the new character
*/
public abstract void replace(int start, int limit, char srcChar, AttributeMap charStyle);
/**
* Replace the entire contents of this MText (both characters and styles) with
* the contents of <code>srcText</code>.
* @param srcText the source for the new characters and styles
*/
public abstract void replaceAll(MConstText srcText);
/**
* Insert the contents of <code>srcText</code> (both characters and styles) into this
* MText at the position specified by <code>pos</code>.
* @param pos The character offset where the new text is to be inserted.
* @param srcText The text to insert. */
public abstract void insert(int pos, MConstText srcText);
/**
* Append the contents of <code>srcText</code> (both characters and styles) to the
* end of this MText.
* @param srcText The text to append. */
public abstract void append(MConstText srcText);
/**
* Delete the specified range of characters (and styles).
* @param start Offset of the first character to delete.
* @param limit Offset of the first character after the range to delete. */
public abstract void remove(int start, int limit);
/**
* Delete all characters and styles.
*/
public abstract void remove();
/**
* Create an MText containing the characters and styles in the range
* [<code>start</code>, <code>limit</code>).
* @param start offset of first character in the new text
* @param limit offset immediately after the last character in the new text
* @return an MConstText object containing the characters and styles in the given range
*/
public abstract MText extractWritable(int start, int limit);
//==================================================
// STORAGE MANAGEMENT
//==================================================
/**
* Minimize the amount of memory used by the MText object.
*/
public abstract void compress();
//==================================================
// STYLE MODIFICATION
//==================================================
/**
* Set the character style of all characters in the MText object to
* <code>AttributeMap.EMPTY_ATTRIBUTE_MAP</code>.
*/
public abstract void removeCharacterStyles();
/**
* Invoke the given modifier on all character styles from start to limit.
* @param modifier the modifier to apply to the range.
* @param start the start of the range of text to modify.
* @param limit the limit of the range of text to modify.
*/
public abstract void modifyCharacterStyles(int start, int limit, StyleModifier modifier);
/**
* Invoke the given modifier on all paragraph styles in paragraphs
* containing characters in the range [start, limit).
* @param modifier the modifier to apply to the range.
* @param start the start of the range of text to modify.
* @param limit the limit of the range of text to modify.
*/
public abstract void modifyParagraphStyles(int start, int limit, StyleModifier modifier);
//==================================================
// DAMAGED RANGE
//==================================================
/**
* Reset the damaged range to an empty interval, and begin accumulating the damaged
* range. The damaged range includes every index where a character, character style,
* or paragraph style has changed.
* @see #damagedRangeStart
* @see #damagedRangeLimit
*/
public abstract void resetDamagedRange();
}
|