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