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