< 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 >