View Javadoc
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
23   * questions.
24   */
25  package javax.swing.plaf;
26  
27  import javax.swing.Action;
28  import javax.swing.BoundedRangeModel;
29  import java.awt.Point;
30  import java.awt.Rectangle;
31  import java.awt.Insets;
32  import javax.swing.text.*;
33  
34  /**
35   * Text editor user interface
36   *
37   * @author  Timothy Prinzing
38   */
39  public abstract class TextUI extends ComponentUI
40  {
41      /**
42       * Converts the given location in the model to a place in
43       * the view coordinate system.
44       *
45       * @param pos  the local location in the model to translate >= 0
46       * @return the coordinates as a rectangle
47       * @exception BadLocationException  if the given position does not
48       *   represent a valid location in the associated document
49       */
50      public abstract Rectangle modelToView(JTextComponent t, int pos) throws BadLocationException;
51  
52      /**
53       * Converts the given location in the model to a place in
54       * the view coordinate system.
55       *
56       * @param pos  the local location in the model to translate >= 0
57       * @return the coordinates as a rectangle
58       * @exception BadLocationException  if the given position does not
59       *   represent a valid location in the associated document
60       */
61      public abstract Rectangle modelToView(JTextComponent t, int pos, Position.Bias bias) throws BadLocationException;
62  
63      /**
64       * Converts the given place in the view coordinate system
65       * to the nearest representative location in the model.
66       *
67       * @param pt  the location in the view to translate.  This
68       *   should be in the same coordinate system as the mouse
69       *   events.
70       * @return the offset from the start of the document >= 0
71       */
72      public abstract int viewToModel(JTextComponent t, Point pt);
73  
74      /**
75       * Provides a mapping from the view coordinate space to the logical
76       * coordinate space of the model.
77       *
78       * @param pt the location in the view to translate.
79       *           This should be in the same coordinate system
80       *           as the mouse events.
81       * @param biasReturn
82       *           filled in by this method to indicate whether
83       *           the point given is closer to the previous or the next
84       *           character in the model
85       *
86       * @return the location within the model that best represents the
87       *         given point in the view >= 0
88       */
89      public abstract int viewToModel(JTextComponent t, Point pt,
90                                      Position.Bias[] biasReturn);
91  
92      /**
93       * Provides a way to determine the next visually represented model
94       * location that one might place a caret.  Some views may not be visible,
95       * they might not be in the same order found in the model, or they just
96       * might not allow access to some of the locations in the model.
97       *
98       * @param t the text component for which this UI is installed
99       * @param pos the position to convert >= 0
100      * @param b the bias for the position
101      * @param direction the direction from the current position that can
102      *  be thought of as the arrow keys typically found on a keyboard.
103      *  This may be SwingConstants.WEST, SwingConstants.EAST,
104      *  SwingConstants.NORTH, or SwingConstants.SOUTH
105      * @param biasRet an array to contain the bias for the returned position
106      * @return the location within the model that best represents the next
107      *  location visual position
108      * @exception BadLocationException
109      * @exception IllegalArgumentException for an invalid direction
110      */
111     public abstract int getNextVisualPositionFrom(JTextComponent t,
112                          int pos, Position.Bias b,
113                          int direction, Position.Bias[] biasRet)
114                          throws BadLocationException;
115 
116     /**
117      * Causes the portion of the view responsible for the
118      * given part of the model to be repainted.
119      *
120      * @param p0 the beginning of the range >= 0
121      * @param p1 the end of the range >= p0
122      */
123     public abstract void damageRange(JTextComponent t, int p0, int p1);
124 
125     /**
126      * Causes the portion of the view responsible for the
127      * given part of the model to be repainted.
128      *
129      * @param p0 the beginning of the range >= 0
130      * @param p1 the end of the range >= p0
131      */
132     public abstract void damageRange(JTextComponent t, int p0, int p1,
133                                      Position.Bias firstBias,
134                                      Position.Bias secondBias);
135 
136     /**
137      * Fetches the binding of services that set a policy
138      * for the type of document being edited.  This contains
139      * things like the commands available, stream readers and
140      * writers, etc.
141      *
142      * @return the editor kit binding
143      */
144     public abstract EditorKit getEditorKit(JTextComponent t);
145 
146     /**
147      * Fetches a View with the allocation of the associated
148      * text component (i.e. the root of the hierarchy) that
149      * can be traversed to determine how the model is being
150      * represented spatially.
151      *
152      * @return the view
153      */
154     public abstract View getRootView(JTextComponent t);
155 
156     /**
157      * Returns the string to be used as the tooltip at the passed in location.
158      *
159      * @see javax.swing.text.JTextComponent#getToolTipText
160      * @since 1.4
161      */
162     public String getToolTipText(JTextComponent t, Point pt) {
163         return null;
164     }
165 }