org.openide.util.HelpCtx Maven / Gradle / Ivy
The newest version!
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common
* Development and Distribution License("CDDL") (collectively, the
* "License"). You may not use this file except in compliance with the
* License. You can obtain a copy of the License at
* http://www.netbeans.org/cddl-gplv2.html
* or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
* specific language governing permissions and limitations under the
* License. When distributing the software, include this License Header
* Notice in each file and include the License file at
* nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the GPL Version 2 section of the License file that
* accompanied this code. If applicable, add the following below the
* License Header, with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Contributor(s):
*
* The Original Software is NetBeans. The Initial Developer of the Original
* Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
* Microsystems, Inc. All Rights Reserved.
*
* If you wish your version of this file to be governed by only the CDDL
* or only the GPL Version 2, indicate your decision by adding
* "[Contributor] elects to include this software in this distribution
* under the [CDDL or GPL Version 2] license." If you do not indicate a
* single choice of license, a recipient has the option to distribute
* your version of this file under either the CDDL, the GPL Version 2 or
* to extend the choice of license to its licensees as provided above.
* However, if you add GPL Version 2 code and therefore, elected the GPL
* Version 2 license, then the option applies only if the new code is
* made subject to such option by the copyright holder.
*/
package org.openide.util;
import java.beans.BeanDescriptor;
import java.beans.IntrospectionException;
import java.beans.Introspector;
import java.net.URL;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.swing.JComponent;
/** Provides help for any window or other feature in the system.
* It is designed to be JavaHelp-compatible and to use the same tactics when
* assigning help to {@link JComponent} instances.
* @see JavaHelp Integration API
* @author Petr Hamernik, Jaroslav Tulach, Jesse Glick
*/
public final class HelpCtx extends Object {
private static final Logger err = Logger.getLogger("org.openide.util.HelpCtx"); // NOI18N
/** Default help page.
* This (hopefully) points to a note explaining to the user that no help is available.
* Precisely, the Help ID is set to org.openide.util.HelpCtx.DEFAULT_HELP.
*/
public final static HelpCtx DEFAULT_HELP = new HelpCtx(HelpCtx.class.getName() + ".DEFAULT_HELP"); // NOI18N
/** URL of the help page */
private final URL helpCtx;
/** JavaHelp ID for the help */
private final String helpID;
/** Create a help context by URL.
* @deprecated Does not work nicely with JavaHelp.
* @param helpCtx URL to point help to
*/
@Deprecated
public HelpCtx(URL helpCtx) {
this.helpCtx = helpCtx;
this.helpID = null;
}
/** Create a help context by tag.
* You must provide an ID of the
* desired help for the item. The ID should refer to an
* already installed help; this can be easily installed by specifying
* a JavaHelp help set for the module (see the Modules API for details).
*
* @param helpID the JavaHelp ID of the help
*/
public HelpCtx(String helpID) {
this.helpID = helpID;
this.helpCtx = null;
}
/** Create a help context by class.
* Assigns the name of a class as
* the ID.
*
* @param clazz the class to take the name from
*/
public HelpCtx(Class clazz) {
this(clazz.getName());
}
/** Get a URL to the help page, if applicable.
* @return a URL to the page, or null if the target was specified by ID
*/
public URL getHelp() {
return helpCtx;
}
/** Get the ID of the help page, if applicable.
* @return the JavaHelp ID string, or null if specified by URL
*/
public String getHelpID() {
return helpID;
}
// object identity
public int hashCode() {
int base = HelpCtx.class.hashCode();
if (helpCtx != null) {
base ^= helpCtx.hashCode();
}
if (helpID != null) {
base ^= helpID.hashCode();
}
return base;
}
public boolean equals(Object o) {
if ((o == null) || !(o instanceof HelpCtx)) {
return false;
}
HelpCtx oo = (HelpCtx) o;
return ((helpCtx == oo.helpCtx) || ((helpCtx != null) && helpCtx.equals(oo.helpCtx))) &&
((helpID == oo.helpID) || ((helpID != null) && helpID.equals(oo.helpID)));
}
public String toString() {
if (helpID != null) {
return "HelpCtx[" + helpID + "]"; // NOI18N
} else {
return "HelpCtx[" + helpCtx + "]"; // NOI18N
}
}
/** Set the help ID for a component.
* @param comp the visual component to associate help to
* @param helpID help ID, or null if the help ID should be removed
*/
public static void setHelpIDString(JComponent comp, String helpID) {
err.fine("setHelpIDString: " + helpID + " on " + comp);
comp.putClientProperty("HelpID", helpID); // NOI18N
}
/** Find the help ID for a component.
* If the component implements {@link org.openide.util.HelpCtx.Provider},
* its method {@link org.openide.util.HelpCtx.Provider#getHelpCtx} is called.
* If the component has help attached by {@link #setHelpIDString}, it returns that.
* Otherwise it checks the parent component recursively.
*
* @param comp the component to find help for
* @return the help for that component (never null)
*/
public static HelpCtx findHelp(java.awt.Component comp) {
if (err.isLoggable(Level.FINEST)) {
err.log(Level.FINEST, "findHelp on " + comp, new Exception());
} else {
err.fine("findHelp on " + comp);
}
while (comp != null) {
if (comp instanceof HelpCtx.Provider) {
HelpCtx h = ((HelpCtx.Provider) comp).getHelpCtx();
err.fine("found help " + h + " through HelpCtx.Provider interface");
return h;
}
if (comp instanceof JComponent) {
JComponent jc = (JComponent) comp;
String hid = (String) jc.getClientProperty("HelpID"); // NOI18N
if (hid != null) {
err.fine("found help " + hid + " by client property");
return new HelpCtx(hid);
}
}
comp = comp.getParent();
err.fine("no luck, trying parent " + comp);
}
err.fine("nothing found");
return DEFAULT_HELP;
}
/** Finds help context for a generic object. Right now checks
* for HelpCtx.Provider and handles java.awt.Component in a
* special way compatible with JavaHelp.
* Also {@link BeanDescriptor}'s are checked for a string-valued attribute
* helpID, as per the JavaHelp specification (but no help sets
* will be loaded).
*
* @param instance to search help for
* @return the help for the object or HelpCtx.DEFAULT_HELP if HelpCtx cannot be found
*
* @since 4.3
*/
public static HelpCtx findHelp(Object instance) {
if (instance instanceof java.awt.Component) {
return findHelp((java.awt.Component) instance);
}
if (instance instanceof HelpCtx.Provider) {
return ((HelpCtx.Provider) instance).getHelpCtx();
}
try {
BeanDescriptor d = Introspector.getBeanInfo(instance.getClass()).getBeanDescriptor();
String v = (String) d.getValue("helpID"); // NOI18N
if (v != null) {
return new HelpCtx(v);
}
} catch (IntrospectionException e) {
err.fine("findHelp on " + instance + ": " + e);
}
return HelpCtx.DEFAULT_HELP;
}
/**
* An object implementing this interface is willing to answer
* the HelpCtx.findHelp() query itself.
*
* @since 3.20
*/
public static interface Provider {
/**
* Get the {@link HelpCtx} associated with implementing object.
* @return assigned HelpCtx or
* {@link #DEFAULT_HELP}, never null.
*/
public HelpCtx getHelpCtx();
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy