001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.help;
011:
012: import org.eclipse.help.IContext;
013: import org.eclipse.help.IHelp;
014: import org.eclipse.jface.action.IAction;
015: import org.eclipse.swt.events.HelpListener;
016: import org.eclipse.swt.widgets.Control;
017: import org.eclipse.swt.widgets.Menu;
018: import org.eclipse.swt.widgets.MenuItem;
019: import org.eclipse.ui.PlatformUI;
020: import org.eclipse.ui.commands.ICommand;
021: import org.eclipse.ui.internal.help.WorkbenchHelpSystem;
022:
023: /**
024: * Provides methods for accessing the help UI.
025: * <p>
026: * The help UI is optional, to allow applications to be configured
027: * without one.
028: * </p>
029: * <p>
030: * The various <code>setHelp</code> methods allow context help to be hooked in
031: * to SWT menus, menu items, and controls, and into JFace actions. This involves
032: * furnishing a help context id. When the user requests help for one of the
033: * established widgets (for instance, by hitting F1), the context id is
034: * retrieved and passed to the help UI using
035: * <code>WorkbenchHelp.displayContext(helpContext, xposition, yposition)</code>.
036: * </p>
037: * <p>
038: * In cases more dynamic situations, clients may hook their own help listener
039: * and call <code>WorkbenchHelp.displayContext</code> with an
040: * <code>IContext</code>.
041: * </p>
042: * <p>
043: * This class provides static methods only; it is not intended to be instantiated
044: * or subclassed.
045: * </p>
046: *
047: * @deprecated clients should use <code>IWorkbenchHelpSystem</code> instead
048: *
049: * @see org.eclipse.help.HelpSystem
050: * @see org.eclipse.ui.help.IWorkbenchHelpSystem
051: * @see org.eclipse.ui.IWorkbench#getHelpSystem()
052: */
053: public class WorkbenchHelp {
054:
055: /**
056: * This class is not intented to be instantiated
057: */
058: private WorkbenchHelp() {
059: }
060:
061: /**
062: * Displays the entire help bookshelf.
063: * <p>
064: * Ignored if no help UI is available.
065: * </p>
066: *
067: * @since 3.0
068: */
069: public static void displayHelp() {
070: PlatformUI.getWorkbench().getHelpSystem().displayHelp();
071: }
072:
073: /**
074: * Displays context-sensitive help for the given context.
075: * <p>
076: * (x,y) coordinates specify the location where the context sensitive
077: * help UI will be presented. These coordinates are screen-relative
078: * (ie: (0,0) is the top left-most screen corner).
079: * The platform is responsible for calling this method and supplying the
080: * appropriate location.
081: * </p>
082: * <p>
083: * Ignored if no help UI is available.
084: * </p>
085: *
086: * @param context the context to display
087: * @param x horizontal position
088: * @param y verifical position
089: * @since 3.0
090: */
091: public static void displayContext(IContext context, int x, int y) {
092: PlatformUI.getWorkbench().getHelpSystem().displayContext(
093: context, x, y);
094: }
095:
096: /**
097: * Displays help content for the help resource with the given URL.
098: * <p>
099: * This method is called by the platform to launch the help system UI, displaying
100: * the documentation identified by the <code>href</code> parameter.
101: * </p>
102: * <p>
103: * The help system makes no guarantee that all the help resources can be displayed or how they are displayed.
104: * </p>
105: * <p>
106: * Ignored if no help UI is available.
107: * </p>
108: *
109: * @param href the URL of the help resource.
110: * <p>Valid href are as described in
111: * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
112: * </p>
113: * @since 3.0
114: */
115: public static void displayHelpResource(String href) {
116: PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(
117: href);
118: }
119:
120: /**
121: * Creates a new help listener for the given command. This retrieves the
122: * help context ID from the command, and creates an appropriate listener
123: * based on this.
124: *
125: * @param command
126: * The command for which the listener should be created; must
127: * not be <code>null</code>.
128: * @return A help listener; never <code>null</code>.
129: */
130: public static HelpListener createHelpListener(ICommand command) {
131: return WorkbenchHelpSystem.getInstance().createHelpListener(
132: command);
133: }
134:
135: /**
136: * Calls the help support system to display the given help context id.
137: * <p>
138: * May only be called from a UI thread.
139: * <p>
140: *
141: * @param contextId the id of the context to display
142: * @since 2.0
143: */
144: public static void displayHelp(String contextId) {
145: PlatformUI.getWorkbench().getHelpSystem()
146: .displayHelp(contextId);
147: }
148:
149: /**
150: * Displays context-sensitive help for the given context.
151: * <p>
152: * May only be called from a UI thread.
153: * <p>
154: *
155: * @param context the context to display
156: * @since 2.0
157: */
158: public static void displayHelp(IContext context) {
159: PlatformUI.getWorkbench().getHelpSystem().displayHelp(context);
160: }
161:
162: /**
163: * Returns the help contexts on the given control.
164: * <p>
165: * Instances of <code>IContextComputer</code> may use this method
166: * to obtain the previously registered help contexts of a control.
167: * </p>
168: *
169: * @param control the control on which the contexts are registered
170: * @return contexts the contexts to use when F1 help is invoked; a mixed-type
171: * array of context ids (type <code>String</code>) and/or help contexts (type
172: * <code>IContext</code>) or an <code>IContextComputer</code> or
173: * <code>null</code> if no contexts have been set.
174: * @deprecated as context computers are no longer supported
175: */
176: public static Object getHelp(Control control) {
177: return control.getData(WorkbenchHelpSystem.HELP_KEY);
178: }
179:
180: /**
181: * Returns the help contexts on the given menu.
182: * <p>
183: * Instances of <code>IContextComputer</code> may use this method
184: * to obtain the previously registered help contexts of a menu.
185: * </p>
186: *
187: * @param menu the menu on which the contexts are registered
188: * @return contexts the contexts to use when F1 help is invoked; a mixed-type
189: * array of context ids (type <code>String</code>) and/or help contexts (type
190: * <code>IContext</code>) or an <code>IContextComputer</code> or
191: * <code>null</code> if no contexts have been set.
192: * @deprecated as context computers are no longer supported
193: */
194: public static Object getHelp(Menu menu) {
195: return menu.getData(WorkbenchHelpSystem.HELP_KEY);
196: }
197:
198: /**
199: * Returns the help contexts on the given menu item.
200: * <p>
201: * Instances of <code>IContextComputer</code> may use this method
202: * to obtain the previously registered help contexts of a menu.
203: * </p>
204: *
205: * @param menuItem the menu item on which the contexts are registered
206: * @return contexts the contexts to use when F1 help is invoked; a mixed-type
207: * array of context ids (type <code>String</code>) and/or help contexts (type
208: * <code>IContext</code>) or an <code>IContextComputer</code> or
209: * <code>null</code> if no contexts have been set.
210: * @deprecated as context computers are no longer supported
211: */
212: public static Object getHelp(MenuItem menuItem) {
213: return menuItem.getData(WorkbenchHelpSystem.HELP_KEY);
214: }
215:
216: /**
217: * Returns the help support system for the platform, if available.
218: *
219: * @return the help support system, or <code>null</code> if none
220: * @deprecated Use the static methods on this class and on
221: * {@link org.eclipse.help.HelpSystem HelpSystem} instead of the IHelp methods
222: * on the object returned by this method.
223: */
224: public static IHelp getHelpSupport() {
225: return WorkbenchHelpSystem.getInstance().getHelpSupport();
226: }
227:
228: /**
229: * Returns whether the context-sensitive help window is currently being
230: * displayed. Returns <code>false</code> if the help UI has not been
231: * activated yet.
232: *
233: * @return <code>true</code> if the context-sensitive help
234: * window is currently being displayed, <code>false</code> otherwise
235: */
236: public static boolean isContextHelpDisplayed() {
237: return PlatformUI.getWorkbench().getHelpSystem()
238: .isContextHelpDisplayed();
239: }
240:
241: /**
242: * Sets the given help contexts on the given action.
243: * <p>
244: * Use this method when the list of help contexts is known in advance.
245: * Help contexts can either supplied as a static list, or calculated with a
246: * context computer (but not both).
247: * </p>
248: *
249: * @param action the action on which to register the computer
250: * @param contexts the contexts to use when F1 help is invoked; a mixed-type
251: * array of context ids (type <code>String</code>) and/or help contexts (type
252: * <code>IContext</code>)
253: * @deprecated use setHelp with a single context id parameter
254: */
255: public static void setHelp(IAction action, final Object[] contexts) {
256: WorkbenchHelpSystem.getInstance().setHelp(action, contexts);
257: }
258:
259: /**
260: * Sets the given help context computer on the given action.
261: * <p>
262: * Use this method when the help contexts cannot be computed in advance.
263: * Help contexts can either supplied as a static list, or calculated with a
264: * context computer (but not both).
265: * </p>
266: *
267: * @param action the action on which to register the computer
268: * @param computer the computer to determine the help contexts for the control
269: * when F1 help is invoked
270: * @deprecated context computers are no longer supported, clients should implement
271: * their own help listener
272: */
273: public static void setHelp(IAction action,
274: final IContextComputer computer) {
275: WorkbenchHelpSystem.getInstance().setHelp(action, computer);
276: }
277:
278: /**
279: * Sets the given help contexts on the given control.
280: * <p>
281: * Use this method when the list of help contexts is known in advance.
282: * Help contexts can either supplied as a static list, or calculated with a
283: * context computer (but not both).
284: * </p>
285: *
286: * @param control the control on which to register the contexts
287: * @param contexts the contexts to use when F1 help is invoked; a mixed-type
288: * array of context ids (type <code>String</code>) and/or help contexts (type
289: * <code>IContext</code>)
290: * @deprecated use setHelp with single context id parameter
291: */
292: public static void setHelp(Control control, Object[] contexts) {
293: WorkbenchHelpSystem.getInstance().setHelp(control, contexts);
294: }
295:
296: /**
297: * Sets the given help context computer on the given control.
298: * <p>
299: * Use this method when the help contexts cannot be computed in advance.
300: * Help contexts can either supplied as a static list, or calculated with a
301: * context computer (but not both).
302: * </p>
303: *
304: * @param control the control on which to register the computer
305: * @param computer the computer to determine the help contexts for the control
306: * when F1 help is invoked
307: * @deprecated context computers are no longer supported, clients should implement
308: * their own help listener
309: */
310: public static void setHelp(Control control,
311: IContextComputer computer) {
312: WorkbenchHelpSystem.getInstance().setHelp(control, computer);
313: }
314:
315: /**
316: * Sets the given help contexts on the given menu.
317: * <p>
318: * Use this method when the list of help contexts is known in advance.
319: * Help contexts can either supplied as a static list, or calculated with a
320: * context computer (but not both).
321: * </p>
322: *
323: * @param menu the menu on which to register the context
324: * @param contexts the contexts to use when F1 help is invoked; a mixed-type
325: * array of context ids (type <code>String</code>) and/or help contexts (type
326: * <code>IContext</code>)
327: * @deprecated use setHelp with single context id parameter
328: */
329: public static void setHelp(Menu menu, Object[] contexts) {
330: WorkbenchHelpSystem.getInstance().setHelp(menu, contexts);
331: }
332:
333: /**
334: * Sets the given help context computer on the given menu.
335: * <p>
336: * Use this method when the help contexts cannot be computed in advance.
337: * Help contexts can either supplied as a static list, or calculated with a
338: * context computer (but not both).
339: * </p>
340: *
341: * @param menu the menu on which to register the computer
342: * @param computer the computer to determine the help contexts for the control
343: * when F1 help is invoked
344: * @deprecated context computers are no longer supported, clients should implement
345: * their own help listener
346: */
347: public static void setHelp(Menu menu, IContextComputer computer) {
348: WorkbenchHelpSystem.getInstance().setHelp(menu, computer);
349: }
350:
351: /**
352: * Sets the given help contexts on the given menu item.
353: * <p>
354: * Use this method when the list of help contexts is known in advance.
355: * Help contexts can either supplied as a static list, or calculated with a
356: * context computer (but not both).
357: * </p>
358: *
359: * @param item the menu item on which to register the context
360: * @param contexts the contexts to use when F1 help is invoked; a mixed-type
361: * array of context ids (type <code>String</code>) and/or help contexts (type
362: * <code>IContext</code>)
363: * @deprecated use setHelp with single context id parameter
364: */
365: public static void setHelp(MenuItem item, Object[] contexts) {
366: WorkbenchHelpSystem.getInstance().setHelp(item, contexts);
367: }
368:
369: /**
370: * Sets the given help context computer on the given menu item.
371: * <p>
372: * Use this method when the help contexts cannot be computed in advance.
373: * Help contexts can either supplied as a static list, or calculated with a
374: * context computer (but not both).
375: * </p>
376: *
377: * @param item the menu item on which to register the computer
378: * @param computer the computer to determine the help contexts for the control
379: * when F1 help is invoked
380: * @deprecated context computers are no longer supported, clients should implement
381: * their own help listener
382: */
383: public static void setHelp(MenuItem item, IContextComputer computer) {
384: WorkbenchHelpSystem.getInstance().setHelp(item, computer);
385: }
386:
387: /**
388: * Sets the given help context id on the given action.
389: *
390: * @param action the action on which to register the context id
391: * @param contextId the context id to use when F1 help is invoked
392: * @since 2.0
393: */
394: public static void setHelp(IAction action, final String contextId) {
395: PlatformUI.getWorkbench().getHelpSystem().setHelp(action,
396: contextId);
397: }
398:
399: /**
400: * Sets the given help context id on the given control.
401: *
402: * @param control the control on which to register the context id
403: * @param contextId the context id to use when F1 help is invoked
404: * @since 2.0
405: */
406: public static void setHelp(Control control, String contextId) {
407: PlatformUI.getWorkbench().getHelpSystem().setHelp(control,
408: contextId);
409: }
410:
411: /**
412: * Sets the given help context id on the given menu.
413: *
414: * @param menu the menu on which to register the context id
415: * @param contextId the context id to use when F1 help is invoked
416: * @since 2.0
417: */
418: public static void setHelp(Menu menu, String contextId) {
419: PlatformUI.getWorkbench().getHelpSystem().setHelp(menu,
420: contextId);
421: }
422:
423: /**
424: * Sets the given help context id on the given menu item.
425: *
426: * @param item the menu item on which to register the context id
427: * @param contextId the context id to use when F1 help is invoked
428: * @since 2.0
429: */
430: public static void setHelp(MenuItem item, String contextId) {
431: PlatformUI.getWorkbench().getHelpSystem().setHelp(item,
432: contextId);
433: }
434: }
|