1 /*
2 * Copyright (c) 1997, 2011, 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 package javax.swing.text;
26
27 import java.awt;
28 import javax.swing.SwingConstants;
29 import javax.swing.event;
30
31 /**
32 * <p>
33 * A very important part of the text package is the <code>View</code> class.
34 * As the name suggests it represents a view of the text model,
35 * or a piece of the text model.
36 * It is this class that is responsible for the look of the text component.
37 * The view is not intended to be some completely new thing that one must
38 * learn, but rather is much like a lightweight component.
39 * <p>
40 By default, a view is very light. It contains a reference to the parent
41 view from which it can fetch many things without holding state, and it
42 contains a reference to a portion of the model (<code>Element</code>).
43 A view does not
44 have to exactly represent an element in the model, that is simply a typical
45 and therefore convenient mapping. A view can alternatively maintain a couple
46 of Position objects to maintain its location in the model (i.e. represent
47 a fragment of an element). This is typically the result of formatting where
48 views have been broken down into pieces. The convenience of a substantial
49 relationship to the element makes it easier to build factories to produce the
50 views, and makes it easier to keep track of the view pieces as the model is
51 changed and the view must be changed to reflect the model. Simple views
52 therefore represent an Element directly and complex views do not.
53 <p>
54 A view has the following responsibilities:
55 <dl>
56
57 <dt><b>Participate in layout.</b>
58 <dd>
59 <p>The view has a <code>setSize</code> method which is like
60 <code>doLayout</code> and <code>setSize</code> in <code>Component</code> combined.
61 The view has a <code>preferenceChanged</code> method which is
62 like <code>invalidate</code> in <code>Component</code> except that one can
63 invalidate just one axis
64 and the child requesting the change is identified.
65 <p>A View expresses the size that it would like to be in terms of three
66 values, a minimum, a preferred, and a maximum span. Layout in a view is
67 can be done independently upon each axis. For a properly functioning View
68 implementation, the minimum span will be <= the preferred span which in turn
69 will be <= the maximum span.
70 </p>
71 <p align=center><img src="doc-files/View-flexibility.jpg"
72 alt="The above text describes this graphic.">
73 <p>The minimum set of methods for layout are:
74 <ul>
75 <li><a href="#getMinimumSpan(int)">getMinimumSpan</a>
76 <li><a href="#getPreferredSpan(int)">getPreferredSpan</a>
77 <li><a href="#getMaximumSpan(int)">getMaximumSpan</a>
78 <li><a href="#getAlignment(int)">getAlignment</a>
79 <li><a href="#preferenceChanged(javax.swing.text.View, boolean, boolean)">preferenceChanged</a>
80 <li><a href="#setSize(float, float)">setSize</a>
81 </ul>
82
83 <p>The <code>setSize</code> method should be prepared to be called a number of times
84 (i.e. It may be called even if the size didn't change).
85 The <code>setSize</code> method
86 is generally called to make sure the View layout is complete prior to trying
87 to perform an operation on it that requires an up-to-date layout. A view's
88 size should <em>always</em> be set to a value within the minimum and maximum
89 span specified by that view. Additionally, the view must always call the
90 <code>preferenceChanged</code> method on the parent if it has changed the
91 values for the
92 layout it would like, and expects the parent to honor. The parent View is
93 not required to recognize a change until the <code>preferenceChanged</code>
94 has been sent.
95 This allows parent View implementations to cache the child requirements if
96 desired. The calling sequence looks something like the following:
97 </p>
98 <p align=center>
99 <img src="doc-files/View-layout.jpg"
100 alt="Sample calling sequence between parent view and child view:
101 setSize, getMinimum, getPreferred, getMaximum, getAlignment, setSize">
102 <p>The exact calling sequence is up to the layout functionality of
103 the parent view (if the view has any children). The view may collect
104 the preferences of the children prior to determining what it will give
105 each child, or it might iteratively update the children one at a time.
106 </p>
107
108 <dt><b>Render a portion of the model.</b>
109 <dd>
110 <p>This is done in the paint method, which is pretty much like a component
111 paint method. Views are expected to potentially populate a fairly large
112 tree. A <code>View</code> has the following semantics for rendering:
113 </p>
114 <ul>
115 <li>The view gets its allocation from the parent at paint time, so it
116 must be prepared to redo layout if the allocated area is different from
117 what it is prepared to deal with.
118 <li>The coordinate system is the same as the hosting <code>Component</code>
119 (i.e. the <code>Component</code> returned by the
120 {@link #getContainer getContainer} method).
121 This means a child view lives in the same coordinate system as the parent
122 view unless the parent has explicitly changed the coordinate system.
123 To schedule itself to be repainted a view can call repaint on the hosting
124 <code>Component</code>.
125 <li>The default is to <em>not clip</em> the children. It is more efficient
126 to allow a view to clip only if it really feels it needs clipping.
127 <li>The <code>Graphics</code> object given is not initialized in any way.
128 A view should set any settings needed.
129 <li>A <code>View</code> is inherently transparent. While a view may render into its
130 entire allocation, typically a view does not. Rendering is performed by
131 tranversing down the tree of <code>View</code> implementations.
132 Each <code>View</code> is responsible
133 for rendering its children. This behavior is depended upon for thread
134 safety. While view implementations do not necessarily have to be implemented
135 with thread safety in mind, other view implementations that do make use of
136 concurrency can depend upon a tree traversal to guarantee thread safety.
137 <li>The order of views relative to the model is up to the implementation.
138 Although child views will typically be arranged in the same order that they
139 occur in the model, they may be visually arranged in an entirely different
140 order. View implementations may have Z-Order associated with them if the
141 children are overlapping.
142 </ul>
143 <p>The methods for rendering are:
144 <ul>
145 <li><a href="#paint(java.awt.Graphics, java.awt.Shape)">paint</a>
146 </ul>
147 <p>
148
149 <dt><b>Translate between the model and view coordinate systems.</b>
150 <dd>
151 <p>Because the view objects are produced from a factory and therefore cannot
152 necessarily be counted upon to be in a particular pattern, one must be able
153 to perform translation to properly locate spatial representation of the model.
154 The methods for doing this are:
155 <ul>
156 <li><a href="#modelToView(int, javax.swing.text.Position.Bias, int, javax.swing.text.Position.Bias, java.awt.Shape)">modelToView</a>
157 <li><a href="#viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])">viewToModel</a>
158 <li><a href="#getDocument()">getDocument</a>
159 <li><a href="#getElement()">getElement</a>
160 <li><a href="#getStartOffset()">getStartOffset</a>
161 <li><a href="#getEndOffset()">getEndOffset</a>
162 </ul>
163 <p>The layout must be valid prior to attempting to make the translation.
164 The translation is not valid, and must not be attempted while changes
165 are being broadcasted from the model via a <code>DocumentEvent</code>.
166 </p>
167
168 <dt><b>Respond to changes from the model.</b>
169 <dd>
170 <p>If the overall view is represented by many pieces (which is the best situation
171 if one want to be able to change the view and write the least amount of new code),
172 it would be impractical to have a huge number of <code>DocumentListener</code>s.
173 If each
174 view listened to the model, only a few would actually be interested in the
175 changes broadcasted at any given time. Since the model has no knowledge of
176 views, it has no way to filter the broadcast of change information. The view
177 hierarchy itself is instead responsible for propagating the change information.
178 At any level in the view hierarchy, that view knows enough about its children to
179 best distribute the change information further. Changes are therefore broadcasted
180 starting from the root of the view hierarchy.
181 The methods for doing this are:
182 <ul>
183 <li>{@link #insertUpdate insertUpdate}
184 <li>{@link #removeUpdate removeUpdate}
185 <li>{@link #changedUpdate changedUpdate}
186 </ul>
187 <p>
188 </dl>
189 *
190 * @author Timothy Prinzing
191 */
192 public abstract class View implements SwingConstants {
193
194 /**
195 * Creates a new <code>View</code> object.
196 *
197 * @param elem the <code>Element</code> to represent
198 */
199 public View(Element elem) {
200 this.elem = elem;
201 }
202
203 /**
204 * Returns the parent of the view.
205 *
206 * @return the parent, or <code>null</code> if none exists
207 */
208 public View getParent() {
209 return parent;
210 }
211
212 /**
213 * Returns a boolean that indicates whether
214 * the view is visible or not. By default
215 * all views are visible.
216 *
217 * @return always returns true
218 */
219 public boolean isVisible() {
220 return true;
221 }
222
223
224 /**
225 * Determines the preferred span for this view along an
226 * axis.
227 *
228 * @param axis may be either <code>View.X_AXIS</code> or
229 * <code>View.Y_AXIS</code>
230 * @return the span the view would like to be rendered into.
231 * Typically the view is told to render into the span
232 * that is returned, although there is no guarantee.
233 * The parent may choose to resize or break the view
234 * @see View#getPreferredSpan
235 */
236 public abstract float getPreferredSpan(int axis);
237
238 /**
239 * Determines the minimum span for this view along an
240 * axis.
241 *
242 * @param axis may be either <code>View.X_AXIS</code> or
243 * <code>View.Y_AXIS</code>
244 * @return the minimum span the view can be rendered into
245 * @see View#getPreferredSpan
246 */
247 public float getMinimumSpan(int axis) {
248 int w = getResizeWeight(axis);
249 if (w == 0) {
250 // can't resize
251 return getPreferredSpan(axis);
252 }
253 return 0;
254 }
255
256 /**
257 * Determines the maximum span for this view along an
258 * axis.
259 *
260 * @param axis may be either <code>View.X_AXIS</code> or
261 * <code>View.Y_AXIS</code>
262 * @return the maximum span the view can be rendered into
263 * @see View#getPreferredSpan
264 */
265 public float getMaximumSpan(int axis) {
266 int w = getResizeWeight(axis);
267 if (w == 0) {
268 // can't resize
269 return getPreferredSpan(axis);
270 }
271 return Integer.MAX_VALUE;
272 }
273
274 /**
275 * Child views can call this on the parent to indicate that
276 * the preference has changed and should be reconsidered
277 * for layout. By default this just propagates upward to
278 * the next parent. The root view will call
279 * <code>revalidate</code> on the associated text component.
280 *
281 * @param child the child view
282 * @param width true if the width preference has changed
283 * @param height true if the height preference has changed
284 * @see javax.swing.JComponent#revalidate
285 */
286 public void preferenceChanged(View child, boolean width, boolean height) {
287 View parent = getParent();
288 if (parent != null) {
289 parent.preferenceChanged(this, width, height);
290 }
291 }
292
293 /**
294 * Determines the desired alignment for this view along an
295 * axis. The desired alignment is returned. This should be
296 * a value >= 0.0 and <= 1.0, where 0 indicates alignment at
297 * the origin and 1.0 indicates alignment to the full span
298 * away from the origin. An alignment of 0.5 would be the
299 * center of the view.
300 *
301 * @param axis may be either <code>View.X_AXIS</code> or
302 * <code>View.Y_AXIS</code>
303 * @return the value 0.5
304 */
305 public float getAlignment(int axis) {
306 return 0.5f;
307 }
308
309 /**
310 * Renders using the given rendering surface and area on that
311 * surface. The view may need to do layout and create child
312 * views to enable itself to render into the given allocation.
313 *
314 * @param g the rendering surface to use
315 * @param allocation the allocated region to render into
316 */
317 public abstract void paint(Graphics g, Shape allocation);
318
319 /**
320 * Establishes the parent view for this view. This is
321 * guaranteed to be called before any other methods if the
322 * parent view is functioning properly. This is also
323 * the last method called, since it is called to indicate
324 * the view has been removed from the hierarchy as
325 * well. When this method is called to set the parent to
326 * null, this method does the same for each of its children,
327 * propogating the notification that they have been
328 * disconnected from the view tree. If this is
329 * reimplemented, <code>super.setParent()</code> should
330 * be called.
331 *
332 * @param parent the new parent, or <code>null</code> if the view is
333 * being removed from a parent
334 */
335 public void setParent(View parent) {
336 // if the parent is null then propogate down the view tree
337 if (parent == null) {
338 for (int i = 0; i < getViewCount(); i++) {
339 if (getView(i).getParent() == this) {
340 // in FlowView.java view might be referenced
341 // from two super-views as a child. see logicalView
342 getView(i).setParent(null);
343 }
344 }
345 }
346 this.parent = parent;
347 }
348
349 /**
350 * Returns the number of views in this view. Since
351 * the default is to not be a composite view this
352 * returns 0.
353 *
354 * @return the number of views >= 0
355 * @see View#getViewCount
356 */
357 public int getViewCount() {
358 return 0;
359 }
360
361 /**
362 * Gets the <i>n</i>th child view. Since there are no
363 * children by default, this returns <code>null</code>.
364 *
365 * @param n the number of the view to get, >= 0 && < getViewCount()
366 * @return the view
367 */
368 public View getView(int n) {
369 return null;
370 }
371
372
373 /**
374 * Removes all of the children. This is a convenience
375 * call to <code>replace</code>.
376 *
377 * @since 1.3
378 */
379 public void removeAll() {
380 replace(0, getViewCount(), null);
381 }
382
383 /**
384 * Removes one of the children at the given position.
385 * This is a convenience call to <code>replace</code>.
386 * @since 1.3
387 */
388 public void remove(int i) {
389 replace(i, 1, null);
390 }
391
392 /**
393 * Inserts a single child view. This is a convenience
394 * call to <code>replace</code>.
395 *
396 * @param offs the offset of the view to insert before >= 0
397 * @param v the view
398 * @see #replace
399 * @since 1.3
400 */
401 public void insert(int offs, View v) {
402 View[] one = new View[1];
403 one[0] = v;
404 replace(offs, 0, one);
405 }
406
407 /**
408 * Appends a single child view. This is a convenience
409 * call to <code>replace</code>.
410 *
411 * @param v the view
412 * @see #replace
413 * @since 1.3
414 */
415 public void append(View v) {
416 View[] one = new View[1];
417 one[0] = v;
418 replace(getViewCount(), 0, one);
419 }
420
421 /**
422 * Replaces child views. If there are no views to remove
423 * this acts as an insert. If there are no views to
424 * add this acts as a remove. Views being removed will
425 * have the parent set to <code>null</code>, and the internal reference
426 * to them removed so that they can be garbage collected.
427 * This is implemented to do nothing, because by default
428 * a view has no children.
429 *
430 * @param offset the starting index into the child views to insert
431 * the new views. This should be a value >= 0 and <= getViewCount
432 * @param length the number of existing child views to remove
433 * This should be a value >= 0 and <= (getViewCount() - offset).
434 * @param views the child views to add. This value can be
435 * <code>null</code> to indicate no children are being added
436 * (useful to remove).
437 * @since 1.3
438 */
439 public void replace(int offset, int length, View[] views) {
440 }
441
442 /**
443 * Returns the child view index representing the given position in
444 * the model. By default a view has no children so this is implemented
445 * to return -1 to indicate there is no valid child index for any
446 * position.
447 *
448 * @param pos the position >= 0
449 * @return index of the view representing the given position, or
450 * -1 if no view represents that position
451 * @since 1.3
452 */
453 public int getViewIndex(int pos, Position.Bias b) {
454 return -1;
455 }
456
457 /**
458 * Fetches the allocation for the given child view.
459 * This enables finding out where various views
460 * are located, without assuming how the views store
461 * their location. This returns <code>null</code> since the
462 * default is to not have any child views.
463 *
464 * @param index the index of the child, >= 0 && <
465 * <code>getViewCount()</code>
466 * @param a the allocation to this view
467 * @return the allocation to the child
468 */
469 public Shape getChildAllocation(int index, Shape a) {
470 return null;
471 }
472
473 /**
474 * Provides a way to determine the next visually represented model
475 * location at which one might place a caret.
476 * Some views may not be visible,
477 * they might not be in the same order found in the model, or they just
478 * might not allow access to some of the locations in the model.
479 *
480 * @param pos the position to convert >= 0
481 * @param a the allocated region in which to render
482 * @param direction the direction from the current position that can
483 * be thought of as the arrow keys typically found on a keyboard.
484 * This will be one of the following values:
485 * <ul>
486 * <li>SwingConstants.WEST
487 * <li>SwingConstants.EAST
488 * <li>SwingConstants.NORTH
489 * <li>SwingConstants.SOUTH
490 * </ul>
491 * @return the location within the model that best represents the next
492 * location visual position
493 * @exception BadLocationException
494 * @exception IllegalArgumentException if <code>direction</code>
495 * doesn't have one of the legal values above
496 */
497 public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,
498 int direction, Position.Bias[] biasRet)
499 throws BadLocationException {
500 if (pos < -1) {
501 // -1 is a reserved value, see the code below
502 throw new BadLocationException("Invalid position", pos);
503 }
504
505 biasRet[0] = Position.Bias.Forward;
506 switch (direction) {
507 case NORTH:
508 case SOUTH:
509 {
510 if (pos == -1) {
511 pos = (direction == NORTH) ? Math.max(0, getEndOffset() - 1) :
512 getStartOffset();
513 break;
514 }
515 JTextComponent target = (JTextComponent) getContainer();
516 Caret c = (target != null) ? target.getCaret() : null;
517 // YECK! Ideally, the x location from the magic caret position
518 // would be passed in.
519 Point mcp;
520 if (c != null) {
521 mcp = c.getMagicCaretPosition();
522 }
523 else {
524 mcp = null;
525 }
526 int x;
527 if (mcp == null) {
528 Rectangle loc = target.modelToView(pos);
529 x = (loc == null) ? 0 : loc.x;
530 }
531 else {
532 x = mcp.x;
533 }
534 if (direction == NORTH) {
535 pos = Utilities.getPositionAbove(target, pos, x);
536 }
537 else {
538 pos = Utilities.getPositionBelow(target, pos, x);
539 }
540 }
541 break;
542 case WEST:
543 if(pos == -1) {
544 pos = Math.max(0, getEndOffset() - 1);
545 }
546 else {
547 pos = Math.max(0, pos - 1);
548 }
549 break;
550 case EAST:
551 if(pos == -1) {
552 pos = getStartOffset();
553 }
554 else {
555 pos = Math.min(pos + 1, getDocument().getLength());
556 }
557 break;
558 default:
559 throw new IllegalArgumentException("Bad direction: " + direction);
560 }
561 return pos;
562 }
563
564 /**
565 * Provides a mapping, for a given character,
566 * from the document model coordinate space
567 * to the view coordinate space.
568 *
569 * @param pos the position of the desired character (>=0)
570 * @param a the area of the view, which encompasses the requested character
571 * @param b the bias toward the previous character or the
572 * next character represented by the offset, in case the
573 * position is a boundary of two views; <code>b</code> will have one
574 * of these values:
575 * <ul>
576 * <li> <code>Position.Bias.Forward</code>
577 * <li> <code>Position.Bias.Backward</code>
578 * </ul>
579 * @return the bounding box, in view coordinate space,
580 * of the character at the specified position
581 * @exception BadLocationException if the specified position does
582 * not represent a valid location in the associated document
583 * @exception IllegalArgumentException if <code>b</code> is not one of the
584 * legal <code>Position.Bias</code> values listed above
585 * @see View#viewToModel
586 */
587 public abstract Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException;
588
589 /**
590 * Provides a mapping, for a given region,
591 * from the document model coordinate space
592 * to the view coordinate space. The specified region is
593 * created as a union of the first and last character positions.
594 *
595 * @param p0 the position of the first character (>=0)
596 * @param b0 the bias of the first character position,
597 * toward the previous character or the
598 * next character represented by the offset, in case the
599 * position is a boundary of two views; <code>b0</code> will have one
600 * of these values:
601 * <ul>
602 * <li> <code>Position.Bias.Forward</code>
603 * <li> <code>Position.Bias.Backward</code>
604 * </ul>
605 * @param p1 the position of the last character (>=0)
606 * @param b1 the bias for the second character position, defined
607 * one of the legal values shown above
608 * @param a the area of the view, which encompasses the requested region
609 * @return the bounding box which is a union of the region specified
610 * by the first and last character positions
611 * @exception BadLocationException if the given position does
612 * not represent a valid location in the associated document
613 * @exception IllegalArgumentException if <code>b0</code> or
614 * <code>b1</code> are not one of the
615 * legal <code>Position.Bias</code> values listed above
616 * @see View#viewToModel
617 */
618 public Shape modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) throws BadLocationException {
619 Shape s0 = modelToView(p0, a, b0);
620 Shape s1;
621 if (p1 == getEndOffset()) {
622 try {
623 s1 = modelToView(p1, a, b1);
624 } catch (BadLocationException ble) {
625 s1 = null;
626 }
627 if (s1 == null) {
628 // Assume extends left to right.
629 Rectangle alloc = (a instanceof Rectangle) ? (Rectangle)a :
630 a.getBounds();
631 s1 = new Rectangle(alloc.x + alloc.width - 1, alloc.y,
632 1, alloc.height);
633 }
634 }
635 else {
636 s1 = modelToView(p1, a, b1);
637 }
638 Rectangle r0 = s0.getBounds();
639 Rectangle r1 = (s1 instanceof Rectangle) ? (Rectangle) s1 :
640 s1.getBounds();
641 if (r0.y != r1.y) {
642 // If it spans lines, force it to be the width of the view.
643 Rectangle alloc = (a instanceof Rectangle) ? (Rectangle)a :
644 a.getBounds();
645 r0.x = alloc.x;
646 r0.width = alloc.width;
647 }
648 r0.add(r1);
649 return r0;
650 }
651
652 /**
653 * Provides a mapping from the view coordinate space to the logical
654 * coordinate space of the model. The <code>biasReturn</code>
655 * argument will be filled in to indicate that the point given is
656 * closer to the next character in the model or the previous
657 * character in the model.
658 *
659 * @param x the X coordinate >= 0
660 * @param y the Y coordinate >= 0
661 * @param a the allocated region in which to render
662 * @return the location within the model that best represents the
663 * given point in the view >= 0. The <code>biasReturn</code>
664 * argument will be
665 * filled in to indicate that the point given is closer to the next
666 * character in the model or the previous character in the model.
667 */
668 public abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn);
669
670 /**
671 * Gives notification that something was inserted into
672 * the document in a location that this view is responsible for.
673 * To reduce the burden to subclasses, this functionality is
674 * spread out into the following calls that subclasses can
675 * reimplement:
676 * <ol>
677 * <li>{@link #updateChildren updateChildren} is called
678 * if there were any changes to the element this view is
679 * responsible for. If this view has child views that are
680 * represent the child elements, then this method should do
681 * whatever is necessary to make sure the child views correctly
682 * represent the model.
683 * <li>{@link #forwardUpdate forwardUpdate} is called
684 * to forward the DocumentEvent to the appropriate child views.
685 * <li>{@link #updateLayout updateLayout} is called to
686 * give the view a chance to either repair its layout, to reschedule
687 * layout, or do nothing.
688 * </ol>
689 *
690 * @param e the change information from the associated document
691 * @param a the current allocation of the view
692 * @param f the factory to use to rebuild if the view has children
693 * @see View#insertUpdate
694 */
695 public void insertUpdate(DocumentEvent e, Shape a, ViewFactory f) {
696 if (getViewCount() > 0) {
697 Element elem = getElement();
698 DocumentEvent.ElementChange ec = e.getChange(elem);
699 if (ec != null) {
700 if (! updateChildren(ec, e, f)) {
701 // don't consider the element changes they
702 // are for a view further down.
703 ec = null;
704 }
705 }
706 forwardUpdate(ec, e, a, f);
707 updateLayout(ec, e, a);
708 }
709 }
710
711 /**
712 * Gives notification that something was removed from the document
713 * in a location that this view is responsible for.
714 * To reduce the burden to subclasses, this functionality is
715 * spread out into the following calls that subclasses can
716 * reimplement:
717 * <ol>
718 * <li>{@link #updateChildren updateChildren} is called
719 * if there were any changes to the element this view is
720 * responsible for. If this view has child views that are
721 * represent the child elements, then this method should do
722 * whatever is necessary to make sure the child views correctly
723 * represent the model.
724 * <li>{@link #forwardUpdate forwardUpdate} is called
725 * to forward the DocumentEvent to the appropriate child views.
726 * <li>{@link #updateLayout updateLayout} is called to
727 * give the view a chance to either repair its layout, to reschedule
728 * layout, or do nothing.
729 * </ol>
730 *
731 * @param e the change information from the associated document
732 * @param a the current allocation of the view
733 * @param f the factory to use to rebuild if the view has children
734 * @see View#removeUpdate
735 */
736 public void removeUpdate(DocumentEvent e, Shape a, ViewFactory f) {
737 if (getViewCount() > 0) {
738 Element elem = getElement();
739 DocumentEvent.ElementChange ec = e.getChange(elem);
740 if (ec != null) {
741 if (! updateChildren(ec, e, f)) {
742 // don't consider the element changes they
743 // are for a view further down.
744 ec = null;
745 }
746 }
747 forwardUpdate(ec, e, a, f);
748 updateLayout(ec, e, a);
749 }
750 }
751
752 /**
753 * Gives notification from the document that attributes were changed
754 * in a location that this view is responsible for.
755 * To reduce the burden to subclasses, this functionality is
756 * spread out into the following calls that subclasses can
757 * reimplement:
758 * <ol>
759 * <li>{@link #updateChildren updateChildren} is called
760 * if there were any changes to the element this view is
761 * responsible for. If this view has child views that are
762 * represent the child elements, then this method should do
763 * whatever is necessary to make sure the child views correctly
764 * represent the model.
765 * <li>{@link #forwardUpdate forwardUpdate} is called
766 * to forward the DocumentEvent to the appropriate child views.
767 * <li>{@link #updateLayout updateLayout} is called to
768 * give the view a chance to either repair its layout, to reschedule
769 * layout, or do nothing.
770 * </ol>
771 *
772 * @param e the change information from the associated document
773 * @param a the current allocation of the view
774 * @param f the factory to use to rebuild if the view has children
775 * @see View#changedUpdate
776 */
777 public void changedUpdate(DocumentEvent e, Shape a, ViewFactory f) {
778 if (getViewCount() > 0) {
779 Element elem = getElement();
780 DocumentEvent.ElementChange ec = e.getChange(elem);
781 if (ec != null) {
782 if (! updateChildren(ec, e, f)) {
783 // don't consider the element changes they
784 // are for a view further down.
785 ec = null;
786 }
787 }
788 forwardUpdate(ec, e, a, f);
789 updateLayout(ec, e, a);
790 }
791 }
792
793 /**
794 * Fetches the model associated with the view.
795 *
796 * @return the view model, <code>null</code> if none
797 * @see View#getDocument
798 */
799 public Document getDocument() {
800 return elem.getDocument();
801 }
802
803 /**
804 * Fetches the portion of the model for which this view is
805 * responsible.
806 *
807 * @return the starting offset into the model >= 0
808 * @see View#getStartOffset
809 */
810 public int getStartOffset() {
811 return elem.getStartOffset();
812 }
813
814 /**
815 * Fetches the portion of the model for which this view is
816 * responsible.
817 *
818 * @return the ending offset into the model >= 0
819 * @see View#getEndOffset
820 */
821 public int getEndOffset() {
822 return elem.getEndOffset();
823 }
824
825 /**
826 * Fetches the structural portion of the subject that this
827 * view is mapped to. The view may not be responsible for the
828 * entire portion of the element.
829 *
830 * @return the subject
831 * @see View#getElement
832 */
833 public Element getElement() {
834 return elem;
835 }
836
837 /**
838 * Fetch a <code>Graphics</code> for rendering.
839 * This can be used to determine
840 * font characteristics, and will be different for a print view
841 * than a component view.
842 *
843 * @return a <code>Graphics</code> object for rendering
844 * @since 1.3
845 */
846 public Graphics getGraphics() {
847 // PENDING(prinz) this is a temporary implementation
848 Component c = getContainer();
849 return c.getGraphics();
850 }
851
852 /**
853 * Fetches the attributes to use when rendering. By default
854 * this simply returns the attributes of the associated element.
855 * This method should be used rather than using the element
856 * directly to obtain access to the attributes to allow
857 * view-specific attributes to be mixed in or to allow the
858 * view to have view-specific conversion of attributes by
859 * subclasses.
860 * Each view should document what attributes it recognizes
861 * for the purpose of rendering or layout, and should always
862 * access them through the <code>AttributeSet</code> returned
863 * by this method.
864 */
865 public AttributeSet getAttributes() {
866 return elem.getAttributes();
867 }
868
869 /**
870 * Tries to break this view on the given axis. This is
871 * called by views that try to do formatting of their
872 * children. For example, a view of a paragraph will
873 * typically try to place its children into row and
874 * views representing chunks of text can sometimes be
875 * broken down into smaller pieces.
876 * <p>
877 * This is implemented to return the view itself, which
878 * represents the default behavior on not being
879 * breakable. If the view does support breaking, the
880 * starting offset of the view returned should be the
881 * given offset, and the end offset should be less than
882 * or equal to the end offset of the view being broken.
883 *
884 * @param axis may be either <code>View.X_AXIS</code> or
885 * <code>View.Y_AXIS</code>
886 * @param offset the location in the document model
887 * that a broken fragment would occupy >= 0. This
888 * would be the starting offset of the fragment
889 * returned
890 * @param pos the position along the axis that the
891 * broken view would occupy >= 0. This may be useful for
892 * things like tab calculations
893 * @param len specifies the distance along the axis
894 * where a potential break is desired >= 0
895 * @return the fragment of the view that represents the
896 * given span, if the view can be broken. If the view
897 * doesn't support breaking behavior, the view itself is
898 * returned.
899 * @see ParagraphView
900 */
901 public View breakView(int axis, int offset, float pos, float len) {
902 return this;
903 }
904
905 /**
906 * Creates a view that represents a portion of the element.
907 * This is potentially useful during formatting operations
908 * for taking measurements of fragments of the view. If
909 * the view doesn't support fragmenting (the default), it
910 * should return itself.
911 *
912 * @param p0 the starting offset >= 0. This should be a value
913 * greater or equal to the element starting offset and
914 * less than the element ending offset.
915 * @param p1 the ending offset > p0. This should be a value
916 * less than or equal to the elements end offset and
917 * greater than the elements starting offset.
918 * @return the view fragment, or itself if the view doesn't
919 * support breaking into fragments
920 * @see LabelView
921 */
922 public View createFragment(int p0, int p1) {
923 return this;
924 }
925
926 /**
927 * Determines how attractive a break opportunity in
928 * this view is. This can be used for determining which
929 * view is the most attractive to call <code>breakView</code>
930 * on in the process of formatting. A view that represents
931 * text that has whitespace in it might be more attractive
932 * than a view that has no whitespace, for example. The
933 * higher the weight, the more attractive the break. A
934 * value equal to or lower than <code>BadBreakWeight</code>
935 * should not be considered for a break. A value greater
936 * than or equal to <code>ForcedBreakWeight</code> should
937 * be broken.
938 * <p>
939 * This is implemented to provide the default behavior
940 * of returning <code>BadBreakWeight</code> unless the length
941 * is greater than the length of the view in which case the
942 * entire view represents the fragment. Unless a view has
943 * been written to support breaking behavior, it is not
944 * attractive to try and break the view. An example of
945 * a view that does support breaking is <code>LabelView</code>.
946 * An example of a view that uses break weight is
947 * <code>ParagraphView</code>.
948 *
949 * @param axis may be either <code>View.X_AXIS</code> or
950 * <code>View.Y_AXIS</code>
951 * @param pos the potential location of the start of the
952 * broken view >= 0. This may be useful for calculating tab
953 * positions
954 * @param len specifies the relative length from <em>pos</em>
955 * where a potential break is desired >= 0
956 * @return the weight, which should be a value between
957 * ForcedBreakWeight and BadBreakWeight
958 * @see LabelView
959 * @see ParagraphView
960 * @see #BadBreakWeight
961 * @see #GoodBreakWeight
962 * @see #ExcellentBreakWeight
963 * @see #ForcedBreakWeight
964 */
965 public int getBreakWeight(int axis, float pos, float len) {
966 if (len > getPreferredSpan(axis)) {
967 return GoodBreakWeight;
968 }
969 return BadBreakWeight;
970 }
971
972 /**
973 * Determines the resizability of the view along the
974 * given axis. A value of 0 or less is not resizable.
975 *
976 * @param axis may be either <code>View.X_AXIS</code> or
977 * <code>View.Y_AXIS</code>
978 * @return the weight
979 */
980 public int getResizeWeight(int axis) {
981 return 0;
982 }
983
984 /**
985 * Sets the size of the view. This should cause
986 * layout of the view along the given axis, if it
987 * has any layout duties.
988 *
989 * @param width the width >= 0
990 * @param height the height >= 0
991 */
992 public void setSize(float width, float height) {
993 }
994
995 /**
996 * Fetches the container hosting the view. This is useful for
997 * things like scheduling a repaint, finding out the host
998 * components font, etc. The default implementation
999 * of this is to forward the query to the parent view.
1000 *
1001 * @return the container, <code>null</code> if none
1002 */
1003 public Container getContainer() {
1004 View v = getParent();
1005 return (v != null) ? v.getContainer() : null;
1006 }
1007
1008 /**
1009 * Fetches the <code>ViewFactory</code> implementation that is feeding
1010 * the view hierarchy. Normally the views are given this
1011 * as an argument to updates from the model when they
1012 * are most likely to need the factory, but this
1013 * method serves to provide it at other times.
1014 *
1015 * @return the factory, <code>null</code> if none
1016 */
1017 public ViewFactory getViewFactory() {
1018 View v = getParent();
1019 return (v != null) ? v.getViewFactory() : null;
1020 }
1021
1022 /**
1023 * Returns the tooltip text at the specified location. The default
1024 * implementation returns the value from the child View identified by
1025 * the passed in location.
1026 *
1027 * @since 1.4
1028 * @see JTextComponent#getToolTipText
1029 */
1030 public String getToolTipText(float x, float y, Shape allocation) {
1031 int viewIndex = getViewIndex(x, y, allocation);
1032 if (viewIndex >= 0) {
1033 allocation = getChildAllocation(viewIndex, allocation);
1034 Rectangle rect = (allocation instanceof Rectangle) ?
1035 (Rectangle)allocation : allocation.getBounds();
1036 if (rect.contains(x, y)) {
1037 return getView(viewIndex).getToolTipText(x, y, allocation);
1038 }
1039 }
1040 return null;
1041 }
1042
1043 /**
1044 * Returns the child view index representing the given position in
1045 * the view. This iterates over all the children returning the
1046 * first with a bounds that contains <code>x</code>, <code>y</code>.
1047 *
1048 * @param x the x coordinate
1049 * @param y the y coordinate
1050 * @param allocation current allocation of the View.
1051 * @return index of the view representing the given location, or
1052 * -1 if no view represents that position
1053 * @since 1.4
1054 */
1055 public int getViewIndex(float x, float y, Shape allocation) {
1056 for (int counter = getViewCount() - 1; counter >= 0; counter--) {
1057 Shape childAllocation = getChildAllocation(counter, allocation);
1058
1059 if (childAllocation != null) {
1060 Rectangle rect = (childAllocation instanceof Rectangle) ?
1061 (Rectangle)childAllocation : childAllocation.getBounds();
1062
1063 if (rect.contains(x, y)) {
1064 return counter;
1065 }
1066 }
1067 }
1068 return -1;
1069 }
1070
1071 /**
1072 * Updates the child views in response to receiving notification
1073 * that the model changed, and there is change record for the
1074 * element this view is responsible for. This is implemented
1075 * to assume the child views are directly responsible for the
1076 * child elements of the element this view represents. The
1077 * <code>ViewFactory</code> is used to create child views for each element
1078 * specified as added in the <code>ElementChange</code>, starting at the
1079 * index specified in the given <code>ElementChange</code>. The number of
1080 * child views representing the removed elements specified are
1081 * removed.
1082 *
1083 * @param ec the change information for the element this view
1084 * is responsible for. This should not be <code>null</code> if
1085 * this method gets called
1086 * @param e the change information from the associated document
1087 * @param f the factory to use to build child views
1088 * @return whether or not the child views represent the
1089 * child elements of the element this view is responsible
1090 * for. Some views create children that represent a portion
1091 * of the element they are responsible for, and should return
1092 * false. This information is used to determine if views
1093 * in the range of the added elements should be forwarded to
1094 * or not
1095 * @see #insertUpdate
1096 * @see #removeUpdate
1097 * @see #changedUpdate
1098 * @since 1.3
1099 */
1100 protected boolean updateChildren(DocumentEvent.ElementChange ec,
1101 DocumentEvent e, ViewFactory f) {
1102 Element[] removedElems = ec.getChildrenRemoved();
1103 Element[] addedElems = ec.getChildrenAdded();
1104 View[] added = null;
1105 if (addedElems != null) {
1106 added = new View[addedElems.length];
1107 for (int i = 0; i < addedElems.length; i++) {
1108 added[i] = f.create(addedElems[i]);
1109 }
1110 }
1111 int nremoved = 0;
1112 int index = ec.getIndex();
1113 if (removedElems != null) {
1114 nremoved = removedElems.length;
1115 }
1116 replace(index, nremoved, added);
1117 return true;
1118 }
1119
1120 /**
1121 * Forwards the given <code>DocumentEvent</code> to the child views
1122 * that need to be notified of the change to the model.
1123 * If there were changes to the element this view is
1124 * responsible for, that should be considered when
1125 * forwarding (i.e. new child views should not get
1126 * notified).
1127 *
1128 * @param ec changes to the element this view is responsible
1129 * for (may be <code>null</code> if there were no changes).
1130 * @param e the change information from the associated document
1131 * @param a the current allocation of the view
1132 * @param f the factory to use to rebuild if the view has children
1133 * @see #insertUpdate
1134 * @see #removeUpdate
1135 * @see #changedUpdate
1136 * @since 1.3
1137 */
1138 protected void forwardUpdate(DocumentEvent.ElementChange ec,
1139 DocumentEvent e, Shape a, ViewFactory f) {
1140 Element elem = getElement();
1141 int pos = e.getOffset();
1142 int index0 = getViewIndex(pos, Position.Bias.Forward);
1143 if (index0 == -1 && e.getType() == DocumentEvent.EventType.REMOVE &&
1144 pos >= getEndOffset()) {
1145 // Event beyond our offsets. We may have represented this, that is
1146 // the remove may have removed one of our child Elements that
1147 // represented this, so, we should foward to last element.
1148 index0 = getViewCount() - 1;
1149 }
1150 int index1 = index0;
1151 View v = (index0 >= 0) ? getView(index0) : null;
1152 if (v != null) {
1153 if ((v.getStartOffset() == pos) && (pos > 0)) {
1154 // If v is at a boundary, forward the event to the previous
1155 // view too.
1156 index0 = Math.max(index0 - 1, 0);
1157 }
1158 }
1159 if (e.getType() != DocumentEvent.EventType.REMOVE) {
1160 index1 = getViewIndex(pos + e.getLength(), Position.Bias.Forward);
1161 if (index1 < 0) {
1162 index1 = getViewCount() - 1;
1163 }
1164 }
1165 int hole0 = index1 + 1;
1166 int hole1 = hole0;
1167 Element[] addedElems = (ec != null) ? ec.getChildrenAdded() : null;
1168 if ((addedElems != null) && (addedElems.length > 0)) {
1169 hole0 = ec.getIndex();
1170 hole1 = hole0 + addedElems.length - 1;
1171 }
1172
1173 // forward to any view not in the forwarding hole
1174 // formed by added elements (i.e. they will be updated
1175 // by initialization.
1176 index0 = Math.max(index0, 0);
1177 for (int i = index0; i <= index1; i++) {
1178 if (! ((i >= hole0) && (i <= hole1))) {
1179 v = getView(i);
1180 if (v != null) {
1181 Shape childAlloc = getChildAllocation(i, a);
1182 forwardUpdateToView(v, e, childAlloc, f);
1183 }
1184 }
1185 }
1186 }
1187
1188 /**
1189 * Forwards the <code>DocumentEvent</code> to the give child view. This
1190 * simply messages the view with a call to <code>insertUpdate</code>,
1191 * <code>removeUpdate</code>, or <code>changedUpdate</code> depending
1192 * upon the type of the event. This is called by
1193 * {@link #forwardUpdate forwardUpdate} to forward
1194 * the event to children that need it.
1195 *
1196 * @param v the child view to forward the event to
1197 * @param e the change information from the associated document
1198 * @param a the current allocation of the view
1199 * @param f the factory to use to rebuild if the view has children
1200 * @see #forwardUpdate
1201 * @since 1.3
1202 */
1203 protected void forwardUpdateToView(View v, DocumentEvent e,
1204 Shape a, ViewFactory f) {
1205 DocumentEvent.EventType type = e.getType();
1206 if (type == DocumentEvent.EventType.INSERT) {
1207 v.insertUpdate(e, a, f);
1208 } else if (type == DocumentEvent.EventType.REMOVE) {
1209 v.removeUpdate(e, a, f);
1210 } else {
1211 v.changedUpdate(e, a, f);
1212 }
1213 }
1214
1215 /**
1216 * Updates the layout in response to receiving notification of
1217 * change from the model. This is implemented to call
1218 * <code>preferenceChanged</code> to reschedule a new layout
1219 * if the <code>ElementChange</code> record is not <code>null</code>.
1220 *
1221 * @param ec changes to the element this view is responsible
1222 * for (may be <code>null</code> if there were no changes)
1223 * @param e the change information from the associated document
1224 * @param a the current allocation of the view
1225 * @see #insertUpdate
1226 * @see #removeUpdate
1227 * @see #changedUpdate
1228 * @since 1.3
1229 */
1230 protected void updateLayout(DocumentEvent.ElementChange ec,
1231 DocumentEvent e, Shape a) {
1232 if ((ec != null) && (a != null)) {
1233 // should damage more intelligently
1234 preferenceChanged(null, true, true);
1235 Container host = getContainer();
1236 if (host != null) {
1237 host.repaint();
1238 }
1239 }
1240 }
1241
1242 /**
1243 * The weight to indicate a view is a bad break
1244 * opportunity for the purpose of formatting. This
1245 * value indicates that no attempt should be made to
1246 * break the view into fragments as the view has
1247 * not been written to support fragmenting.
1248 *
1249 * @see #getBreakWeight
1250 * @see #GoodBreakWeight
1251 * @see #ExcellentBreakWeight
1252 * @see #ForcedBreakWeight
1253 */
1254 public static final int BadBreakWeight = 0;
1255
1256 /**
1257 * The weight to indicate a view supports breaking,
1258 * but better opportunities probably exist.
1259 *
1260 * @see #getBreakWeight
1261 * @see #BadBreakWeight
1262 * @see #ExcellentBreakWeight
1263 * @see #ForcedBreakWeight
1264 */
1265 public static final int GoodBreakWeight = 1000;
1266
1267 /**
1268 * The weight to indicate a view supports breaking,
1269 * and this represents a very attractive place to
1270 * break.
1271 *
1272 * @see #getBreakWeight
1273 * @see #BadBreakWeight
1274 * @see #GoodBreakWeight
1275 * @see #ForcedBreakWeight
1276 */
1277 public static final int ExcellentBreakWeight = 2000;
1278
1279 /**
1280 * The weight to indicate a view supports breaking,
1281 * and must be broken to be represented properly
1282 * when placed in a view that formats its children
1283 * by breaking them.
1284 *
1285 * @see #getBreakWeight
1286 * @see #BadBreakWeight
1287 * @see #GoodBreakWeight
1288 * @see #ExcellentBreakWeight
1289 */
1290 public static final int ForcedBreakWeight = 3000;
1291
1292 /**
1293 * Axis for format/break operations.
1294 */
1295 public static final int X_AXIS = HORIZONTAL;
1296
1297 /**
1298 * Axis for format/break operations.
1299 */
1300 public static final int Y_AXIS = VERTICAL;
1301
1302 /**
1303 * Provides a mapping from the document model coordinate space
1304 * to the coordinate space of the view mapped to it. This is
1305 * implemented to default the bias to <code>Position.Bias.Forward</code>
1306 * which was previously implied.
1307 *
1308 * @param pos the position to convert >= 0
1309 * @param a the allocated region in which to render
1310 * @return the bounding box of the given position is returned
1311 * @exception BadLocationException if the given position does
1312 * not represent a valid location in the associated document
1313 * @see View#modelToView
1314 * @deprecated
1315 */
1316 @Deprecated
1317 public Shape modelToView(int pos, Shape a) throws BadLocationException {
1318 return modelToView(pos, a, Position.Bias.Forward);
1319 }
1320
1321
1322 /**
1323 * Provides a mapping from the view coordinate space to the logical
1324 * coordinate space of the model.
1325 *
1326 * @param x the X coordinate >= 0
1327 * @param y the Y coordinate >= 0
1328 * @param a the allocated region in which to render
1329 * @return the location within the model that best represents the
1330 * given point in the view >= 0
1331 * @see View#viewToModel
1332 * @deprecated
1333 */
1334 @Deprecated
1335 public int viewToModel(float x, float y, Shape a) {
1336 sharedBiasReturn[0] = Position.Bias.Forward;
1337 return viewToModel(x, y, a, sharedBiasReturn);
1338 }
1339
1340 // static argument available for viewToModel calls since only
1341 // one thread at a time may call this method.
1342 static final Position.Bias[] sharedBiasReturn = new Position.Bias[1];
1343
1344 private View parent;
1345 private Element elem;
1346
1347 };