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  
26  
27  package javax.swing;
28  import javax.swing.plaf.*;
29  import javax.accessibility.*;
30  
31  import java.io.ObjectOutputStream;
32  import java.io.ObjectInputStream;
33  import java.io.IOException;
34  import java.util.Objects;
35  
36  
37  /**
38   * Used to display a "Tip" for a Component. Typically components provide api
39   * to automate the process of using <code>ToolTip</code>s.
40   * For example, any Swing component can use the <code>JComponent</code>
41   * <code>setToolTipText</code> method to specify the text
42   * for a standard tooltip. A component that wants to create a custom
43   * <code>ToolTip</code>
44   * display can override <code>JComponent</code>'s <code>createToolTip</code>
45   * method and use a subclass of this class.
46   * <p>
47   * See <a href="http://docs.oracle.com/javase/tutorial/uiswing/components/tooltip.html">How to Use Tool Tips</a>
48   * in <em>The Java Tutorial</em>
49   * for further documentation.
50   * <p>
51   * <strong>Warning:</strong> Swing is not thread safe. For more
52   * information see <a
53   * href="package-summary.html#threading">Swing's Threading
54   * Policy</a>.
55   * <p>
56   * <strong>Warning:</strong>
57   * Serialized objects of this class will not be compatible with
58   * future Swing releases. The current serialization support is
59   * appropriate for short term storage or RMI between applications running
60   * the same version of Swing.  As of 1.4, support for long term storage
61   * of all JavaBeans&trade;
62   * has been added to the <code>java.beans</code> package.
63   * Please see {@link java.beans.XMLEncoder}.
64   *
65   * @see JComponent#setToolTipText
66   * @see JComponent#createToolTip
67   * @author Dave Moore
68   * @author Rich Shiavi
69   */
70  @SuppressWarnings("serial")
71  public class JToolTip extends JComponent implements Accessible {
72      /**
73       * @see #getUIClassID
74       * @see #readObject
75       */
76      private static final String uiClassID = "ToolTipUI";
77  
78      String tipText;
79      JComponent component;
80  
81      /** Creates a tool tip. */
82      public JToolTip() {
83          setOpaque(true);
84          updateUI();
85      }
86  
87      /**
88       * Returns the L&amp;F object that renders this component.
89       *
90       * @return the <code>ToolTipUI</code> object that renders this component
91       */
92      public ToolTipUI getUI() {
93          return (ToolTipUI)ui;
94      }
95  
96      /**
97       * Resets the UI property to a value from the current look and feel.
98       *
99       * @see JComponent#updateUI
100      */
101     public void updateUI() {
102         setUI((ToolTipUI)UIManager.getUI(this));
103     }
104 
105 
106     /**
107      * Returns the name of the L&amp;F class that renders this component.
108      *
109      * @return the string "ToolTipUI"
110      * @see JComponent#getUIClassID
111      * @see UIDefaults#getUI
112      */
113     public String getUIClassID() {
114         return uiClassID;
115     }
116 
117 
118     /**
119      * Sets the text to show when the tool tip is displayed.
120      * The string <code>tipText</code> may be <code>null</code>.
121      *
122      * @param tipText the <code>String</code> to display
123      * @beaninfo
124      *    preferred: true
125      *        bound: true
126      *  description: Sets the text of the tooltip
127      */
128     public void setTipText(String tipText) {
129         String oldValue = this.tipText;
130         this.tipText = tipText;
131         firePropertyChange("tiptext", oldValue, tipText);
132 
133         if (!Objects.equals(oldValue, tipText)) {
134             revalidate();
135             repaint();
136         }
137     }
138 
139     /**
140      * Returns the text that is shown when the tool tip is displayed.
141      * The returned value may be <code>null</code>.
142      *
143      * @return the <code>String</code> that is displayed
144      */
145     public String getTipText() {
146         return tipText;
147     }
148 
149     /**
150      * Specifies the component that the tooltip describes.
151      * The component <code>c</code> may be <code>null</code>
152      * and will have no effect.
153      * <p>
154      * This is a bound property.
155      *
156      * @param c the <code>JComponent</code> being described
157      * @see JComponent#createToolTip
158      * @beaninfo
159      *       bound: true
160      * description: Sets the component that the tooltip describes.
161      */
162     public void setComponent(JComponent c) {
163         JComponent oldValue = this.component;
164 
165         component = c;
166         firePropertyChange("component", oldValue, c);
167     }
168 
169     /**
170      * Returns the component the tooltip applies to.
171      * The returned value may be <code>null</code>.
172      *
173      * @return the component that the tooltip describes
174      *
175      * @see JComponent#createToolTip
176      */
177     public JComponent getComponent() {
178         return component;
179     }
180 
181     /**
182      * Always returns true since tooltips, by definition,
183      * should always be on top of all other windows.
184      */
185     // package private
186     boolean alwaysOnTop() {
187         return true;
188     }
189 
190 
191     /**
192      * See <code>readObject</code> and <code>writeObject</code>
193      * in <code>JComponent</code> for more
194      * information about serialization in Swing.
195      */
196     private void writeObject(ObjectOutputStream s) throws IOException {
197         s.defaultWriteObject();
198         if (getUIClassID().equals(uiClassID)) {
199             byte count = JComponent.getWriteObjCounter(this);
200             JComponent.setWriteObjCounter(this, --count);
201             if (count == 0 && ui != null) {
202                 ui.installUI(this);
203             }
204         }
205     }
206 
207 
208     /**
209      * Returns a string representation of this <code>JToolTip</code>.
210      * This method
211      * is intended to be used only for debugging purposes, and the
212      * content and format of the returned string may vary between
213      * implementations. The returned string may be empty but may not
214      * be <code>null</code>.
215      *
216      * @return  a string representation of this <code>JToolTip</code>
217      */
218     protected String paramString() {
219         String tipTextString = (tipText != null ?
220                                 tipText : "");
221 
222         return super.paramString() +
223         ",tipText=" + tipTextString;
224     }
225 
226 
227 /////////////////
228 // Accessibility support
229 ////////////////
230 
231     /**
232      * Gets the AccessibleContext associated with this JToolTip.
233      * For tool tips, the AccessibleContext takes the form of an
234      * AccessibleJToolTip.
235      * A new AccessibleJToolTip instance is created if necessary.
236      *
237      * @return an AccessibleJToolTip that serves as the
238      *         AccessibleContext of this JToolTip
239      */
240     public AccessibleContext getAccessibleContext() {
241         if (accessibleContext == null) {
242             accessibleContext = new AccessibleJToolTip();
243         }
244         return accessibleContext;
245     }
246 
247     /**
248      * This class implements accessibility support for the
249      * <code>JToolTip</code> class.  It provides an implementation of the
250      * Java Accessibility API appropriate to tool tip user-interface elements.
251      * <p>
252      * <strong>Warning:</strong>
253      * Serialized objects of this class will not be compatible with
254      * future Swing releases. The current serialization support is
255      * appropriate for short term storage or RMI between applications running
256      * the same version of Swing.  As of 1.4, support for long term storage
257      * of all JavaBeans&trade;
258      * has been added to the <code>java.beans</code> package.
259      * Please see {@link java.beans.XMLEncoder}.
260      */
261     @SuppressWarnings("serial")
262     protected class AccessibleJToolTip extends AccessibleJComponent {
263 
264         /**
265          * Get the accessible description of this object.
266          *
267          * @return a localized String describing this object.
268          */
269         public String getAccessibleDescription() {
270             String description = accessibleDescription;
271 
272             // fallback to client property
273             if (description == null) {
274                 description = (String)getClientProperty(AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY);
275             }
276             if (description == null) {
277                 description = getTipText();
278             }
279             return description;
280         }
281 
282         /**
283          * Get the role of this object.
284          *
285          * @return an instance of AccessibleRole describing the role of the
286          * object
287          */
288         public AccessibleRole getAccessibleRole() {
289             return AccessibleRole.TOOL_TIP;
290         }
291     }
292 }