Java tutorial
/* * Copyright (c) 1998, 2013, 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(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} 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); } }