KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > help > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc resolve(String JavaDoc href, boolean documentOnly);
210 }
Popular Tags