/*
 * @(#)$RCSfile: MText.java,v $ $Revision: 1.2 $ $Date: 2002/02/16 03:06:36 $
 *
 * (C) Copyright IBM Corp. 1998-1999.  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 srcText 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 charsStyle 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();
}