/*

   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

 */
package org.apache.batik.gvt.text;

import java.text.AttributedCharacterIterator;
import java.text.AttributedString;
import java.util.Map;
import java.util.Set;

GVTAttributedCharacterIterator
Used to implement SVG <tspan> and <text>
attributes.  This implementation is designed for efficient support
of per-character attributes (i.e. single character attribute spans).
It supports an extended set of TextAttributes, via inner class
SVGAttributedCharacterIterator.TextAttributes.
Author:
Bill Haneman
Version:
$Id: GVTAttributedCharacterIterator.java 1802297 2017-07-18 13:58:12Z ssteiner $/**
 * GVTAttributedCharacterIterator
 *
 * Used to implement SVG &lt;tspan&gt; and &lt;text&gt;
 * attributes.  This implementation is designed for efficient support
 * of per-character attributes (i.e. single character attribute spans).
 * It supports an extended set of TextAttributes, via inner class
 * SVGAttributedCharacterIterator.TextAttributes.
 *
 * @author <a href="mailto:bill.haneman@ireland.sun.com">Bill Haneman</a>
 * @version $Id: GVTAttributedCharacterIterator.java 1802297 2017-07-18 13:58:12Z ssteiner $
 */

public interface GVTAttributedCharacterIterator extends AttributedCharacterIterator {

    
Sets this iterator's contents to an unattributed copy of String s.
/**
     * Sets this iterator's contents to an unattributed copy of String s.
     */
    void setString(String s);

    
Assigns this iterator's contents to be equivalent to AttributedString s.
/**
     * Assigns this iterator's contents to be equivalent to AttributedString s.
     */
    void setString(AttributedString s);

    
Sets values of a per-character attribute associated with the content
    string.
Characters from beginIndex to endIndex
    (zero-offset) are assigned values for attribute key attr
    from the array attValues.
If the length of attValues is less than character span
    (endIndex-beginIndex) the last value is duplicated;
    if attValues is longer than the character span
    the extra values are ignored.
Note that if either beginIndex or endIndex are outside the bounds
    of the current character array they are clipped accordingly.
/**
     * Sets values of a per-character attribute associated with the content
     *     string.
     * Characters from <code>beginIndex</code> to <code>endIndex</code>
     *     (zero-offset) are assigned values for attribute key <code>attr</code>
     *     from the array <code>attValues.</code>
     * If the length of attValues is less than character span
     *     <code>(endIndex-beginIndex)</code> the last value is duplicated;
     *     if attValues is longer than the character span
     *     the extra values are ignored.
     * Note that if either beginIndex or endIndex are outside the bounds
     *     of the current character array they are clipped accordingly.
     */
    void setAttributeArray(TextAttribute attr,
                        Object[] attValues, int beginIndex, int endIndex);

    //From java.text.AttributedCharacterIterator

    
Get the keys of all attributes defined on the iterator's text range.
/**
     * Get the keys of all attributes defined on the iterator's text range.
     */
    Set getAllAttributeKeys();

    
Get the value of the named attribute for the current
    character.
/**
     * Get the value of the named attribute for the current
     *     character.
     */
    Object getAttribute(AttributedCharacterIterator.Attribute attribute);

    
Returns a map with the attributes defined on the current
character.
/**
     * Returns a map with the attributes defined on the current
     * character.
     */
    Map getAttributes();

    
Get the index of the first character following the
    run with respect to all attributes containing the current
    character.
/**
     * Get the index of the first character following the
     *     run with respect to all attributes containing the current
     *     character.
     */
    int getRunLimit();

    
Get the index of the first character following the
     run with respect to the given attribute containing the current
     character.
/**
     * Get the index of the first character following the
     *      run with respect to the given attribute containing the current
     *      character.
     */
    int getRunLimit(AttributedCharacterIterator.Attribute attribute);

    
Get the index of the first character following the
    run with respect to the given attributes containing the current
    character.
/**
     * Get the index of the first character following the
     *     run with respect to the given attributes containing the current
     *     character.
     */
    int getRunLimit(Set attributes);

    
Get the index of the first character of the run with
   respect to all attributes containing the current character.
/**
     * Get the index of the first character of the run with
     *    respect to all attributes containing the current character.
     */
    int getRunStart();

    
Get the index of the first character of the run with
     respect to the given attribute containing the current character.
Params:
attribute – The attribute for whose appearance the first offset
     is requested./**
     * Get the index of the first character of the run with
     *      respect to the given attribute containing the current character.
     * @param attribute The attribute for whose appearance the first offset
     *      is requested.
     */
    int getRunStart(AttributedCharacterIterator.Attribute attribute);

    
Get the index of the first character of the run with
     respect to the given attributes containing the current character.
Params:
attributes – the Set of attributes which begins at the returned index./**
     * Get the index of the first character of the run with
     *      respect to the given attributes containing the current character.
     * @param attributes the Set of attributes which begins at the returned index.
     */
    int getRunStart(Set attributes);

    //From CharacterIterator

    
Create a copy of this iterator
/**
     * Create a copy of this iterator
     */
    Object clone();

    
Get the character at the current position (as returned
     by getIndex()).

Specified by: java.text.CharacterIterator.
/**
     * Get the character at the current position (as returned
     *      by getIndex()).
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char current();

    
Sets the position to getBeginIndex().
Returns:
the character at the start index of the text.

Specified by: java.text.CharacterIterator./**
     * Sets the position to getBeginIndex().
     * @return the character at the start index of the text.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char first();

    
Get the start index of the text.

Specified by: java.text.CharacterIterator.
/**
     * Get the start index of the text.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    int getBeginIndex();

    
Get the end index of the text.

Specified by: java.text.CharacterIterator.
/**
     * Get the end index of the text.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    int getEndIndex();

    
Get the current index.

Specified by: java.text.CharacterIterator.
/**
     * Get the current index.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    int getIndex();

    
Sets the position to getEndIndex()-1 (getEndIndex() if
the text is empty) and returns the character at that position.

Specified by: java.text.CharacterIterator.
/**
     * Sets the position to getEndIndex()-1 (getEndIndex() if
     * the text is empty) and returns the character at that position.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char last();

    
Increments the iterator's index by one, returning the next character.
Returns:
the character at the new index.

Specified by: java.text.CharacterIterator./**
     * Increments the iterator's index by one, returning the next character.
     * @return the character at the new index.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char next();

    
Decrements the iterator's index by one and returns
the character at the new index.

Specified by: java.text.CharacterIterator.
/**
     * Decrements the iterator's index by one and returns
     * the character at the new index.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char previous();

    
Sets the position to the specified position in the text.
Params:
position – The new (current) index into the text.
Returns:
the character at new index position.

Specified by: java.text.CharacterIterator./**
     * Sets the position to the specified position in the text.
     * @param position The new (current) index into the text.
     * @return the character at new index <em>position</em>.
     * <br><b>Specified by:</b> java.text.CharacterIterator.
     */
    char setIndex(int position);

    //Inner classes:

    
Attribute keys that identify SVG text attributes.  Anchor point for
attribute values of X, Y, and ROTATION is determined by the character's
font and other attributes.
We duplicate the features of java.awt.font.TextAttribute rather than
subclassing because java.awt.font.TextAttribute is final.
/**
     * Attribute keys that identify SVG text attributes.  Anchor point for
     * attribute values of X, Y, and ROTATION is determined by the character's
     * font and other attributes.
     * We duplicate the features of java.awt.font.TextAttribute rather than
     * subclassing because java.awt.font.TextAttribute is <em>final</em>.
     */
    class TextAttribute extends AttributedCharacterIterator.Attribute {

        
Construct a TextAttribute key with name s /** Construct a TextAttribute key with name s */
        public TextAttribute(String s) {
            super(s);
        }

        public static final TextAttribute FLOW_PARAGRAPH =
            new TextAttribute("FLOW_PARAGRAPH");

        public static final TextAttribute FLOW_EMPTY_PARAGRAPH =
            new TextAttribute("FLOW_EMPTY_PARAGRAPH");

        public static final TextAttribute FLOW_LINE_BREAK =
            new TextAttribute("FLOW_LINE_BREAK");

        public static final TextAttribute FLOW_REGIONS =
            new TextAttribute("FLOW_REGIONS");

        public static final TextAttribute LINE_HEIGHT =
            new TextAttribute("LINE_HEIGHT");

        public static final TextAttribute PREFORMATTED =
            new TextAttribute("PREFORMATTED");

        
Attribute span delimiter - new tspan, tref, or textelement./** Attribute span delimiter - new tspan, tref, or textelement.*/
        public static final TextAttribute TEXT_COMPOUND_DELIMITER =
                              new TextAttribute("TEXT_COMPOUND_DELIMITER");

        
Element identifier all chars from same element will share an
 ID. /** Element identifier all chars from same element will share an
         *  ID. */
        public static final TextAttribute TEXT_COMPOUND_ID =
                              new TextAttribute("TEXT_COMPOUND_ID");

        
Anchor type./** Anchor type.*/
        public static final TextAttribute ANCHOR_TYPE =
                              new TextAttribute("ANCHOR_TYPE");

        
Marker attribute indicating explicit glyph layout./** Marker attribute indicating explicit glyph layout.*/
        public static final TextAttribute EXPLICIT_LAYOUT =
                              new TextAttribute("EXPLICIT_LAYOUT");

        
User-space X coordinate for character./** User-space X coordinate for character.*/
        public static final TextAttribute X = new TextAttribute("X");

        
User-space Y coordinate for character./** User-space Y coordinate for character.*/
        public static final TextAttribute Y = new TextAttribute("Y");

        
User-space relative X coordinate for character./** User-space relative X coordinate for character.*/
        public static final TextAttribute DX = new TextAttribute("DX");

        
User-space relative Y coordinate for character./** User-space relative Y coordinate for character.*/
        public static final TextAttribute DY = new TextAttribute("DY");

        
Rotation for character, in degrees./** Rotation for character, in degrees.*/
        public static final TextAttribute ROTATION =
                                          new TextAttribute("ROTATION");

        
All the paint attributes for the text./** All the paint attributes for the text.*/
        public static final TextAttribute PAINT_INFO =
                                          new TextAttribute("PAINT_INFO");

        
Author-expected width for bounding box containing
 all text string glyphs.
/** Author-expected width for bounding box containing
         *  all text string glyphs.
         */
        public static final TextAttribute BBOX_WIDTH =
                                          new TextAttribute("BBOX_WIDTH");

        
Method specified for adjusting text element layout size.
/** Method specified for adjusting text element layout size.
         */
        public static final TextAttribute LENGTH_ADJUST =
                                          new TextAttribute("LENGTH_ADJUST");

        
Convenience flag indicating that non-default glyph spacing is needed.
/** Convenience flag indicating that non-default glyph spacing is needed.
         */
        public static final TextAttribute CUSTOM_SPACING =
                                          new TextAttribute("CUSTOM_SPACING");

        
User-specified inter-glyph kerning value.
/** User-specified inter-glyph kerning value.
         */
        public static final TextAttribute KERNING =
                                          new TextAttribute("KERNING");

        
User-specified inter-glyph spacing value.
/** User-specified inter-glyph spacing value.
         */
        public static final TextAttribute LETTER_SPACING =
                                          new TextAttribute("LETTER_SPACING");

        
User-specified width for whitespace characters.
/** User-specified width for whitespace characters.
         */
        public static final TextAttribute WORD_SPACING =
                                          new TextAttribute("WORD_SPACING");

        
Path along which text is to be laid out /** Path along which text is to be laid out */
        public static final TextAttribute TEXTPATH =
                                          new TextAttribute("TEXTPATH");

        
Font variant to be used for this character span.
See Also:
SMALL_CAPS.SMALL_CAPS/** Font variant to be used for this character span.
         * @see org.apache.batik.gvt.text.GVTAttributedCharacterIterator.TextAttribute#SMALL_CAPS
         */
        public static final TextAttribute FONT_VARIANT =
                                          new TextAttribute("FONT_VARIANT");

        
Baseline adjustment to be applied to this character span.
/** Baseline adjustment to be applied to this character span.
         */
        public static final TextAttribute BASELINE_SHIFT =
                                          new TextAttribute("BASELINE_SHIFT");

        
Directional writing mode applied to this character span.
/** Directional writing mode applied to this character span.
         */
        public static final TextAttribute WRITING_MODE =
                                          new TextAttribute("WRITING_MODE");

        public static final TextAttribute VERTICAL_ORIENTATION =
                                          new TextAttribute("VERTICAL_ORIENTATION");

        public static final TextAttribute VERTICAL_ORIENTATION_ANGLE =
                                          new TextAttribute("VERTICAL_ORIENTATION_ANGLE");

        public static final TextAttribute HORIZONTAL_ORIENTATION_ANGLE =
                                          new TextAttribute("HORIZONTAL_ORIENTATION_ANGLE");

        public static final TextAttribute GVT_FONT_FAMILIES =
                       new TextAttribute("GVT_FONT_FAMILIES");

        public static final TextAttribute GVT_FONTS =
                                          new TextAttribute("GVT_FONTS");

        public static final TextAttribute GVT_FONT =
                                          new TextAttribute("GVT_FONT");

        public static final TextAttribute ALT_GLYPH_HANDLER =
                                          new TextAttribute("ALT_GLYPH_HANDLER");

        public static final TextAttribute BIDI_LEVEL =
                                          new TextAttribute("BIDI_LEVEL");

        public static final TextAttribute CHAR_INDEX =
                                          new TextAttribute("CHAR_INDEX");

        public static final TextAttribute ARABIC_FORM =
                                          new TextAttribute("ARABIC_FORM");

        public static final TextAttribute SCRIPT =
                                          new TextAttribute("SCRIPT");

        public static final TextAttribute LANGUAGE =
                                          new TextAttribute("LANGUAGE");

        // VALUES

        
Value for WRITING_MODE indicating left-to-right /** Value for WRITING_MODE indicating left-to-right */
        public static final Integer WRITING_MODE_LTR = 0x1;

        
Value for WRITING_MODE indicating right-to-left /** Value for WRITING_MODE indicating right-to-left */
        public static final Integer WRITING_MODE_RTL = 0x2;

        
Value for WRITING_MODE indicating top-to-botton /** Value for WRITING_MODE indicating top-to-botton */
        public static final Integer WRITING_MODE_TTB = 0x3;

        
Value for VERTICAL_ORIENTATION indicating an angle /** Value for VERTICAL_ORIENTATION indicating an angle */
        public static final Integer ORIENTATION_ANGLE = 0x1;

        
Value for VERTICAL_ORIENTATION indicating auto /** Value for VERTICAL_ORIENTATION indicating auto */
        public static final Integer ORIENTATION_AUTO = 0x2;

        
Value for FONT_VARIANT specifying small caps /** Value for FONT_VARIANT specifying small caps */
        public static final Integer SMALL_CAPS = 0x10;

        
Value for UNDERLINE specifying underlining-on /** Value for UNDERLINE specifying underlining-on */
        public static final Integer UNDERLINE_ON =
                            java.awt.font.TextAttribute.UNDERLINE_ON;

        
Value for OVERLINE specifying overlining-on /** Value for OVERLINE specifying overlining-on */
        public static final Boolean OVERLINE_ON = Boolean.TRUE;

        
Value for STRIKETHROUGH specifying strikethrough-on /** Value for STRIKETHROUGH specifying strikethrough-on */
        public static final Boolean STRIKETHROUGH_ON =
                            java.awt.font.TextAttribute.STRIKETHROUGH_ON;

        
Value for LENGTH_ADJUST specifying adjustment to inter-glyph spacing /** Value for LENGTH_ADJUST specifying adjustment to inter-glyph spacing */
        public static final Integer ADJUST_SPACING =
                0x0;

        
Value for LENGTH_ADJUST specifying overall scaling of layout outlines /** Value for LENGTH_ADJUST specifying overall scaling of layout outlines */
        public static final Integer ADJUST_ALL =
                0x01;

        // constant values for the arabic glyph forms
        public static final Integer ARABIC_NONE = 0x0;
        public static final Integer ARABIC_ISOLATED = 0x1;
        public static final Integer ARABIC_TERMINAL = 0x2;
        public static final Integer ARABIC_INITIAL = 0x3;
        public static final Integer ARABIC_MEDIAL = 0x4;

    }

    
Interface for helper class which mutates the attributes of an
AttributedCharacterIterator.
Typically used to convert location and rotation attributes to
TextAttribute.TRANSFORM attributes, or convert between implementations
of AttributedCharacterIterator.Attribute.
/**
     * Interface for helper class which mutates the attributes of an
     * AttributedCharacterIterator.
     * Typically used to convert location and rotation attributes to
     * TextAttribute.TRANSFORM attributes, or convert between implementations
     * of AttributedCharacterIterator.Attribute.
     */
    interface AttributeFilter {

        
Modify an AttributedCharacterIterator's attributes systematically.
Usually returns a copy since AttributedCharacterIterator instances
are often immutable.  The effect of the attribute modification
is implementation dependent.
Params:
aci – an AttributedCharacterIterator whose attributes are
    to be modified.
Returns:
an instance of AttributedCharacterIterator with mutated
    attributes./**
         * Modify an AttributedCharacterIterator's attributes systematically.
         * Usually returns a copy since AttributedCharacterIterator instances
         * are often immutable.  The effect of the attribute modification
         * is implementation dependent.
         * @param aci an AttributedCharacterIterator whose attributes are
         *     to be modified.
         * @return an instance of AttributedCharacterIterator with mutated
         *     attributes.
         */
        AttributedCharacterIterator
            mutateAttributes(AttributedCharacterIterator aci);

    }
}