HelpSystem


1   /*******************************************************************************
2    * Copyright (c) 2003, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.help;
12  
13  import java.io.InputStream  ;
14  
15  import org.eclipse.core.runtime.Platform;
16  import org.eclipse.help.internal.HelpPlugin;
17  import org.eclipse.help.internal.HelpPlugin.IHelpProvider;
18  
19  /**
20   * This class provides general access to help content contributed to the
21   * <code>"org.eclipse.help.toc"</code> and
22   * <code>"org.eclipse.help.contexts"</code> extension points.
23   * <p>
24   * This class provides static methods only; it is not intended to be
25   * instantiated or subclassed.
26   * </p>
27   * 
28   * @since 3.0
29   */
30  public final class HelpSystem {
31  
32      private static boolean fShared;
33      
34      /**
35       * This class is not intended to be instantiated.
36       */
37      private HelpSystem() {
38          // do nothing
39      }
40  
41      /**
42       * Computes and returns context information for the given context id
43       * for the platform's current locale.
44       * 
45       * @param contextId the context id, e.g. "org.my.plugin.my_id"
46       * @return the context, or <code>null</code> if none
47       */
48      public static IContext getContext(String   contextId) {
49          return HelpPlugin.getContextManager().getContext(contextId, Platform.getNL());
50      }
51  
52      /**
53       * Computes and returns context information for the given context id
54       * and locale.
55       * 
56       * @param contextId the context id, e.g. "org.my.plugin.my_id"
57       * @param locale the locale being requested, e.g. "en_US"
58       * @return the context, or <code>null</code> if none
59       */
60      public static IContext getContext(String   contextId, String   locale) {
61          return HelpPlugin.getContextManager().getContext(contextId, locale);
62      }
63  
64      /**
65       * Returns the list of all integrated tables of contents available. Each
66       * entry corresponds of a different help "book".
67       * 
68       * @return an array of TOC's
69       */
70      public static IToc[] getTocs() {
71          return HelpPlugin.getTocManager().getTocs(Platform.getNL());
72      }
73  
74      /**
75       * Returns the keyword index available in the help system.
76       *
77       * @return the keyword index
78       * @since 3.2
79       */
80      public static IIndex getIndex() {
81          return HelpPlugin.getIndexManager().getIndex(Platform.getNL());
82      }
83  
84      /**
85       * Returns an open input stream on the contents of the specified help
86       * resource in the platform's current locale. The client is responsible for
87       * closing the stream when finished.
88       * 
89       * @param href
90       *            the URL (as a string) of the help resource
91       *            <p>
92       *            Valid href are as described in
93       *            {@link  org.eclipse.help.IHelpResource#getHref IHelpResource.getHref}
94       *            </p>
95       * @return an input stream containing the contents of the help resource, or
96       *         <code>null</code> if the help resource could not be found and
97       *         opened
98       */
99      public static InputStream   getHelpContent(String   href) {
100         return getHelpContent(href, Platform.getNL());
101     }
102     
103     /**
104      * Returns an open input stream on the contents of the specified help
105      * resource for the speficied locale. The client is responsible for closing
106      * the stream when finished.
107      * 
108      * @param href
109      *            the URL (as a string) of the help resource
110      *            <p>
111      *            Valid href are as described in
112      *            {@link  org.eclipse.help.IHelpResource#getHref IHelpResource.getHref}
113      *            </p>
114      * @param locale the locale code, e.g. en_US
115      * @return an input stream containing the contents of the help resource, or
116      *         <code>null</code> if the help resource could not be found and
117      *         opened
118      * @since 3.0
119      */
120     public static InputStream   getHelpContent(String   href, String   locale) {
121         IHelpProvider provider = HelpPlugin.getDefault().getHelpProvider();
122         if (provider != null) {
123             return provider.getHelpContent(href, locale);
124         }
125         return null;
126     }
127 
128     /**
129      * Returns whether or not the help system, in its current mode of operation,
130      * can be shared by multiple (potentially remote) users. This is a hint to
131      * the help system implementation that it should not perform operations that
132      * are specific to the help system's local environment.
133      * 
134      * <p>
135      * For example, when <code>true</code>, the default dynamic content producer
136      * implementation will not perform any filtering based on local system
137      * properties such as operating system or activities.
138      * </p>
139      * <p>
140      * If you are providing your own help implementation that is shared, you
141      * must notify the platform on startup by calling <code>setShared(true)</code>.
142      * </p>
143      * 
144      * @return whether or not the help system can be shared by multiple users
145      * @since 3.2
146      */
147     public static boolean isShared() {
148         return fShared;
149     }
150     
151     /**
152      * Sets whether or not the help system, in its current mode of operation,
153      * can be shared by multiple (potentially remote) users. This is a hint to
154      * the help system implementation that it should not perform operations that
155      * are specific to the help system's local environment.
156      * 
157      * <p>
158      * By default the help system is flagged as not shared. If you are providing 
159      * your own help implementation that is shared, you must call this on startup
160      * with the parameter <code>true</code>.
161      * </p>
162      * 
163      * @param shared whether or not the help system can be shared by multiple users
164      */
165     public static void setShared(boolean shared) {
166         fShared = shared;
167     }
168 }
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags