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 23 * questions. 24 */ 25 26 27 package javax.swing; 28 29 import javax.swing.plaf.*; 30 import javax.accessibility.*; 31 32 import java.beans.BeanProperty; 33 import java.io.ObjectOutputStream; 34 import java.io.ObjectInputStream; 35 import java.io.IOException; 36 import java.util.Objects; 37 38 39 /** 40 * Used to display a "Tip" for a Component. Typically components provide api 41 * to automate the process of using <code>ToolTip</code>s. 42 * For example, any Swing component can use the <code>JComponent</code> 43 * <code>setToolTipText</code> method to specify the text 44 * for a standard tooltip. A component that wants to create a custom 45 * <code>ToolTip</code> 46 * display can override <code>JComponent</code>'s <code>createToolTip</code> 47 * method and use a subclass of this class. 48 * <p> 49 * See <a href="https://docs.oracle.com/javase/tutorial/uiswing/components/tooltip.html">How to Use Tool Tips</a> 50 * in <em>The Java Tutorial</em> 51 * for further documentation. 52 * <p> 53 * <strong>Warning:</strong> Swing is not thread safe. For more 54 * information see <a 55 * href="package-summary.html#threading">Swing's Threading 56 * Policy</a>. 57 * <p> 58 * <strong>Warning:</strong> 59 * Serialized objects of this class will not be compatible with 60 * future Swing releases. The current serialization support is 61 * appropriate for short term storage or RMI between applications running 62 * the same version of Swing. As of 1.4, support for long term storage 63 * of all JavaBeans™ 64 * has been added to the <code>java.beans</code> package. 65 * Please see {@link java.beans.XMLEncoder}. 66 * 67 * @see JComponent#setToolTipText 68 * @see JComponent#createToolTip 69 * @author Dave Moore 70 * @author Rich Shiavi 71 * @since 1.2 72 */ 73 @SuppressWarnings("serial") 74 public class JToolTip extends JComponent implements Accessible { 75 /** 76 * @see #getUIClassID 77 * @see #readObject 78 */ 79 private static final String uiClassID = "ToolTipUI"; 80 81 String tipText; 82 JComponent component; 83 84 /** Creates a tool tip. */ 85 public JToolTip() { 86 setOpaque(true); 87 updateUI(); 88 } 89 90 /** 91 * Returns the L&F object that renders this component. 92 * 93 * @return the <code>ToolTipUI</code> object that renders this component 94 */ 95 public ToolTipUI getUI() { 96 return (ToolTipUI)ui; 97 } 98 99 /** 100 * Resets the UI property to a value from the current look and feel. 101 * 102 * @see JComponent#updateUI 103 */ 104 public void updateUI() { 105 setUI((ToolTipUI)UIManager.getUI(this)); 106 } 107 108 109 /** 110 * Returns the name of the L&F class that renders this component. 111 * 112 * @return the string "ToolTipUI" 113 * @see JComponent#getUIClassID 114 * @see UIDefaults#getUI 115 */ 116 public String getUIClassID() { 117 return uiClassID; 118 } 119 120 121 /** 122 * Sets the text to show when the tool tip is displayed. 123 * The string <code>tipText</code> may be <code>null</code>. 124 * 125 * @param tipText the <code>String</code> to display 126 */ 127 @BeanProperty(preferred = true, description 128 = "Sets the text of the tooltip") 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 */ 160 @BeanProperty(description 161 = "Sets the component that the tooltip describes.") 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™ 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 }