Back to index...

	/*
	* 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</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>{@code
	* 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>{@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</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();

	charIter.reset(measurer.getChars(), start);
	breakIter.setText(charIter);
	}
	}

Back to index...