/*

 * Copyright (c) 1998, 2001, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved

 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved

 *

 * The original version of this source code and documentation is

 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary

 * of IBM. These materials are provided under terms of a License

 * Agreement between Taligent and Sun. This technology is protected

 * by multiple US and International patents.

 *

 * This notice and attribution to Taligent may not be removed.

 * Taligent is a registered trademark of Taligent, Inc.

 *

 */

package java.awt.font;

import java.text.BreakIterator;

import java.text.CharacterIterator;

import java.text.AttributedCharacterIterator;

import java.awt.font.FontRenderContext;

/**

 * The <code>LineBreakMeasurer</code> class allows styled text to be

 * broken into lines (or segments) that fit within a particular visual

 * advance.  This is useful for clients who wish to display a paragraph of

 * text that fits within a specific width, called the <b>wrapping

 * width</b>.

 * <p>

 * <code>LineBreakMeasurer</code> is constructed with an iterator over

 * styled text.  The iterator's range should be a single paragraph in the

 * text.

 * <code>LineBreakMeasurer</code> maintains a position in the text for the

 * start of the next text segment.  Initially, this position is the

 * start of text.  Paragraphs are assigned an overall direction (either

 * left-to-right or right-to-left) according to the bidirectional

 * formatting rules.  All segments obtained from a paragraph have the

 * same direction as the paragraph.

 * <p>

 * Segments of text are obtained by calling the method

 * <code>nextLayout</code>, which returns a {@link TextLayout}

 * representing the text that fits within the wrapping width.

 * The <code>nextLayout</code> method moves the current position

 * to the end of the layout returned from <code>nextLayout</code>.

 * <p>

 * <code>LineBreakMeasurer</code> implements the most commonly used

 * line-breaking policy: Every word that fits within the wrapping

 * width is placed on the line. If the first word does not fit, then all

 * of the characters that fit within the wrapping width are placed on the

 * line.  At least one character is placed on each line.

 * <p>

 * The <code>TextLayout</code> instances returned by

 * <code>LineBreakMeasurer</code> treat tabs like 0-width spaces.  Clients

 * who wish to obtain tab-delimited segments for positioning should use

 * the overload of <code>nextLayout</code> which takes a limiting offset

 * in the text.

 * The limiting offset should be the first character after the tab.

 * The <code>TextLayout</code> objects returned from this method end

 * at the limit provided (or before, if the text between the current

 * position and the limit won't fit entirely within the  wrapping

 * width).

 * <p>

 * Clients who are laying out tab-delimited text need a slightly

 * different line-breaking policy after the first segment has been

 * placed on a line.  Instead of fitting partial words in the

 * remaining space, they should place words which don't fit in the

 * remaining space entirely on the next line.  This change of policy

 * can be requested in the overload of <code>nextLayout</code> which

 * takes a <code>boolean</code> parameter.  If this parameter is

 * <code>true</code>, <code>nextLayout</code> returns

 * <code>null</code> if the first word won't fit in

 * the given space.  See the tab sample below.

 * <p>

 * In general, if the text used to construct the

 * <code>LineBreakMeasurer</code> changes, a new

 * <code>LineBreakMeasurer</code> must be constructed to reflect

 * the change.  (The old <code>LineBreakMeasurer</code> continues to

 * function properly, but it won't be aware of the text change.)

 * Nevertheless, if the text change is the insertion or deletion of a

 * single character, an existing <code>LineBreakMeasurer</code> can be

 * 'updated' by calling <code>insertChar</code> or

 * <code>deleteChar</code>. Updating an existing

 * <code>LineBreakMeasurer</code> is much faster than creating a new one.

 * Clients who modify text based on user typing should take advantage

 * of these methods.

 * <p>

 * <strong>Examples</strong>:<p>

 * Rendering a paragraph in a component

 * <blockquote>

 * <pre>

 * public void paint(Graphics graphics) {

 *

 *     Point2D pen = new Point2D(10, 20);

 *     Graphics2D g2d = (Graphics2D)graphics;

 *     FontRenderContext frc = g2d.getFontRenderContext();

 *

 *     // let styledText be an AttributedCharacterIterator containing at least

 *     // one character

 *

 *     LineBreakMeasurer measurer = new LineBreakMeasurer(styledText, frc);

 *     float wrappingWidth = getSize().width - 15;

 *

 *     while (measurer.getPosition() < fStyledText.length()) {

 *

 *         TextLayout layout = measurer.nextLayout(wrappingWidth);

 *

 *         pen.y += (layout.getAscent());

 *         float dx = layout.isLeftToRight() ?

 *             0 : (wrappingWidth - layout.getAdvance());

 *

 *         layout.draw(graphics, pen.x + dx, pen.y);

 *         pen.y += layout.getDescent() + layout.getLeading();

 *     }

 * }

 * </pre>

 * </blockquote>

 * <p>

 * Rendering text with tabs.  For simplicity, the overall text

 * direction is assumed to be left-to-right

 * <blockquote>

 * <pre>

 * public void paint(Graphics graphics) {

 *

 *     float leftMargin = 10, rightMargin = 310;

 *     float[] tabStops = { 100, 250 };

 *

 *     // assume styledText is an AttributedCharacterIterator, and the number

 *     // of tabs in styledText is tabCount

 *

 *     int[] tabLocations = new int[tabCount+1];

 *

 *     int i = 0;

 *     for (char c = styledText.first(); c != styledText.DONE; c = styledText.next()) {

 *         if (c == '\t') {

 *             tabLocations[i++] = styledText.getIndex();

 *         }

 *     }

 *     tabLocations[tabCount] = styledText.getEndIndex() - 1;

 *

 *     // Now tabLocations has an entry for every tab's offset in

 *     // the text.  For convenience, the last entry is tabLocations

 *     // is the offset of the last character in the text.

 *

 *     LineBreakMeasurer measurer = new LineBreakMeasurer(styledText);

 *     int currentTab = 0;

 *     float verticalPos = 20;

 *

 *     while (measurer.getPosition() < styledText.getEndIndex()) {

 *

 *         // Lay out and draw each line.  All segments on a line

 *         // must be computed before any drawing can occur, since

 *         // we must know the largest ascent on the line.

 *         // TextLayouts are computed and stored in a Vector;

 *         // their horizontal positions are stored in a parallel

 *         // Vector.

 *

 *         // lineContainsText is true after first segment is drawn

 *         boolean lineContainsText = false;

 *         boolean lineComplete = false;

 *         float maxAscent = 0, maxDescent = 0;

 *         float horizontalPos = leftMargin;

 *         Vector layouts = new Vector(1);

 *         Vector penPositions = new Vector(1);

 *

 *         while (!lineComplete) {

 *             float wrappingWidth = rightMargin - horizontalPos;

 *             TextLayout layout =

 *                     measurer.nextLayout(wrappingWidth,

 *                                         tabLocations[currentTab]+1,

 *                                         lineContainsText);

 *

 *             // layout can be null if lineContainsText is true

 *             if (layout != null) {

 *                 layouts.addElement(layout);

 *                 penPositions.addElement(new Float(horizontalPos));

 *                 horizontalPos += layout.getAdvance();

 *                 maxAscent = Math.max(maxAscent, layout.getAscent());

 *                 maxDescent = Math.max(maxDescent,

 *                     layout.getDescent() + layout.getLeading());

 *             } else {

 *                 lineComplete = true;

 *             }

 *

 *             lineContainsText = true;

 *

 *             if (measurer.getPosition() == tabLocations[currentTab]+1) {

 *                 currentTab++;

 *             }

 *

 *             if (measurer.getPosition() == styledText.getEndIndex())

 *                 lineComplete = true;

 *             else if (horizontalPos >= tabStops[tabStops.length-1])

 *                 lineComplete = true;

 *

 *             if (!lineComplete) {

 *                 // move to next tab stop

 *                 int j;

 *                 for (j=0; horizontalPos >= tabStops[j]; j++) {}

 *                 horizontalPos = tabStops[j];

 *             }

 *         }

 *

 *         verticalPos += maxAscent;

 *

 *         Enumeration layoutEnum = layouts.elements();

 *         Enumeration positionEnum = penPositions.elements();

 *

 *         // now iterate through layouts and draw them

 *         while (layoutEnum.hasMoreElements()) {

 *             TextLayout nextLayout = (TextLayout) layoutEnum.nextElement();

 *             Float nextPosition = (Float) positionEnum.nextElement();

 *             nextLayout.draw(graphics, nextPosition.floatValue(), verticalPos);

 *         }

 *

 *         verticalPos += maxDescent;

 *     }

 * }

 * </pre>

 * </blockquote>

 * @see TextLayout

 */

public final class LineBreakMeasurer {

    private BreakIterator breakIter;

    private int start;

    private int pos;

    private int limit;

    private TextMeasurer measurer;

    private CharArrayIterator charIter;

    /**

     * Constructs a <code>LineBreakMeasurer</code> for the specified text.

     *

     * @param text the text for which this <code>LineBreakMeasurer</code>

     *       produces <code>TextLayout</code> objects; the text must contain

     *       at least one character; if the text available through

     *       <code>iter</code> changes, further calls to this

     *       <code>LineBreakMeasurer</code> instance are undefined (except,

     *       in some cases, when <code>insertChar</code> or

     *       <code>deleteChar</code> are invoked afterward - see below)

     * @param frc contains information about a graphics device which is

     *       needed to measure the text correctly;

     *       text measurements can vary slightly depending on the

     *       device resolution, and attributes such as antialiasing; this

     *       parameter does not specify a translation between the

     *       <code>LineBreakMeasurer</code> and user space

     * @see LineBreakMeasurer#insertChar

     * @see LineBreakMeasurer#deleteChar

     */

    public LineBreakMeasurer(AttributedCharacterIterator text, FontRenderContext frc) {

        this(text, BreakIterator.getLineInstance(), frc);

    }

    /**

     * Constructs a <code>LineBreakMeasurer</code> for the specified text.

     *

     * @param text the text for which this <code>LineBreakMeasurer</code>

     *     produces <code>TextLayout</code> objects; the text must contain

     *     at least one character; if the text available through

     *     <code>iter</code> changes, further calls to this

     *     <code>LineBreakMeasurer</code> instance are undefined (except,

     *     in some cases, when <code>insertChar</code> or

     *     <code>deleteChar</code> are invoked afterward - see below)

     * @param breakIter the {@link BreakIterator} which defines line

     *     breaks

     * @param frc contains information about a graphics device which is

     *       needed to measure the text correctly;

     *       text measurements can vary slightly depending on the

     *       device resolution, and attributes such as antialiasing; this

     *       parameter does not specify a translation between the

     *       <code>LineBreakMeasurer</code> and user space

     * @throws IllegalArgumentException if the text has less than one character

     * @see LineBreakMeasurer#insertChar

     * @see LineBreakMeasurer#deleteChar

     */

    public LineBreakMeasurer(AttributedCharacterIterator text,

                             BreakIterator breakIter,

                             FontRenderContext frc) {

        if (text.getEndIndex() - text.getBeginIndex() < 1) {

            throw new IllegalArgumentException("Text must contain at least one character.");

        }

        this.breakIter = breakIter;

        this.measurer = new TextMeasurer(text, frc);

        this.limit = text.getEndIndex();

        this.pos = this.start = text.getBeginIndex();

        charIter = new CharArrayIterator(measurer.getChars(), this.start);

        this.breakIter.setText(charIter);

    }

    /**

     * Returns the position at the end of the next layout.  Does NOT

     * update the current position of this <code>LineBreakMeasurer</code>.

     *

     * @param wrappingWidth the maximum visible advance permitted for

     *    the text in the next layout

     * @return an offset in the text representing the limit of the

     *    next <code>TextLayout</code>.

     */

    public int nextOffset(float wrappingWidth) {

        return nextOffset(wrappingWidth, limit, false);

    }

    /**

     * Returns the position at the end of the next layout.  Does NOT

     * update the current position of this <code>LineBreakMeasurer</code>.

     *

     * @param wrappingWidth the maximum visible advance permitted for

     *    the text in the next layout

     * @param offsetLimit the first character that can not be included

     *    in the next layout, even if the text after the limit would fit

     *    within the wrapping width; <code>offsetLimit</code> must be

     *    greater than the current position

     * @param requireNextWord if <code>true</code>, the current position

     *    that is returned if the entire next word does not fit within

     *    <code>wrappingWidth</code>; if <code>false</code>, the offset

     *    returned is at least one greater than the current position

     * @return an offset in the text representing the limit of the

     *    next <code>TextLayout</code>

     */

    public int nextOffset(float wrappingWidth, int offsetLimit,

                          boolean requireNextWord) {

        int nextOffset = pos;

        if (pos < limit) {

            if (offsetLimit <= pos) {

                    throw new IllegalArgumentException("offsetLimit must be after current position");

            }

            int charAtMaxAdvance =

                            measurer.getLineBreakIndex(pos, wrappingWidth);

            if (charAtMaxAdvance == limit) {

                nextOffset = limit;

            }

            else if (Character.isWhitespace(measurer.getChars()[charAtMaxAdvance-start])) {

                nextOffset = breakIter.following(charAtMaxAdvance);

            }

            else {

            // Break is in a word;  back up to previous break.

                // NOTE:  I think that breakIter.preceding(limit) should be

                // equivalent to breakIter.last(), breakIter.previous() but

                // the authors of BreakIterator thought otherwise...

                // If they were equivalent then the first branch would be

                // unnecessary.

                int testPos = charAtMaxAdvance + 1;

                if (testPos == limit) {

                    breakIter.last();

                    nextOffset = breakIter.previous();

                }

                else {

                    nextOffset = breakIter.preceding(testPos);

                }

                if (nextOffset <= pos) {

                    // first word doesn't fit on line

                    if (requireNextWord) {

                        nextOffset = pos;

                    }

                    else {

                        nextOffset = Math.max(pos+1, charAtMaxAdvance);

                    }

                }

            }

        }

        if (nextOffset > offsetLimit) {

            nextOffset = offsetLimit;

        }

        return nextOffset;

    }

    /**

     * Returns the next layout, and updates the current position.

     *

     * @param wrappingWidth the maximum visible advance permitted for

     *     the text in the next layout

     * @return a <code>TextLayout</code>, beginning at the current

     *     position, which represents the next line fitting within

     *     <code>wrappingWidth</code>

     */

    public TextLayout nextLayout(float wrappingWidth) {

        return nextLayout(wrappingWidth, limit, false);

    }

    /**

     * Returns the next layout, and updates the current position.

     *

     * @param wrappingWidth the maximum visible advance permitted

     *    for the text in the next layout

     * @param offsetLimit the first character that can not be

     *    included in the next layout, even if the text after the limit

     *    would fit within the wrapping width; <code>offsetLimit</code>

     *    must be greater than the current position

     * @param requireNextWord if <code>true</code>, and if the entire word

     *    at the current position does not fit within the wrapping width,

     *    <code>null</code> is returned. If <code>false</code>, a valid

     *    layout is returned that includes at least the character at the

     *    current position

     * @return a <code>TextLayout</code>, beginning at the current

     *    position, that represents the next line fitting within

     *    <code>wrappingWidth</code>.  If the current position is at the end

     *    of the text used by this <code>LineBreakMeasurer</code>,

     *    <code>null</code> is returned

     */

    public TextLayout nextLayout(float wrappingWidth, int offsetLimit,

                                 boolean requireNextWord) {

        if (pos < limit) {

            int layoutLimit = nextOffset(wrappingWidth, offsetLimit, requireNextWord);

            if (layoutLimit == pos) {

                return null;

            }

            TextLayout result = measurer.getLayout(pos, layoutLimit);

            pos = layoutLimit;

            return result;

        } else {

            return null;

        }

    }

    /**

     * Returns the current position of this <code>LineBreakMeasurer</code>.

     *

     * @return the current position of this <code>LineBreakMeasurer</code>

     * @see #setPosition

     */

    public int getPosition() {

        return pos;

    }

    /**

     * Sets the current position of this <code>LineBreakMeasurer</code>.

     *

     * @param newPosition the current position of this

     *    <code>LineBreakMeasurer</code>; the position should be within the

     *    text used to construct this <code>LineBreakMeasurer</code> (or in

     *    the text most recently passed to <code>insertChar</code>

     *    or <code>deleteChar</code>

     * @see #getPosition

     */

    public void setPosition(int newPosition) {

        if (newPosition < start || newPosition > limit) {

            throw new IllegalArgumentException("position is out of range");

        }

        pos = newPosition;

    }

    /**

     * Updates this <code>LineBreakMeasurer</code> after a single

     * character is inserted into the text, and sets the current

     * position to the beginning of the paragraph.

     *

     * @param newParagraph the text after the insertion

     * @param insertPos the position in the text at which the character

     *    is inserted

     * @throws IndexOutOfBoundsException if <code>insertPos</code> is less

     *         than the start of <code>newParagraph</code> or greater than

     *         or equal to the end of <code>newParagraph</code>

     * @throws NullPointerException if <code>newParagraph</code> is

     *         <code>null</code>

     * @see #deleteChar

     */

    public void insertChar(AttributedCharacterIterator newParagraph,

                           int insertPos) {

        measurer.insertChar(newParagraph, insertPos);

        limit = newParagraph.getEndIndex();

        pos = start = newParagraph.getBeginIndex();

        charIter.reset(measurer.getChars(), newParagraph.getBeginIndex());

        breakIter.setText(charIter);

    }

    /**

     * Updates this <code>LineBreakMeasurer</code> after a single

     * character is deleted from the text, and sets the current

     * position to the beginning of the paragraph.

     * @param newParagraph the text after the deletion

     * @param deletePos the position in the text at which the character

     *    is deleted

     * @throws IndexOutOfBoundsException if <code>deletePos</code> is

     *         less than the start of <code>newParagraph</code> or greater

     *         than the end of <code>newParagraph</code>

     * @throws NullPointerException if <code>newParagraph</code> is

     *         <code>null</code>

     * @see #insertChar

     */

    public void deleteChar(AttributedCharacterIterator newParagraph,

                           int deletePos) {

        measurer.deleteChar(newParagraph, deletePos);

        limit = newParagraph.getEndIndex();

        pos = start = newParagraph.getBeginIndex();