1 /* 2 * Copyright (c) 1997, 2006, 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://java.sun.com/docs/books/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<sup><font size="-2">TM</font></sup> 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&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&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<sup><font size="-2">TM</font></sup> 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 }