KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ca > commons > cbutil > CBHelpSystem


1 /*
2  * HelpSystem.java
3  * (modified from rescoHelpBroker, courtesy Irina)
4  * Copyright (c) 1999 by Computer Associates, Inc. All Rights Reserved.
5  * @author Chris Betts
6  */
7
8 package com.ca.commons.cbutil;
9
10 import javax.help.HelpBroker;
11 import javax.help.HelpSet;
12 import javax.swing.*;
13 import java.net.URL JavaDoc;
14 import java.util.logging.Level JavaDoc;
15 import java.util.logging.Logger JavaDoc;
16
17 /**
18  * A wrapper around the JavaHelp system.
19  */
20 public class CBHelpSystem
21 {
22     private String JavaDoc helpSetName; // name of the help set
23 private HelpSet helpSet = null; // manages data
24 private HelpBroker helpBroker; // manages help viewer
25
26     private ClassLoader JavaDoc myClassLoader;
27
28     boolean setup = false;
29
30     private static CBHelpSystem defaultHelpSystem; // a 'global' help set, usually the first constructed.
31
32     private static Logger JavaDoc log = Logger.getLogger(CBHelpSystem.class.getName());
33
34     /**
35      * fires up the Help Broker, using the passed help file name (which
36      * is checked for localisation).
37      *
38      * @param helpset_Name name of the help set (and path)
39      */
40
41     public CBHelpSystem(String JavaDoc helpset_Name)
42     {
43         this(helpset_Name, null);
44         if (defaultHelpSystem == null)
45             defaultHelpSystem = this;
46         runDelayedConstructor();
47     }
48
49     /**
50      * fires up the Help Broker, using the passed help file name (which
51      * is checked for localisation).
52      *
53      * @param helpset_Name name of the help set (and path)
54      * @param cl the class loader used to load the help set url.
55      */
56 //TE: XXXXXXXXXX why does this get run twice on start up?
57 public CBHelpSystem(String JavaDoc helpset_Name, ClassLoader JavaDoc cl)
58     {
59         if (cl != null) myClassLoader = cl;
60         if (helpset_Name != null) helpSetName = helpset_Name;
61         runDelayedConstructor();
62         if (defaultHelpSystem == null)
63             defaultHelpSystem = this;
64     }
65
66     public boolean ready()
67     {
68         return setup;
69     }
70
71     private synchronized void runDelayedConstructor()
72     {
73 /* THREAD PROBLEMS?
74         Thread worker = new Thread()
75         {
76             public void run()
77             {
78 */
79         doDelayedConstructor();
80 /*
81             }
82         };
83         worker.setPriority(2);
84         worker.start();
85 */
86     }
87
88     /**
89      * A piece of performance evil; delay actually doing all the help
90      * initialisation until we *really* have to ('cause it's so darn expensive)
91      */
92     protected synchronized void doDelayedConstructor()
93     {
94         if (setup == true) return; // only run once.
95
96         if (myClassLoader == null)
97             myClassLoader = getClass().getClassLoader();
98
99         helpSet = getHelpSet(helpSetName, myClassLoader);
100
101         if (helpSet == null)
102         {
103             log.warning("Error creating help set! Can't find: " + helpSetName);
104             return; // leaving setup==false in case we want to try again...
105 }
106         else
107         {
108             helpBroker = helpSet.createHelpBroker();
109         }
110
111         log.info("Initial HelpSet created: " + helpSet.toString());
112
113         setup = true; // we've now constructed the help object!
114 }
115
116
117     public synchronized HelpSet getHelpSet()
118     {
119         return helpSet;
120     }
121
122     public synchronized HelpBroker getHelpBroker()
123     {
124         return helpBroker;
125     }
126
127     /**
128      * Uses the specified class loader (or the default, if the class loader is
129      * null) to look up the named help set, and return it.
130      *
131      * @param newHelpSetName the class loader to use for looking up the help set - or null
132      * if the default class loader is to be used.
133      * @param loader the base name of the help set (without any
134      * localisation extensions.)
135      */
136
137     public static HelpSet getHelpSet(String JavaDoc newHelpSetName, ClassLoader JavaDoc loader)
138     {
139         HelpSet newHelpSet = null;
140         try
141         {
142             URL JavaDoc url = HelpSet.findHelpSet(loader, newHelpSetName);
143             if (url != null)
144                 newHelpSet = new HelpSet(loader, url);
145         }
146         catch (NoClassDefFoundError JavaDoc ec)
147         {
148             log.log(Level.WARNING, "Help Broker initialization error: couldn't find help set ", ec);
149         }
150         catch (ExceptionInInitializerError JavaDoc ex)
151         {
152             log.log(Level.WARNING, "Help Broker initialization error: ", ex);
153             ex.getException().printStackTrace(); // very rare error - keep for debugging...
154 }
155         catch (Exception JavaDoc ee)
156         {
157             log.log(Level.WARNING, "Help Set '" + newHelpSetName + "' not found", ee);
158         }
159
160         return newHelpSet;
161     }
162
163     /**
164      * Appends a new help set to the main help set - useful for plugin help sets.
165      *
166      * @param loader - the class loader used to find the plugin help set
167      * @param pluginHelpSet - the
168      */
169
170     public void addHelpSet(String JavaDoc pluginHelpSet, ClassLoader JavaDoc loader)
171     {
172         if (helpSet != null)
173             helpSet.add(getHelpSet(pluginHelpSet, loader));
174         else // we don't have a help set - grab this one and use it.
175 {
176             helpSet = getHelpSet(pluginHelpSet, loader);
177             if (helpSet != null)
178                 helpBroker = helpSet.createHelpBroker();
179         }
180     }
181
182     public void addHelpSet(HelpSet newSet)
183     {
184         if (newSet == null) return;
185
186         if (helpSet != null)
187             helpSet.add(newSet);
188         else // we don't have a help set - grab this one and use it.
189 {
190             helpSet = newSet;
191             if (helpSet != null)
192                 helpBroker = helpSet.createHelpBroker();
193         }
194     }
195
196
197     /**
198      * Show the help window
199      */
200
201     public void open()
202     {
203         if (setup == false)
204             doDelayedConstructor();
205
206         if (helpBroker != null)
207             helpBroker.setDisplayed(true);
208     }
209
210
211     /**
212      * Show the help window with the specified tab opened.
213      * If there is an error (IllegalArgumentException) open() is called.'
214      *
215      * @param tab the tab name...options should be either 'TOC', 'Index' or 'Search'.
216      */
217
218     public void openTab(String JavaDoc tab)
219     {
220         if (setup == false)
221             doDelayedConstructor();
222
223         if (helpBroker != null)
224         {
225             try
226             {
227                 helpBroker.setCurrentView(tab);
228             }
229             catch (IllegalArgumentException JavaDoc ia)
230             {
231                 log.warning("Caught Illegal Argument Exception - an incorrect Help view was asked for: "
232                         + ia + "\n\nOpening help with default view...");
233                 open();
234                 return;
235             }
236
237             helpBroker.setDisplayed(true);
238         }
239     }
240
241
242     /**
243      * Shows the help window at a defined location (specifically set up for dialog help buttons).
244      *
245      * @param contentID the location (or topic ID) to be displayed when the help opens.
246      */
247
248     public void open(String JavaDoc contentID)
249     {
250         if (setup == false)
251             doDelayedConstructor();
252
253         if (helpBroker != null)
254             helpBroker.setDisplayed(true);
255
256         try
257         {
258             helpBroker.setCurrentID(contentID);
259         }
260         catch (Exception JavaDoc e)
261         {
262             log.log(Level.WARNING, "Caught exception: ", e);
263         }
264     }
265
266
267     public static void setdefaultHelpSystem(CBHelpSystem set)
268     {
269         defaultHelpSystem = set;
270     }
271
272     public static CBHelpSystem getDefaultHelpSystem()
273     {
274         return defaultHelpSystem;
275     }
276
277     public static void addToDefaultHelpSystem(String JavaDoc newHelpSet, ClassLoader JavaDoc loader)
278     {
279         log.info("attempting to add help set: '" + newHelpSet + "' using loader: " + loader.toString());
280
281         if (defaultHelpSystem == null)
282         {
283             CBHelpSystem newDefault = new CBHelpSystem(newHelpSet, loader);
284             //HelpSet bloop = getHelpSet(newHelpSet, loader);
285 log.info("trying to set default help system to: " + ((newDefault == null) ? "null" : newDefault.toString()));
286             if (newDefault != null)
287                 setdefaultHelpSystem(newDefault);
288         }
289         else
290         {
291             HelpSet bloop = getHelpSet(newHelpSet, loader);
292             log.info("found help set: " + ((bloop == null) ? " null " : bloop.toString()));
293             defaultHelpSystem.addHelpSet(bloop);
294         }
295     }
296
297
298     /**
299      * Sets up a help button with a listener that when clicked will open the
300      * at the defined location in java help. Solves the modal problem too.
301      *
302      * @param button the help button.
303      * @param helpString the map ID (java help location that is to be displayed).
304      */
305
306     public static void useDefaultHelp(JButton button, String JavaDoc helpString)
307     {
308         // do we want to make a global default help broker...?
309
310         if (helpString == null)
311             return; // nothing to do.
312
313         if (defaultHelpSystem == null)
314             log.warning("No default HelpSystem.");
315
316         if (defaultHelpSystem.ready() == false)
317             defaultHelpSystem.doDelayedConstructor();
318
319         try
320         {
321             HelpBroker helpBrok = defaultHelpSystem.getHelpSet().createHelpBroker();
322             helpBrok.enableHelpOnButton(button, helpString, defaultHelpSystem.getHelpSet());
323         }
324         catch (Exception JavaDoc e)
325         {
326             log.log(Level.WARNING, "No HelpSet available: ", e);
327         }
328     }
329
330
331 }
Popular Tags