1 /*
2 * Copyright (c) 1997, 2013, 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
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 * @since 1.3
385 */
386 public void remove(int i) {
387 replace(i, 1, null);
388 }
389
390 /**
391 * Inserts a single child view. This is a convenience
392 * call to <code>replace</code>.
393 *
394 * @param offs the offset of the view to insert before >= 0
395 * @param v the view
396 * @see #replace
397 * @since 1.3
398 */
399 public void insert(int offs, View v) {
400 View[] one = new View[1];
401 one[0] = v;
402 replace(offs, 0, one);
403 }
427 *
428 * @param offset the starting index into the child views to insert
429 * the new views. This should be a value >= 0 and <= getViewCount
430 * @param length the number of existing child views to remove
431 * This should be a value >= 0 and <= (getViewCount() - offset).
432 * @param views the child views to add. This value can be
433 * <code>null</code> to indicate no children are being added
434 * (useful to remove).
435 * @since 1.3
436 */
437 public void replace(int offset, int length, View[] views) {
438 }
439
440 /**
441 * Returns the child view index representing the given position in
442 * the model. By default a view has no children so this is implemented
443 * to return -1 to indicate there is no valid child index for any
444 * position.
445 *
446 * @param pos the position >= 0
447 * @return index of the view representing the given position, or
448 * -1 if no view represents that position
449 * @since 1.3
450 */
451 public int getViewIndex(int pos, Position.Bias b) {
452 return -1;
453 }
454
455 /**
456 * Fetches the allocation for the given child view.
457 * This enables finding out where various views
458 * are located, without assuming how the views store
459 * their location. This returns <code>null</code> since the
460 * default is to not have any child views.
461 *
462 * @param index the index of the child, >= 0 && <
463 * <code>getViewCount()</code>
464 * @param a the allocation to this view
465 * @return the allocation to the child
466 */
467 public Shape getChildAllocation(int index, Shape a) {
468 return null;
469 }
470
471 /**
472 * Provides a way to determine the next visually represented model
473 * location at which one might place a caret.
474 * Some views may not be visible,
475 * they might not be in the same order found in the model, or they just
476 * might not allow access to some of the locations in the model.
477 * This method enables specifying a position to convert
478 * within the range of >=0. If the value is -1, a position
479 * will be calculated automatically. If the value < -1,
480 * the {@code BadLocationException} will be thrown.
481 *
482 * @param pos the position to convert
483 * @param a the allocated region in which to render
484 * @param direction the direction from the current position that can
485 * be thought of as the arrow keys typically found on a keyboard.
486 * This will be one of the following values:
487 * <ul>
488 * <li>SwingConstants.WEST
489 * <li>SwingConstants.EAST
490 * <li>SwingConstants.NORTH
491 * <li>SwingConstants.SOUTH
492 * </ul>
493 * @return the location within the model that best represents the next
494 * location visual position
495 * @exception BadLocationException the given position is not a valid
496 * position within the document
497 * @exception IllegalArgumentException if <code>direction</code>
498 * doesn't have one of the legal values above
499 */
500 public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,
501 int direction, Position.Bias[] biasRet)
502 throws BadLocationException {
503 if (pos < -1 || pos > getDocument().getLength()) {
504 // -1 is a reserved value, see the code below
505 throw new BadLocationException("Invalid position", pos);
506 }
507
508 biasRet[0] = Position.Bias.Forward;
509 switch (direction) {
510 case NORTH:
511 case SOUTH:
512 {
645 // If it spans lines, force it to be the width of the view.
646 Rectangle alloc = (a instanceof Rectangle) ? (Rectangle)a :
647 a.getBounds();
648 r0.x = alloc.x;
649 r0.width = alloc.width;
650 }
651 r0.add(r1);
652 return r0;
653 }
654
655 /**
656 * Provides a mapping from the view coordinate space to the logical
657 * coordinate space of the model. The <code>biasReturn</code>
658 * argument will be filled in to indicate that the point given is
659 * closer to the next character in the model or the previous
660 * character in the model.
661 *
662 * @param x the X coordinate >= 0
663 * @param y the Y coordinate >= 0
664 * @param a the allocated region in which to render
665 * @return the location within the model that best represents the
666 * given point in the view >= 0. The <code>biasReturn</code>
667 * argument will be
668 * filled in to indicate that the point given is closer to the next
669 * character in the model or the previous character in the model.
670 */
671 public abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn);
672
673 /**
674 * Gives notification that something was inserted into
675 * the document in a location that this view is responsible for.
676 * To reduce the burden to subclasses, this functionality is
677 * spread out into the following calls that subclasses can
678 * reimplement:
679 * <ol>
680 * <li>{@link #updateChildren updateChildren} is called
681 * if there were any changes to the element this view is
682 * responsible for. If this view has child views that are
683 * represent the child elements, then this method should do
684 * whatever is necessary to make sure the child views correctly
847 * @since 1.3
848 */
849 public Graphics getGraphics() {
850 // PENDING(prinz) this is a temporary implementation
851 Component c = getContainer();
852 return c.getGraphics();
853 }
854
855 /**
856 * Fetches the attributes to use when rendering. By default
857 * this simply returns the attributes of the associated element.
858 * This method should be used rather than using the element
859 * directly to obtain access to the attributes to allow
860 * view-specific attributes to be mixed in or to allow the
861 * view to have view-specific conversion of attributes by
862 * subclasses.
863 * Each view should document what attributes it recognizes
864 * for the purpose of rendering or layout, and should always
865 * access them through the <code>AttributeSet</code> returned
866 * by this method.
867 */
868 public AttributeSet getAttributes() {
869 return elem.getAttributes();
870 }
871
872 /**
873 * Tries to break this view on the given axis. This is
874 * called by views that try to do formatting of their
875 * children. For example, a view of a paragraph will
876 * typically try to place its children into row and
877 * views representing chunks of text can sometimes be
878 * broken down into smaller pieces.
879 * <p>
880 * This is implemented to return the view itself, which
881 * represents the default behavior on not being
882 * breakable. If the view does support breaking, the
883 * starting offset of the view returned should be the
884 * given offset, and the end offset should be less than
885 * or equal to the end offset of the view being broken.
886 *
1009 }
1010
1011 /**
1012 * Fetches the <code>ViewFactory</code> implementation that is feeding
1013 * the view hierarchy. Normally the views are given this
1014 * as an argument to updates from the model when they
1015 * are most likely to need the factory, but this
1016 * method serves to provide it at other times.
1017 *
1018 * @return the factory, <code>null</code> if none
1019 */
1020 public ViewFactory getViewFactory() {
1021 View v = getParent();
1022 return (v != null) ? v.getViewFactory() : null;
1023 }
1024
1025 /**
1026 * Returns the tooltip text at the specified location. The default
1027 * implementation returns the value from the child View identified by
1028 * the passed in location.
1029 *
1030 * @since 1.4
1031 * @see JTextComponent#getToolTipText
1032 */
1033 public String getToolTipText(float x, float y, Shape allocation) {
1034 int viewIndex = getViewIndex(x, y, allocation);
1035 if (viewIndex >= 0) {
1036 allocation = getChildAllocation(viewIndex, allocation);
1037 Rectangle rect = (allocation instanceof Rectangle) ?
1038 (Rectangle)allocation : allocation.getBounds();
1039 if (rect.contains(x, y)) {
1040 return getView(viewIndex).getToolTipText(x, y, allocation);
1041 }
1042 }
1043 return null;
1044 }
1045
1046 /**
1047 * Returns the child view index representing the given position in
1048 * the view. This iterates over all the children returning the
|
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
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 }
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 public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,
505 int direction, Position.Bias[] biasRet)
506 throws BadLocationException {
507 if (pos < -1 || pos > getDocument().getLength()) {
508 // -1 is a reserved value, see the code below
509 throw new BadLocationException("Invalid position", pos);
510 }
511
512 biasRet[0] = Position.Bias.Forward;
513 switch (direction) {
514 case NORTH:
515 case SOUTH:
516 {
649 // If it spans lines, force it to be the width of the view.
650 Rectangle alloc = (a instanceof Rectangle) ? (Rectangle)a :
651 a.getBounds();
652 r0.x = alloc.x;
653 r0.width = alloc.width;
654 }
655 r0.add(r1);
656 return r0;
657 }
658
659 /**
660 * Provides a mapping from the view coordinate space to the logical
661 * coordinate space of the model. The <code>biasReturn</code>
662 * argument will be filled in to indicate that the point given is
663 * closer to the next character in the model or the previous
664 * character in the model.
665 *
666 * @param x the X coordinate >= 0
667 * @param y the Y coordinate >= 0
668 * @param a the allocated region in which to render
669 * @param biasReturn the returned bias
670 * @return the location within the model that best represents the
671 * given point in the view >= 0. The <code>biasReturn</code>
672 * argument will be
673 * filled in to indicate that the point given is closer to the next
674 * character in the model or the previous character in the model.
675 */
676 public abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn);
677
678 /**
679 * Gives notification that something was inserted into
680 * the document in a location that this view is responsible for.
681 * To reduce the burden to subclasses, this functionality is
682 * spread out into the following calls that subclasses can
683 * reimplement:
684 * <ol>
685 * <li>{@link #updateChildren updateChildren} is called
686 * if there were any changes to the element this view is
687 * responsible for. If this view has child views that are
688 * represent the child elements, then this method should do
689 * whatever is necessary to make sure the child views correctly
852 * @since 1.3
853 */
854 public Graphics getGraphics() {
855 // PENDING(prinz) this is a temporary implementation
856 Component c = getContainer();
857 return c.getGraphics();
858 }
859
860 /**
861 * Fetches the attributes to use when rendering. By default
862 * this simply returns the attributes of the associated element.
863 * This method should be used rather than using the element
864 * directly to obtain access to the attributes to allow
865 * view-specific attributes to be mixed in or to allow the
866 * view to have view-specific conversion of attributes by
867 * subclasses.
868 * Each view should document what attributes it recognizes
869 * for the purpose of rendering or layout, and should always
870 * access them through the <code>AttributeSet</code> returned
871 * by this method.
872 * @return the attributes to use when rendering
873 */
874 public AttributeSet getAttributes() {
875 return elem.getAttributes();
876 }
877
878 /**
879 * Tries to break this view on the given axis. This is
880 * called by views that try to do formatting of their
881 * children. For example, a view of a paragraph will
882 * typically try to place its children into row and
883 * views representing chunks of text can sometimes be
884 * broken down into smaller pieces.
885 * <p>
886 * This is implemented to return the view itself, which
887 * represents the default behavior on not being
888 * breakable. If the view does support breaking, the
889 * starting offset of the view returned should be the
890 * given offset, and the end offset should be less than
891 * or equal to the end offset of the view being broken.
892 *
1015 }
1016
1017 /**
1018 * Fetches the <code>ViewFactory</code> implementation that is feeding
1019 * the view hierarchy. Normally the views are given this
1020 * as an argument to updates from the model when they
1021 * are most likely to need the factory, but this
1022 * method serves to provide it at other times.
1023 *
1024 * @return the factory, <code>null</code> if none
1025 */
1026 public ViewFactory getViewFactory() {
1027 View v = getParent();
1028 return (v != null) ? v.getViewFactory() : null;
1029 }
1030
1031 /**
1032 * Returns the tooltip text at the specified location. The default
1033 * implementation returns the value from the child View identified by
1034 * the passed in location.
1035 * @param x the x coordinate
1036 * @param y the y coordinate
1037 * @param allocation current allocation of the View.
1038 * @return the tooltip text at the specified location
1039 *
1040 * @since 1.4
1041 * @see JTextComponent#getToolTipText
1042 */
1043 public String getToolTipText(float x, float y, Shape allocation) {
1044 int viewIndex = getViewIndex(x, y, allocation);
1045 if (viewIndex >= 0) {
1046 allocation = getChildAllocation(viewIndex, allocation);
1047 Rectangle rect = (allocation instanceof Rectangle) ?
1048 (Rectangle)allocation : allocation.getBounds();
1049 if (rect.contains(x, y)) {
1050 return getView(viewIndex).getToolTipText(x, y, allocation);
1051 }
1052 }
1053 return null;
1054 }
1055
1056 /**
1057 * Returns the child view index representing the given position in
1058 * the view. This iterates over all the children returning the
|