| /******************************************************************************* |
| * Copyright (c) 2000, 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.ui.help; |
| |
| import org.eclipse.help.IContext; |
| import org.eclipse.help.IHelp; |
| import org.eclipse.jface.action.IAction; |
| import org.eclipse.swt.events.HelpListener; |
| import org.eclipse.swt.widgets.Control; |
| import org.eclipse.swt.widgets.Menu; |
| import org.eclipse.swt.widgets.MenuItem; |
| import org.eclipse.ui.PlatformUI; |
| import org.eclipse.ui.commands.ICommand; |
| import org.eclipse.ui.internal.help.WorkbenchHelpSystem; |
| |
| /** |
| * Provides methods for accessing the help UI. |
| * <p> |
| * The help UI is optional, to allow applications to be configured |
| * without one. |
| * </p> |
| * <p> |
| * The various <code>setHelp</code> methods allow context help to be hooked in |
| * to SWT menus, menu items, and controls, and into JFace actions. This involves |
| * furnishing a help context id. When the user requests help for one of the |
| * established widgets (for instance, by hitting F1), the context id is |
| * retrieved and passed to the help UI using |
| * <code>WorkbenchHelp.displayContext(helpContext, xposition, yposition)</code>. |
| * </p> |
| * <p> |
| * In cases more dynamic situations, clients may hook their own help listener |
| * and call <code>WorkbenchHelp.displayContext</code> with an |
| * <code>IContext</code>. |
| * </p> |
| * <p> |
| * This class provides static methods only; it is not intended to be instantiated |
| * or subclassed. |
| * </p> |
| * |
| * @deprecated clients should use <code>IWorkbenchHelpSystem</code> instead |
| * |
| * @see org.eclipse.help.HelpSystem |
| * @see org.eclipse.ui.help.IWorkbenchHelpSystem |
| * @see org.eclipse.ui.IWorkbench#getHelpSystem() |
| */ |
| public class WorkbenchHelp { |
| |
| /** |
| * This class is not intented to be instantiated |
| */ |
| private WorkbenchHelp() { |
| } |
| |
| /** |
| * Displays the entire help bookshelf. |
| * <p> |
| * Ignored if no help UI is available. |
| * </p> |
| * |
| * @since 3.0 |
| */ |
| public static void displayHelp() { |
| PlatformUI.getWorkbench().getHelpSystem().displayHelp(); |
| } |
| |
| /** |
| * Displays context-sensitive help for the given context. |
| * <p> |
| * (x,y) coordinates specify the location where the context sensitive |
| * help UI will be presented. These coordinates are screen-relative |
| * (ie: (0,0) is the top left-most screen corner). |
| * The platform is responsible for calling this method and supplying the |
| * appropriate location. |
| * </p> |
| * <p> |
| * Ignored if no help UI is available. |
| * </p> |
| * |
| * @param context the context to display |
| * @param x horizontal position |
| * @param y verifical position |
| * @since 3.0 |
| */ |
| public static void displayContext(IContext context, int x, int y) { |
| PlatformUI.getWorkbench().getHelpSystem().displayContext(context, x, y); |
| } |
| |
| /** |
| * Displays help content for the help resource with the given URL. |
| * <p> |
| * This method is called by the platform to launch the help system UI, displaying |
| * the documentation identified by the <code>href</code> parameter. |
| * </p> |
| * <p> |
| * The help system makes no guarantee that all the help resources can be displayed or how they are displayed. |
| * </p> |
| * <p> |
| * Ignored if no help UI is available. |
| * </p> |
| * |
| * @param href the URL of the help resource. |
| * <p>Valid href are as described in |
| * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()} |
| * </p> |
| * @since 3.0 |
| */ |
| public static void displayHelpResource(String href) { |
| PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(href); |
| } |
| |
| /** |
| * Creates a new help listener for the given command. This retrieves the |
| * help context ID from the command, and creates an appropriate listener |
| * based on this. |
| * |
| * @param command |
| * The command for which the listener should be created; must |
| * not be <code>null</code>. |
| * @return A help listener; never <code>null</code>. |
| */ |
| public static HelpListener createHelpListener(ICommand command) { |
| return WorkbenchHelpSystem.getInstance().createHelpListener(command); |
| } |
| |
| /** |
| * Calls the help support system to display the given help context id. |
| * <p> |
| * May only be called from a UI thread. |
| * <p> |
| * |
| * @param contextId the id of the context to display |
| * @since 2.0 |
| */ |
| public static void displayHelp(String contextId) { |
| PlatformUI.getWorkbench().getHelpSystem().displayHelp(contextId); |
| } |
| |
| /** |
| * Displays context-sensitive help for the given context. |
| * <p> |
| * May only be called from a UI thread. |
| * <p> |
| * |
| * @param context the context to display |
| * @since 2.0 |
| */ |
| public static void displayHelp(IContext context) { |
| PlatformUI.getWorkbench().getHelpSystem().displayHelp(context); |
| } |
| |
| /** |
| * Returns the help contexts on the given control. |
| * <p> |
| * Instances of <code>IContextComputer</code> may use this method |
| * to obtain the previously registered help contexts of a control. |
| * </p> |
| * |
| * @param control the control on which the contexts are registered |
| * @return contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) or an <code>IContextComputer</code> or |
| * <code>null</code> if no contexts have been set. |
| * @deprecated as context computers are no longer supported |
| */ |
| public static Object getHelp(Control control) { |
| return control.getData(WorkbenchHelpSystem.HELP_KEY); |
| } |
| |
| /** |
| * Returns the help contexts on the given menu. |
| * <p> |
| * Instances of <code>IContextComputer</code> may use this method |
| * to obtain the previously registered help contexts of a menu. |
| * </p> |
| * |
| * @param menu the menu on which the contexts are registered |
| * @return contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) or an <code>IContextComputer</code> or |
| * <code>null</code> if no contexts have been set. |
| * @deprecated as context computers are no longer supported |
| */ |
| public static Object getHelp(Menu menu) { |
| return menu.getData(WorkbenchHelpSystem.HELP_KEY); |
| } |
| |
| /** |
| * Returns the help contexts on the given menu item. |
| * <p> |
| * Instances of <code>IContextComputer</code> may use this method |
| * to obtain the previously registered help contexts of a menu. |
| * </p> |
| * |
| * @param menuItem the menu item on which the contexts are registered |
| * @return contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) or an <code>IContextComputer</code> or |
| * <code>null</code> if no contexts have been set. |
| * @deprecated as context computers are no longer supported |
| */ |
| public static Object getHelp(MenuItem menuItem) { |
| return menuItem.getData(WorkbenchHelpSystem.HELP_KEY); |
| } |
| |
| /** |
| * Returns the help support system for the platform, if available. |
| * |
| * @return the help support system, or <code>null</code> if none |
| * @deprecated Use the static methods on this class and on |
| * {@link org.eclipse.help.HelpSystem HelpSystem} instead of the IHelp methods |
| * on the object returned by this method. |
| */ |
| public static IHelp getHelpSupport() { |
| return WorkbenchHelpSystem.getInstance().getHelpSupport(); |
| } |
| |
| |
| /** |
| * Returns whether the context-sensitive help window is currently being |
| * displayed. Returns <code>false</code> if the help UI has not been |
| * activated yet. |
| * |
| * @return <code>true</code> if the context-sensitive help |
| * window is currently being displayed, <code>false</code> otherwise |
| */ |
| public static boolean isContextHelpDisplayed() { |
| return PlatformUI.getWorkbench().getHelpSystem().isContextHelpDisplayed(); |
| } |
| |
| /** |
| * Sets the given help contexts on the given action. |
| * <p> |
| * Use this method when the list of help contexts is known in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param action the action on which to register the computer |
| * @param contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) |
| * @deprecated use setHelp with a single context id parameter |
| */ |
| public static void setHelp(IAction action, final Object[] contexts) { |
| WorkbenchHelpSystem.getInstance().setHelp(action, contexts); |
| } |
| |
| /** |
| * Sets the given help context computer on the given action. |
| * <p> |
| * Use this method when the help contexts cannot be computed in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param action the action on which to register the computer |
| * @param computer the computer to determine the help contexts for the control |
| * when F1 help is invoked |
| * @deprecated context computers are no longer supported, clients should implement |
| * their own help listener |
| */ |
| public static void setHelp(IAction action, final IContextComputer computer) { |
| WorkbenchHelpSystem.getInstance().setHelp(action, computer); |
| } |
| |
| /** |
| * Sets the given help contexts on the given control. |
| * <p> |
| * Use this method when the list of help contexts is known in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param control the control on which to register the contexts |
| * @param contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) |
| * @deprecated use setHelp with single context id parameter |
| */ |
| public static void setHelp(Control control, Object[] contexts) { |
| WorkbenchHelpSystem.getInstance().setHelp(control, contexts); |
| } |
| |
| /** |
| * Sets the given help context computer on the given control. |
| * <p> |
| * Use this method when the help contexts cannot be computed in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param control the control on which to register the computer |
| * @param computer the computer to determine the help contexts for the control |
| * when F1 help is invoked |
| * @deprecated context computers are no longer supported, clients should implement |
| * their own help listener |
| */ |
| public static void setHelp(Control control, IContextComputer computer) { |
| WorkbenchHelpSystem.getInstance().setHelp(control, computer); |
| } |
| |
| /** |
| * Sets the given help contexts on the given menu. |
| * <p> |
| * Use this method when the list of help contexts is known in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param menu the menu on which to register the context |
| * @param contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) |
| * @deprecated use setHelp with single context id parameter |
| */ |
| public static void setHelp(Menu menu, Object[] contexts) { |
| WorkbenchHelpSystem.getInstance().setHelp(menu, contexts); |
| } |
| |
| /** |
| * Sets the given help context computer on the given menu. |
| * <p> |
| * Use this method when the help contexts cannot be computed in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param menu the menu on which to register the computer |
| * @param computer the computer to determine the help contexts for the control |
| * when F1 help is invoked |
| * @deprecated context computers are no longer supported, clients should implement |
| * their own help listener |
| */ |
| public static void setHelp(Menu menu, IContextComputer computer) { |
| WorkbenchHelpSystem.getInstance().setHelp(menu, computer); |
| } |
| |
| /** |
| * Sets the given help contexts on the given menu item. |
| * <p> |
| * Use this method when the list of help contexts is known in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param item the menu item on which to register the context |
| * @param contexts the contexts to use when F1 help is invoked; a mixed-type |
| * array of context ids (type <code>String</code>) and/or help contexts (type |
| * <code>IContext</code>) |
| * @deprecated use setHelp with single context id parameter |
| */ |
| public static void setHelp(MenuItem item, Object[] contexts) { |
| WorkbenchHelpSystem.getInstance().setHelp(item, contexts); |
| } |
| |
| /** |
| * Sets the given help context computer on the given menu item. |
| * <p> |
| * Use this method when the help contexts cannot be computed in advance. |
| * Help contexts can either supplied as a static list, or calculated with a |
| * context computer (but not both). |
| * </p> |
| * |
| * @param item the menu item on which to register the computer |
| * @param computer the computer to determine the help contexts for the control |
| * when F1 help is invoked |
| * @deprecated context computers are no longer supported, clients should implement |
| * their own help listener |
| */ |
| public static void setHelp(MenuItem item, IContextComputer computer) { |
| WorkbenchHelpSystem.getInstance().setHelp(item, computer); |
| } |
| |
| /** |
| * Sets the given help context id on the given action. |
| * |
| * @param action the action on which to register the context id |
| * @param contextId the context id to use when F1 help is invoked |
| * @since 2.0 |
| */ |
| public static void setHelp(IAction action, final String contextId) { |
| PlatformUI.getWorkbench().getHelpSystem().setHelp(action, contextId); |
| } |
| |
| /** |
| * Sets the given help context id on the given control. |
| * |
| * @param control the control on which to register the context id |
| * @param contextId the context id to use when F1 help is invoked |
| * @since 2.0 |
| */ |
| public static void setHelp(Control control, String contextId) { |
| PlatformUI.getWorkbench().getHelpSystem().setHelp(control, contextId); |
| } |
| |
| /** |
| * Sets the given help context id on the given menu. |
| * |
| * @param menu the menu on which to register the context id |
| * @param contextId the context id to use when F1 help is invoked |
| * @since 2.0 |
| */ |
| public static void setHelp(Menu menu, String contextId) { |
| PlatformUI.getWorkbench().getHelpSystem().setHelp(menu, contextId); |
| } |
| |
| /** |
| * Sets the given help context id on the given menu item. |
| * |
| * @param item the menu item on which to register the context id |
| * @param contextId the context id to use when F1 help is invoked |
| * @since 2.0 |
| */ |
| public static void setHelp(MenuItem item, String contextId) { |
| PlatformUI.getWorkbench().getHelpSystem().setHelp(item, contextId); |
| } |
| } |
