| /* | |
| * Copyright (c) 1998, 2023, 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} 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} is constructed with an iterator over | |
| * styled text. The iterator's range should be a single paragraph in the | |
| * text. | |
| * {@code LineBreakMeasurer} 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}, which returns a {@link TextLayout} | |
| * representing the text that fits within the wrapping width. | |
| * The {@code nextLayout} method moves the current position | |
| * to the end of the layout returned from {@code nextLayout}. | |
| * <p> | |
| * {@code LineBreakMeasurer} 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} instances returned by | |
| * {@code LineBreakMeasurer} treat tabs like 0-width spaces. Clients | |
| * who wish to obtain tab-delimited segments for positioning should use | |
| * the overload of {@code nextLayout} which takes a limiting offset | |
| * in the text. | |
| * The limiting offset should be the first character after the tab. | |
| * The {@code TextLayout} 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} which | |
| * takes a {@code boolean} parameter. If this parameter is | |
| * {@code true}, {@code nextLayout} returns | |
| * {@code null} 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} changes, a new | |
| * {@code LineBreakMeasurer} must be constructed to reflect | |
| * the change. (The old {@code LineBreakMeasurer} 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} can be | |
| * 'updated' by calling {@code insertChar} or | |
| * {@code deleteChar}. Updating an existing | |
| * {@code LineBreakMeasurer} 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>{@code | |
| * public void paint(Graphics graphics) { | |
| * | |
| * float dx = 0f, dy = 5f; | |
| * Graphics2D g2d = (Graphics2D)graphics; | |
| * FontRenderContext frc = g2d.getFontRenderContext(); | |
| * | |
| * AttributedString text = new AttributedString("....."); | |
| * AttributedCharacterIterator paragraph = text.getIterator(); | |
| * | |
| * LineBreakMeasurer measurer = new LineBreakMeasurer(paragraph, frc); | |
| * measurer.setPosition(paragraph.getBeginIndex()); | |
| * float wrappingWidth = (float)getSize().width; | |
| * | |
| * while (measurer.getPosition() < paragraph.getEndIndex()) { | |
| * | |
| * TextLayout layout = measurer.nextLayout(wrappingWidth); | |
| * | |
| * dy += (layout.getAscent()); | |
| * float dx = layout.isLeftToRight() ? | |
| * 0 : (wrappingWidth - layout.getAdvance()); | |
| * | |
| * layout.draw(graphics, dx, dy); | |
| * dy += 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>{@code | |
| * 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(Float.valueOf(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} for the specified text. | |
| * | |
| * @param text the text for which this {@code LineBreakMeasurer} | |
| * produces {@code TextLayout} objects; the text must contain | |
| * at least one character; if the text available through | |
| * {@code iter} changes, further calls to this | |
| * {@code LineBreakMeasurer} instance are undefined (except, | |
| * in some cases, when {@code insertChar} or | |
| * {@code deleteChar} 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} and user space | |
| * @see LineBreakMeasurer#insertChar | |
| * @see LineBreakMeasurer#deleteChar | |
| */ | |
| public LineBreakMeasurer(AttributedCharacterIterator text, FontRenderContext frc) { | |
| this(text, BreakIterator.getLineInstance(), frc); | |
| } | |
| /** | |
| * Constructs a {@code LineBreakMeasurer} for the specified text. | |
| * | |
| * @param text the text for which this {@code LineBreakMeasurer} | |
| * produces {@code TextLayout} objects; the text must contain | |
| * at least one character; if the text available through | |
| * {@code iter} changes, further calls to this | |
| * {@code LineBreakMeasurer} instance are undefined (except, | |
| * in some cases, when {@code insertChar} or | |
| * {@code deleteChar} 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} 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}. | |
| * | |
| * @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}. | |
| */ | |
| 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}. | |
| * | |
| * @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} must be | |
| * greater than the current position | |
| * @param requireNextWord if {@code true}, the current position | |
| * that is returned if the entire next word does not fit within | |
| * {@code wrappingWidth}; if {@code false}, 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} | |
| */ | |
| 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}, beginning at the current | |
| * position, which represents the next line fitting within | |
| * {@code wrappingWidth} | |
| */ | |
| 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} | |
| * must be greater than the current position | |
| * @param requireNextWord if {@code true}, and if the entire word | |
| * at the current position does not fit within the wrapping width, | |
| * {@code null} is returned. If {@code false}, a valid | |
| * layout is returned that includes at least the character at the | |
| * current position | |
| * @return a {@code TextLayout}, beginning at the current | |
| * position, that represents the next line fitting within | |
| * {@code wrappingWidth}. If the current position is at the end | |
| * of the text used by this {@code LineBreakMeasurer}, | |
| * {@code null} 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}. | |
| * | |
| * @return the current position of this {@code LineBreakMeasurer} | |
| * @see #setPosition | |
| */ | |
| public int getPosition() { | |
| return pos; | |
| } | |
| /** | |
| * Sets the current position of this {@code LineBreakMeasurer}. | |
| * | |
| * @param newPosition the current position of this | |
| * {@code LineBreakMeasurer}; the position should be within the | |
| * text used to construct this {@code LineBreakMeasurer} (or in | |
| * the text most recently passed to {@code insertChar} | |
| * or {@code deleteChar} | |
| * @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} 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} is less | |
| * than the start of {@code newParagraph} or greater than | |
| * or equal to the end of {@code newParagraph} | |
| * @throws NullPointerException if {@code newParagraph} is | |
| * {@code null} | |
| * @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} 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} is | |
| * less than the start of {@code newParagraph} or greater | |
| * than the end of {@code newParagraph} | |
| * @throws NullPointerException if {@code newParagraph} is | |
| * {@code null} | |
| * @see #insertChar | |
| */ | |
| public void deleteChar(AttributedCharacterIterator newParagraph, | |
| int deletePos) { | |
| measurer.deleteChar(newParagraph, deletePos); | |
| limit = newParagraph.getEndIndex(); | |
| pos = start = newParagraph.getBeginIndex(); | |
| charIter.reset(measurer.getChars(), start); | |
| breakIter.setText(charIter); | |
| } | |
| } |