HelpCtx


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.openide.util;
21  
22  import java.beans.BeanDescriptor  ;
23  import java.beans.IntrospectionException  ;
24  import java.beans.Introspector  ;
25  import java.net.URL  ;
26  import java.util.logging.Logger  ;
27  import javax.swing.JComponent  ;
28  
29  /** Provides help for any window or other feature in the system.
30  * It is designed to be JavaHelp-compatible and to use the same tactics when
31  * assigning help to {@link JComponent} instances.
32  * @see <a HREF="@org-netbeans-modules-javahelp@/">JavaHelp Integration API</a>
33  * @author Petr Hamernik, Jaroslav Tulach, Jesse Glick
34  */
35  public final class HelpCtx extends Object   {
36      private static final Logger   err = Logger.getLogger("org.openide.util.HelpCtx"); // NOI18N
37  
38      /** Default help page.
39      * This (hopefully) points to a note explaining to the user that no help is available.
40      * Precisely, the Help ID is set to <code>org.openide.util.HelpCtx.DEFAULT_HELP</code>.
41      */
42      public final static HelpCtx DEFAULT_HELP = new HelpCtx(HelpCtx.class.getName() + ".DEFAULT_HELP"); // NOI18N
43  
44      /** URL of the help page */
45      private final URL   helpCtx;
46  
47      /** JavaHelp ID for the help */
48      private final String   helpID;
49  
50      /** Create a help context by URL.
51       * @deprecated Does not work nicely with JavaHelp.
52      * @param helpCtx URL to point help to
53      */
54      @Deprecated  
55      public HelpCtx(URL   helpCtx) {
56          this.helpCtx = helpCtx;
57          this.helpID = null;
58      }
59  
60      /** Create a help context by tag.
61      * You must provide an ID of the
62      * desired help for the item. The ID should refer to an
63      * already installed help; this can be easily installed by specifying
64      * a JavaHelp help set for the module (see the Modules API for details).
65      *
66      * @param helpID the JavaHelp ID of the help
67      */
68      public HelpCtx(String   helpID) {
69          this.helpID = helpID;
70          this.helpCtx = null;
71      }
72  
73      /** Create a help context by class.
74      * Assigns the name of a class as
75      * the ID.
76      *
77      * @param clazz the class to take the name from
78      */
79      public HelpCtx(Class   clazz) {
80          this(clazz.getName());
81      }
82  
83      /** Get a URL to the help page, if applicable.
84      * @return a URL to the page, or <code>null</code> if the target was specified by ID
85      */
86      public URL   getHelp() {
87          return helpCtx;
88      }
89  
90      /** Get the ID of the help page, if applicable.
91      * @return the JavaHelp ID string, or <code>null</code> if specified by URL
92      */
93      public String   getHelpID() {
94          return helpID;
95      }
96  
97      // object identity
98      public int hashCode() {
99          int base = HelpCtx.class.hashCode();
100 
101         if (helpCtx != null) {
102             base ^= helpCtx.hashCode();
103         }
104 
105         if (helpID != null) {
106             base ^= helpID.hashCode();
107         }
108 
109         return base;
110     }
111 
112     public boolean equals(Object   o) {
113         if ((o == null) || !(o instanceof HelpCtx)) {
114             return false;
115         }
116 
117         HelpCtx oo = (HelpCtx) o;
118 
119         return ((helpCtx == oo.helpCtx) || ((helpCtx != null) && helpCtx.equals(oo.helpCtx))) &&
120         ((helpID == oo.helpID) || ((helpID != null) && helpID.equals(oo.helpID)));
121     }
122 
123     public String   toString() {
124         if (helpID != null) {
125             return "HelpCtx[" + helpID + "]"; // NOI18N
126         } else {
127             return "HelpCtx[" + helpCtx + "]"; // NOI18N
128         }
129     }
130 
131     /** Set the help ID for a component.
132     * @param comp the visual component to associate help to
133     * @param helpID help ID, or <code>null</code> if the help ID should be removed
134     */
135     public static void setHelpIDString(JComponent   comp, String   helpID) {
136         err.fine("setHelpIDString: " + helpID + " on " + comp);
137 
138         comp.putClientProperty("HelpID", helpID); // NOI18N
139     }
140 
141     /** Find the help ID for a component.
142      * If the component implements {@link org.openide.util.HelpCtx.Provider},
143      * its method {@link org.openide.util.HelpCtx.Provider#getHelpCtx} is called.
144      * If the component has help attached by {@link #setHelpIDString}, it returns that.
145      * Otherwise it checks the parent component recursively.
146      *
147      * @param comp the component to find help for
148      * @return the help for that component (never <code>null</code>)
149      */
150     public static HelpCtx findHelp(java.awt.Component   comp) {
151         err.fine("findHelp on " + comp);
152 
153         while (comp != null) {
154             if (comp instanceof HelpCtx.Provider) {
155                 HelpCtx h = ((HelpCtx.Provider) comp).getHelpCtx();
156 
157                 err.fine("found help " + h + " through HelpCtx.Provider interface");
158 
159                 return h;
160             }
161 
162             if (comp instanceof JComponent  ) {
163                 JComponent   jc = (JComponent  ) comp;
164                 String   hid = (String  ) jc.getClientProperty("HelpID"); // NOI18N
165 
166                 if (hid != null) {
167                     err.fine("found help " + hid + " by client property");
168 
169                     return new HelpCtx(hid);
170                 }
171             }
172 
173             comp = comp.getParent();
174 
175             err.fine("no luck, trying parent " + comp);
176         }
177 
178         err.fine("nothing found");
179 
180         return DEFAULT_HELP;
181     }
182 
183     /** Finds help context for a generic object. Right now checks
184      * for HelpCtx.Provider and handles java.awt.Component in a
185      * special way compatible with JavaHelp.
186      * Also {@link BeanDescriptor}'s are checked for a string-valued attribute
187      * <code>helpID</code>, as per the JavaHelp specification (but no help sets
188      * will be loaded).
189      *
190      * @param instance to search help for
191      * @return the help for the object or <code>HelpCtx.DEFAULT_HELP</code> if HelpCtx cannot be found
192      *
193      * @since 4.3
194      */
195     public static HelpCtx findHelp(Object   instance) {
196         if (instance instanceof java.awt.Component  ) {
197             return findHelp((java.awt.Component  ) instance);
198         }
199 
200         if (instance instanceof HelpCtx.Provider) {
201             return ((HelpCtx.Provider) instance).getHelpCtx();
202         }
203 
204         try {
205             BeanDescriptor   d = Introspector.getBeanInfo(instance.getClass()).getBeanDescriptor();
206             String   v = (String  ) d.getValue("helpID"); // NOI18N
207 
208             if (v != null) {
209                 return new HelpCtx(v);
210             }
211         } catch (IntrospectionException   e) {
212             err.fine("findHelp on " + instance + ": " + e);
213         }
214 
215         return HelpCtx.DEFAULT_HELP;
216     }
217 
218     /**
219      * An object implementing this interface is willing to answer
220      * the HelpCtx.findHelp() query itself.
221      *
222      * @since 3.20
223      */
224     public static interface Provider {
225         /**
226          * Get the {@link HelpCtx} associated with implementing object.
227          * @return assigned <code>HelpCtx</code> or
228          *         {@link #DEFAULT_HELP}, never <code>null</code>.
229          */
230         public HelpCtx getHelpCtx();
231     }
232 }
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags