< prev index next >
src/java.desktop/share/classes/java/awt/font/LineBreakMeasurer.java
Print this page
*** 44,113 ****
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
--- 44,113 ----
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
*** 253,302 ****
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,
--- 253,302 ----
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,
*** 315,351 ****
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;
--- 315,351 ----
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;
*** 403,415 ****
/**
* 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);
}
--- 403,415 ----
/**
* 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);
}
*** 418,439 ****
*
* @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) {
--- 418,439 ----
*
* @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) {
*** 450,498 ****
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) {
--- 450,498 ----
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) {
*** 504,524 ****
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) {
--- 504,524 ----
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) {
< prev index next >