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&trade;
  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&amp;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&amp;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&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 }