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&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<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 }