IWorkbenchHelpSystem


1   /*******************************************************************************
2    * Copyright (c) 2005 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.ui.help;
12  
13  import java.net.URL  ;
14  
15  import org.eclipse.help.IContext;
16  import org.eclipse.jface.action.IAction;
17  import org.eclipse.swt.widgets.Control;
18  import org.eclipse.swt.widgets.Menu;
19  import org.eclipse.swt.widgets.MenuItem;
20  
21  /**
22   * <p>
23   * The interface that is used to access the workbench help system. Replaces
24   * static methods on <code>WorkbenchHelp</code>.
25   * </p>
26   * <p>
27   * This interface is not intended to be implemented by clients.
28   * </p>
29   * 
30   * @since 3.1
31   */
32  public interface IWorkbenchHelpSystem {
33  
34      /**
35       * Returns whether there is a UI help system installed.
36       * 
37       * @return whether there is a UI help system installed
38       */
39      boolean hasHelpUI();
40  
41      /**
42       * Displays the entire help bookshelf.
43       * <p>
44       * Ignored if no help UI is available.
45       * </p>
46       */
47      void displayHelp();
48  
49      /**
50       * Displays the help search system.
51       * <p>
52       * Ignored if no help UI is available.
53       * </p>
54       */
55      void displaySearch();
56  
57      /**
58       * Displays the dynamic help for the current UI context.
59       * <p>
60       * Ignored if no help UI is available.
61       * </p>
62       */
63      void displayDynamicHelp();
64  
65      /**
66       * Starts the search using the help search system.
67       * <p>
68       * Ignored if no help UI is available.
69       * </p>
70       * 
71       * @param expression
72       *            the search expression. The actual syntax rules of the
73       *            expression are dependent on the active
74       *            help system. Refer to the help system
75       *            documentation for more details.
76       */
77      void search(String   expression);
78  
79      /**
80       * Displays context-sensitive help for the given context.
81       * <p>
82       * (x,y) coordinates specify the location where the context sensitive help
83       * UI will be presented. These coordinates are screen-relative (ie: (0,0) is
84       * the top left-most screen corner). The platform is responsible for calling
85       * this method and supplying the appropriate location.
86       * </p>
87       * <p>
88       * Ignored if no help UI is available.
89       * </p>
90       * 
91       * @param context
92       *            the context to display
93       * @param x
94       *            horizontal position
95       * @param y
96       *            verifical position
97       */
98      void displayContext(IContext context, int x, int y);
99  
100     /**
101      * Displays help content for the help resource with the given URL.
102      * <p>
103      * This method is called by the platform to launch the help system UI,
104      * displaying the documentation identified by the <code>href</code>
105      * parameter.
106      * </p>
107      * <p>
108      * The help system makes no guarantee that all the help resources can be
109      * displayed or how they are displayed.
110      * </p>
111      * <p>
112      * Ignored if no help UI is available.
113      * </p>
114      * 
115      * @param href
116      *            the URL of the help resource.
117      *            <p>
118      *            Valid href are as described in
119      *            {@link  org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
120      *            </p>
121      */
122     void displayHelpResource(String   href);
123 
124     /**
125      * Calls the help support system to display the given help context id.
126      * <p>
127      * May only be called from a UI thread.
128      * <p>
129      * 
130      * @param contextId
131      *            the id of the context to display
132      */
133     void displayHelp(String   contextId);
134 
135     /**
136      * Displays context-sensitive help for the given context.
137      * <p>
138      * May only be called from a UI thread.
139      * <p>
140      * 
141      * @param context
142      *            the context to display
143      */
144     void displayHelp(IContext context);
145 
146     /**
147      * Returns whether the context-sensitive help window is currently being
148      * displayed. Returns <code>false</code> if the help UI has not been
149      * activated yet.
150      * 
151      * @return <code>true</code> if the context-sensitive help window is
152      *         currently being displayed, <code>false</code> otherwise
153      */
154     boolean isContextHelpDisplayed();
155 
156     /**
157      * Sets the given help context id on the given action.
158      * 
159      * @param action
160      *            the action on which to register the context id
161      * @param contextId
162      *            the context id to use when F1 help is invoked
163      */
164     void setHelp(IAction action, String   contextId);
165 
166     /**
167      * Sets the given help context id on the given control.
168      * 
169      * @param control
170      *            the control on which to register the context id
171      * @param contextId
172      *            the context id to use when F1 help is invoked
173      */
174     void setHelp(Control control, String   contextId);
175 
176     /**
177      * Sets the given help context id on the given menu.
178      * 
179      * @param menu
180      *            the menu on which to register the context id
181      * @param contextId
182      *            the context id to use when F1 help is invoked
183      */
184     void setHelp(Menu menu, String   contextId);
185 
186     /**
187      * Sets the given help context id on the given menu item.
188      * 
189      * @param item
190      *            the menu item on which to register the context id
191      * @param contextId
192      *            the context id to use when F1 help is invoked
193      */
194     void setHelp(MenuItem item, String   contextId);
195 
196     /**
197      * Resolves the help resource href by converting it into a legitimate URL
198      * according to the implementation of the help system. Help resources that
199      * already have a protocol will be unchanged.
200      * 
201      * @param href
202      * @param documentOnly if <code>true</code>, the resulting URL must point
203      * at the document referenced by href. Otherwise, it can be a URL that
204      * contains additional elements like navigation that the help system
205      * adds to the document.
206      * @return the resolved URL or <code>null</code> if no help UI is
207      *         available.
208      */
209     URL   resolve(String   href, boolean documentOnly);
210 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags