1 /*
2 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /*
27 * (C) Copyright Taligent, Inc. 1996 - 1997, All Rights Reserved
28 * (C) Copyright IBM Corp. 1996 - 1998, All Rights Reserved
29 *
30 * The original version of this source code and documentation is
31 * copyrighted and owned by Taligent, Inc., a wholly-owned subsidiary
32 * of IBM. These materials are provided under terms of a License
33 * Agreement between Taligent and Sun. This technology is protected
34 * by multiple US and International patents.
35 *
36 * This notice and attribution to Taligent may not be removed.
37 * Taligent is a registered trademark of Taligent, Inc.
38 *
39 */
40
41 package java.awt.font;
42
43 import java.text.BreakIterator;
44 import java.text.CharacterIterator;
45 import java.text.AttributedCharacterIterator;
46 import java.awt.font.FontRenderContext;
47
48 /**
49 * The {@code LineBreakMeasurer} class allows styled text to be
50 * broken into lines (or segments) that fit within a particular visual
51 * advance. This is useful for clients who wish to display a paragraph of
52 * text that fits within a specific width, called the <b>wrapping
53 * width</b>.
54 * <p>
55 * {@code LineBreakMeasurer} is constructed with an iterator over
56 * styled text. The iterator's range should be a single paragraph in the
57 * text.
58 * {@code LineBreakMeasurer} maintains a position in the text for the
59 * start of the next text segment. Initially, this position is the
60 * start of text. Paragraphs are assigned an overall direction (either
61 * left-to-right or right-to-left) according to the bidirectional
62 * formatting rules. All segments obtained from a paragraph have the
63 * same direction as the paragraph.
64 * <p>
65 * Segments of text are obtained by calling the method
66 * {@code nextLayout}, which returns a {@link TextLayout}
67 * representing the text that fits within the wrapping width.
68 * The {@code nextLayout} method moves the current position
69 * to the end of the layout returned from {@code nextLayout}.
70 * <p>
71 * {@code LineBreakMeasurer} implements the most commonly used
72 * line-breaking policy: Every word that fits within the wrapping
73 * width is placed on the line. If the first word does not fit, then all
74 * of the characters that fit within the wrapping width are placed on the
75 * line. At least one character is placed on each line.
76 * <p>
77 * The {@code TextLayout} instances returned by
78 * {@code LineBreakMeasurer} treat tabs like 0-width spaces. Clients
79 * who wish to obtain tab-delimited segments for positioning should use
80 * the overload of {@code nextLayout} which takes a limiting offset
81 * in the text.
82 * The limiting offset should be the first character after the tab.
83 * The {@code TextLayout} objects returned from this method end
84 * at the limit provided (or before, if the text between the current
85 * position and the limit won't fit entirely within the wrapping
86 * width).
87 * <p>
88 * Clients who are laying out tab-delimited text need a slightly
89 * different line-breaking policy after the first segment has been
90 * placed on a line. Instead of fitting partial words in the
91 * remaining space, they should place words which don't fit in the
92 * remaining space entirely on the next line. This change of policy
93 * can be requested in the overload of {@code nextLayout} which
94 * takes a {@code boolean} parameter. If this parameter is
95 * {@code true}, {@code nextLayout} returns
96 * {@code null} if the first word won't fit in
97 * the given space. See the tab sample below.
98 * <p>
99 * In general, if the text used to construct the
100 * {@code LineBreakMeasurer} changes, a new
101 * {@code LineBreakMeasurer} must be constructed to reflect
102 * the change. (The old {@code LineBreakMeasurer} continues to
103 * function properly, but it won't be aware of the text change.)
104 * Nevertheless, if the text change is the insertion or deletion of a
105 * single character, an existing {@code LineBreakMeasurer} can be
106 * 'updated' by calling {@code insertChar} or
107 * {@code deleteChar}. Updating an existing
108 * {@code LineBreakMeasurer} is much faster than creating a new one.
109 * Clients who modify text based on user typing should take advantage
110 * of these methods.
111 * <p>
112 * <strong>Examples</strong>:<p>
113 * Rendering a paragraph in a component
114 * <blockquote>
115 * <pre>{@code
116 * public void paint(Graphics graphics) {
117 *
118 * float dx = 0f, dy = 5f;
119 * Graphics2D g2d = (Graphics2D)graphics;
120 * FontRenderContext frc = g2d.getFontRenderContext();
121 *
122 * AttributedString text = new AttributedString(".....");
123 * AttributedCharacterIterator paragraph = text.getIterator();
124 *
125 * LineBreakMeasurer measurer = new LineBreakMeasurer(paragraph, frc);
126 * measurer.setPosition(paragraph.getBeginIndex());
127 * float wrappingWidth = (float)getSize().width;
128 *
129 * while (measurer.getPosition() < paragraph.getEndIndex()) {
130 *
131 * TextLayout layout = measurer.nextLayout(wrappingWidth);
132 *
133 * dy += (layout.getAscent());
134 * float dx = layout.isLeftToRight() ?
135 * 0 : (wrappingWidth - layout.getAdvance());
136 *
137 * layout.draw(graphics, dx, dy);
138 * dy += layout.getDescent() + layout.getLeading();
139 * }
140 * }
141 * }</pre>
142 * </blockquote>
143 * <p>
144 * Rendering text with tabs. For simplicity, the overall text
145 * direction is assumed to be left-to-right
146 * <blockquote>
147 * <pre>{@code
148 * public void paint(Graphics graphics) {
149 *
150 * float leftMargin = 10, rightMargin = 310;
151 * float[] tabStops = { 100, 250 };
152 *
153 * // assume styledText is an AttributedCharacterIterator, and the number
154 * // of tabs in styledText is tabCount
155 *
156 * int[] tabLocations = new int[tabCount+1];
157 *
158 * int i = 0;
159 * for (char c = styledText.first(); c != styledText.DONE; c = styledText.next()) {
160 * if (c == '\t') {
161 * tabLocations[i++] = styledText.getIndex();
162 * }
163 * }
164 * tabLocations[tabCount] = styledText.getEndIndex() - 1;
165 *
166 * // Now tabLocations has an entry for every tab's offset in
167 * // the text. For convenience, the last entry is tabLocations
168 * // is the offset of the last character in the text.
169 *
170 * LineBreakMeasurer measurer = new LineBreakMeasurer(styledText);
171 * int currentTab = 0;
172 * float verticalPos = 20;
173 *
174 * while (measurer.getPosition() < styledText.getEndIndex()) {
175 *
176 * // Lay out and draw each line. All segments on a line
177 * // must be computed before any drawing can occur, since
178 * // we must know the largest ascent on the line.
179 * // TextLayouts are computed and stored in a Vector;
180 * // their horizontal positions are stored in a parallel
181 * // Vector.
182 *
183 * // lineContainsText is true after first segment is drawn
184 * boolean lineContainsText = false;
185 * boolean lineComplete = false;
186 * float maxAscent = 0, maxDescent = 0;
187 * float horizontalPos = leftMargin;
188 * Vector layouts = new Vector(1);
189 * Vector penPositions = new Vector(1);
190 *
191 * while (!lineComplete) {
192 * float wrappingWidth = rightMargin - horizontalPos;
193 * TextLayout layout =
194 * measurer.nextLayout(wrappingWidth,
195 * tabLocations[currentTab]+1,
196 * lineContainsText);
197 *
198 * // layout can be null if lineContainsText is true
199 * if (layout != null) {
200 * layouts.addElement(layout);
201 * penPositions.addElement(new Float(horizontalPos));
202 * horizontalPos += layout.getAdvance();
203 * maxAscent = Math.max(maxAscent, layout.getAscent());
204 * maxDescent = Math.max(maxDescent,
205 * layout.getDescent() + layout.getLeading());
206 * } else {
207 * lineComplete = true;
208 * }
209 *
210 * lineContainsText = true;
211 *
212 * if (measurer.getPosition() == tabLocations[currentTab]+1) {
213 * currentTab++;
214 * }
215 *
216 * if (measurer.getPosition() == styledText.getEndIndex())
217 * lineComplete = true;
218 * else if (horizontalPos >= tabStops[tabStops.length-1])
219 * lineComplete = true;
220 *
221 * if (!lineComplete) {
222 * // move to next tab stop
223 * int j;
224 * for (j=0; horizontalPos >= tabStops[j]; j++) {}
225 * horizontalPos = tabStops[j];
226 * }
227 * }
228 *
229 * verticalPos += maxAscent;
230 *
231 * Enumeration layoutEnum = layouts.elements();
232 * Enumeration positionEnum = penPositions.elements();
233 *
234 * // now iterate through layouts and draw them
235 * while (layoutEnum.hasMoreElements()) {
236 * TextLayout nextLayout = (TextLayout) layoutEnum.nextElement();
237 * Float nextPosition = (Float) positionEnum.nextElement();
238 * nextLayout.draw(graphics, nextPosition.floatValue(), verticalPos);
239 * }
240 *
241 * verticalPos += maxDescent;
242 * }
243 * }
244 * }</pre>
245 * </blockquote>
246 * @see TextLayout
247 */
248
249 public final class LineBreakMeasurer {
250
251 private BreakIterator breakIter;
252 private int start;
253 private int pos;
254 private int limit;
255 private TextMeasurer measurer;
256 private CharArrayIterator charIter;
257
258 /**
259 * Constructs a {@code LineBreakMeasurer} for the specified text.
260 *
261 * @param text the text for which this {@code LineBreakMeasurer}
262 * produces {@code TextLayout} objects; the text must contain
263 * at least one character; if the text available through
264 * {@code iter} changes, further calls to this
265 * {@code LineBreakMeasurer} instance are undefined (except,
266 * in some cases, when {@code insertChar} or
267 * {@code deleteChar} are invoked afterward - see below)
268 * @param frc contains information about a graphics device which is
269 * needed to measure the text correctly;
270 * text measurements can vary slightly depending on the
271 * device resolution, and attributes such as antialiasing; this
272 * parameter does not specify a translation between the
273 * {@code LineBreakMeasurer} and user space
274 * @see LineBreakMeasurer#insertChar
275 * @see LineBreakMeasurer#deleteChar
276 */
277 public LineBreakMeasurer(AttributedCharacterIterator text, FontRenderContext frc) {
278 this(text, BreakIterator.getLineInstance(), frc);
279 }
280
281 /**
282 * Constructs a {@code LineBreakMeasurer} for the specified text.
283 *
284 * @param text the text for which this {@code LineBreakMeasurer}
285 * produces {@code TextLayout} objects; the text must contain
286 * at least one character; if the text available through
287 * {@code iter} changes, further calls to this
288 * {@code LineBreakMeasurer} instance are undefined (except,
289 * in some cases, when {@code insertChar} or
290 * {@code deleteChar} are invoked afterward - see below)
291 * @param breakIter the {@link BreakIterator} which defines line
292 * breaks
293 * @param frc contains information about a graphics device which is
294 * needed to measure the text correctly;
295 * text measurements can vary slightly depending on the
296 * device resolution, and attributes such as antialiasing; this
297 * parameter does not specify a translation between the
298 * {@code LineBreakMeasurer} and user space
299 * @throws IllegalArgumentException if the text has less than one character
300 * @see LineBreakMeasurer#insertChar
301 * @see LineBreakMeasurer#deleteChar
302 */
303 public LineBreakMeasurer(AttributedCharacterIterator text,
304 BreakIterator breakIter,
305 FontRenderContext frc) {
306 if (text.getEndIndex() - text.getBeginIndex() < 1) {
307 throw new IllegalArgumentException("Text must contain at least one character.");
308 }
309
310 this.breakIter = breakIter;
311 this.measurer = new TextMeasurer(text, frc);
312 this.limit = text.getEndIndex();
313 this.pos = this.start = text.getBeginIndex();
314
315 charIter = new CharArrayIterator(measurer.getChars(), this.start);
316 this.breakIter.setText(charIter);
317 }
318
319 /**
320 * Returns the position at the end of the next layout. Does NOT
321 * update the current position of this {@code LineBreakMeasurer}.
322 *
323 * @param wrappingWidth the maximum visible advance permitted for
324 * the text in the next layout
325 * @return an offset in the text representing the limit of the
326 * next {@code TextLayout}.
327 */
328 public int nextOffset(float wrappingWidth) {
329 return nextOffset(wrappingWidth, limit, false);
330 }
331
332 /**
333 * Returns the position at the end of the next layout. Does NOT
334 * update the current position of this {@code LineBreakMeasurer}.
335 *
336 * @param wrappingWidth the maximum visible advance permitted for
337 * the text in the next layout
338 * @param offsetLimit the first character that can not be included
339 * in the next layout, even if the text after the limit would fit
340 * within the wrapping width; {@code offsetLimit} must be
341 * greater than the current position
342 * @param requireNextWord if {@code true}, the current position
343 * that is returned if the entire next word does not fit within
344 * {@code wrappingWidth}; if {@code false}, the offset
345 * returned is at least one greater than the current position
346 * @return an offset in the text representing the limit of the
347 * next {@code TextLayout}
348 */
349 public int nextOffset(float wrappingWidth, int offsetLimit,
350 boolean requireNextWord) {
351
352 int nextOffset = pos;
353
354 if (pos < limit) {
355 if (offsetLimit <= pos) {
356 throw new IllegalArgumentException("offsetLimit must be after current position");
357 }
358
359 int charAtMaxAdvance =
360 measurer.getLineBreakIndex(pos, wrappingWidth);
361
362 if (charAtMaxAdvance == limit) {
363 nextOffset = limit;
364 }
365 else if (Character.isWhitespace(measurer.getChars()[charAtMaxAdvance-start])) {
366 nextOffset = breakIter.following(charAtMaxAdvance);
367 }
368 else {
369 // Break is in a word; back up to previous break.
370
371 // NOTE: I think that breakIter.preceding(limit) should be
372 // equivalent to breakIter.last(), breakIter.previous() but
373 // the authors of BreakIterator thought otherwise...
374 // If they were equivalent then the first branch would be
375 // unnecessary.
376 int testPos = charAtMaxAdvance + 1;
377 if (testPos == limit) {
378 breakIter.last();
379 nextOffset = breakIter.previous();
380 }
381 else {
382 nextOffset = breakIter.preceding(testPos);
383 }
384
385 if (nextOffset <= pos) {
386 // first word doesn't fit on line
387 if (requireNextWord) {
388 nextOffset = pos;
389 }
390 else {
391 nextOffset = Math.max(pos+1, charAtMaxAdvance);
392 }
393 }
394 }
395 }
396
397 if (nextOffset > offsetLimit) {
398 nextOffset = offsetLimit;
399 }
400
401 return nextOffset;
402 }
403
404 /**
405 * Returns the next layout, and updates the current position.
406 *
407 * @param wrappingWidth the maximum visible advance permitted for
408 * the text in the next layout
409 * @return a {@code TextLayout}, beginning at the current
410 * position, which represents the next line fitting within
411 * {@code wrappingWidth}
412 */
413 public TextLayout nextLayout(float wrappingWidth) {
414 return nextLayout(wrappingWidth, limit, false);
415 }
416
417 /**
418 * Returns the next layout, and updates the current position.
419 *
420 * @param wrappingWidth the maximum visible advance permitted
421 * for the text in the next layout
422 * @param offsetLimit the first character that can not be
423 * included in the next layout, even if the text after the limit
424 * would fit within the wrapping width; {@code offsetLimit}
425 * must be greater than the current position
426 * @param requireNextWord if {@code true}, and if the entire word
427 * at the current position does not fit within the wrapping width,
428 * {@code null} is returned. If {@code false}, a valid
429 * layout is returned that includes at least the character at the
430 * current position
431 * @return a {@code TextLayout}, beginning at the current
432 * position, that represents the next line fitting within
433 * {@code wrappingWidth}. If the current position is at the end
434 * of the text used by this {@code LineBreakMeasurer},
435 * {@code null} is returned
436 */
437 public TextLayout nextLayout(float wrappingWidth, int offsetLimit,
438 boolean requireNextWord) {
439
440 if (pos < limit) {
441 int layoutLimit = nextOffset(wrappingWidth, offsetLimit, requireNextWord);
442 if (layoutLimit == pos) {
443 return null;
444 }
445
446 TextLayout result = measurer.getLayout(pos, layoutLimit);
447 pos = layoutLimit;
448
449 return result;
450 } else {
451 return null;
452 }
453 }
454
455 /**
456 * Returns the current position of this {@code LineBreakMeasurer}.
457 *
458 * @return the current position of this {@code LineBreakMeasurer}
459 * @see #setPosition
460 */
461 public int getPosition() {
462 return pos;
463 }
464
465 /**
466 * Sets the current position of this {@code LineBreakMeasurer}.
467 *
468 * @param newPosition the current position of this
469 * {@code LineBreakMeasurer}; the position should be within the
470 * text used to construct this {@code LineBreakMeasurer} (or in
471 * the text most recently passed to {@code insertChar}
472 * or {@code deleteChar}
473 * @see #getPosition
474 */
475 public void setPosition(int newPosition) {
476 if (newPosition < start || newPosition > limit) {
477 throw new IllegalArgumentException("position is out of range");
478 }
479 pos = newPosition;
480 }
481
482 /**
483 * Updates this {@code LineBreakMeasurer} after a single
484 * character is inserted into the text, and sets the current
485 * position to the beginning of the paragraph.
486 *
487 * @param newParagraph the text after the insertion
488 * @param insertPos the position in the text at which the character
489 * is inserted
490 * @throws IndexOutOfBoundsException if {@code insertPos} is less
491 * than the start of {@code newParagraph} or greater than
492 * or equal to the end of {@code newParagraph}
493 * @throws NullPointerException if {@code newParagraph} is
494 * {@code null}
495 * @see #deleteChar
496 */
497 public void insertChar(AttributedCharacterIterator newParagraph,
498 int insertPos) {
499
500 measurer.insertChar(newParagraph, insertPos);
501
502 limit = newParagraph.getEndIndex();
503 pos = start = newParagraph.getBeginIndex();
504
505 charIter.reset(measurer.getChars(), newParagraph.getBeginIndex());
506 breakIter.setText(charIter);
507 }
508
509 /**
510 * Updates this {@code LineBreakMeasurer} after a single
511 * character is deleted from the text, and sets the current
512 * position to the beginning of the paragraph.
513 * @param newParagraph the text after the deletion
514 * @param deletePos the position in the text at which the character
515 * is deleted
516 * @throws IllegalArgumentException if multiple characters are deleted from
517 * the text represented by {@code newParagraph}
518 * @throws IndexOutOfBoundsException if {@code deletePos} is
519 * less than the start of {@code newParagraph} or greater
520 * than the end of {@code newParagraph}
521 * @throws NullPointerException if {@code newParagraph} is
522 * {@code null}
523 * @see #insertChar
524 */
525 public void deleteChar(AttributedCharacterIterator newParagraph,
526 int deletePos) {
527
528 measurer.deleteChar(newParagraph, deletePos);
529
530 limit = newParagraph.getEndIndex();
531 pos = start = newParagraph.getBeginIndex();
532
533 charIter.reset(measurer.getChars(), start);
534 breakIter.setText(charIter);
535 }
536 }