0001: /*******************************************************************************
0002: * Copyright (c) 2004, 2007 IBM Corporation and others.
0003: * All rights reserved. This program and the accompanying materials
0004: * are made available under the terms of the Eclipse Public License v1.0
0005: * which accompanies this distribution, and is available at
0006: * http://www.eclipse.org/legal/epl-v10.html
0007: *
0008: * Contributors:
0009: * IBM Corporation - initial API and implementation
0010: *******************************************************************************/package org.eclipse.ui.internal.help;
0011:
0012: import java.net.URL;
0013:
0014: import org.eclipse.core.runtime.Assert;
0015: import org.eclipse.core.runtime.CoreException;
0016: import org.eclipse.core.runtime.IConfigurationElement;
0017: import org.eclipse.core.runtime.IExtension;
0018: import org.eclipse.core.runtime.IExtensionPoint;
0019: import org.eclipse.core.runtime.Platform;
0020: import org.eclipse.core.runtime.dynamichelpers.IExtensionChangeHandler;
0021: import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
0022: import org.eclipse.help.HelpSystem;
0023: import org.eclipse.help.IContext;
0024: import org.eclipse.help.IContext2;
0025: import org.eclipse.help.IHelp;
0026: import org.eclipse.help.IHelpResource;
0027: import org.eclipse.help.IToc;
0028: import org.eclipse.jface.action.IAction;
0029: import org.eclipse.swt.custom.BusyIndicator;
0030: import org.eclipse.swt.events.HelpEvent;
0031: import org.eclipse.swt.events.HelpListener;
0032: import org.eclipse.swt.graphics.Point;
0033: import org.eclipse.swt.widgets.Control;
0034: import org.eclipse.swt.widgets.Display;
0035: import org.eclipse.swt.widgets.Menu;
0036: import org.eclipse.swt.widgets.MenuItem;
0037: import org.eclipse.ui.PlatformUI;
0038: import org.eclipse.ui.commands.ICommand;
0039: import org.eclipse.ui.help.AbstractHelpUI;
0040: import org.eclipse.ui.help.IContextComputer;
0041: import org.eclipse.ui.help.IWorkbenchHelpSystem;
0042: import org.eclipse.ui.internal.IWorkbenchHelpContextIds;
0043: import org.eclipse.ui.internal.WorkbenchPlugin;
0044: import org.eclipse.ui.internal.registry.IWorkbenchRegistryConstants;
0045:
0046: /**
0047: * This class represents a refactoring of the functionality previously contained
0048: * in <code>WorkbenchHelp</code>.
0049: *
0050: * @since 3.1
0051: */
0052: public final class WorkbenchHelpSystem implements IWorkbenchHelpSystem {
0053:
0054: /**
0055: * Key used for stashing help-related data on SWT widgets.
0056: *
0057: * @see org.eclipse.swt.widgets.Widget#getData(java.lang.String)
0058: */
0059: public static final String HELP_KEY = "org.eclipse.ui.help";//$NON-NLS-1$
0060:
0061: /**
0062: * Id of extension point where the help UI is contributed.
0063: */
0064: private static final String HELP_SYSTEM_EXTENSION_ID = PlatformUI.PLUGIN_ID
0065: + '.' + IWorkbenchRegistryConstants.PL_HELPSUPPORT;
0066:
0067: /**
0068: * Attribute id for class attribute of help UI extension point.
0069: */
0070: private static final String HELP_SYSTEM_CLASS_ATTRIBUTE = "class";//$NON-NLS-1$
0071:
0072: /**
0073: * Singleton.
0074: */
0075: private static WorkbenchHelpSystem instance;
0076:
0077: /**
0078: * The help listener.
0079: */
0080: private static class WorkbenchHelpListener implements HelpListener {
0081: public void helpRequested(HelpEvent event) {
0082:
0083: if (getInstance().getHelpUI() == null) {
0084: return;
0085: }
0086:
0087: // get the help context from the widget
0088: Object object = event.widget.getData(HELP_KEY);
0089:
0090: // Since 2.0 we can expect that object is a String, however
0091: // for backward compatability we handle context computers and
0092: // arrays.
0093: IContext context = null;
0094: if (object instanceof String) {
0095: // context id - this is the norm
0096: context = HelpSystem.getContext((String) object);
0097: } else if (object instanceof IContext) {
0098: // already resolved context (pre 2.0)
0099: context = (IContext) object;
0100: } else if (object instanceof IContextComputer) {
0101: // a computed context (pre 2.0) - compute it now
0102: Object[] helpContexts = ((IContextComputer) object)
0103: .computeContexts(event);
0104: // extract the first entry
0105: if (helpContexts != null && helpContexts.length > 0) {
0106: Object primaryEntry = helpContexts[0];
0107: if (primaryEntry instanceof String) {
0108: context = HelpSystem
0109: .getContext((String) primaryEntry);
0110: } else if (primaryEntry instanceof IContext) {
0111: context = (IContext) primaryEntry;
0112: }
0113: }
0114: } else if (object instanceof Object[]) {
0115: // mixed array of String or IContext (pre 2.0) - extract the
0116: // first entry
0117: Object[] helpContexts = (Object[]) object;
0118: // extract the first entry
0119: if (helpContexts.length > 0) {
0120: Object primaryEntry = helpContexts[0];
0121: if (primaryEntry instanceof String) {
0122: context = HelpSystem
0123: .getContext((String) primaryEntry);
0124: } else if (primaryEntry instanceof IContext) {
0125: context = (IContext) primaryEntry;
0126: }
0127: }
0128: }
0129:
0130: /*
0131: * If can't find it, show the "context is missing" context.
0132: */
0133: if (context == null) {
0134: context = HelpSystem
0135: .getContext(IWorkbenchHelpContextIds.MISSING);
0136: }
0137:
0138: if (context != null) {
0139: // determine a location in the upper right corner of the
0140: // widget
0141: Point point = computePopUpLocation(event.widget
0142: .getDisplay());
0143: // display the help
0144: getInstance().displayContext(context, point.x, point.y);
0145: }
0146: }
0147: }
0148:
0149: /**
0150: * Whether the help system has been initialized.
0151: */
0152: private boolean isInitialized;
0153:
0154: /**
0155: * Pluggable help UI, or <code>null</code> if none (or unknown).
0156: */
0157: private AbstractHelpUI pluggableHelpUI = null;
0158:
0159: /**
0160: * The id of the help extension that should be used. This is used only for
0161: * debugging purposes.
0162: */
0163: private String desiredHelpSystemId;
0164:
0165: /**
0166: * Handles dynamic removal of the help system.
0167: *
0168: * @since 3.1
0169: */
0170: /**
0171: * Handles dynamic removal of the help system.
0172: *
0173: * @since 3.1
0174: */
0175: private IExtensionChangeHandler handler = new IExtensionChangeHandler() {
0176:
0177: /* (non-Javadoc)
0178: * @see org.eclipse.core.runtime.dynamicHelpers.IExtensionChangeHandler#addExtension(org.eclipse.core.runtime.dynamicHelpers.IExtensionTracker, org.eclipse.core.runtime.IExtension)
0179: */
0180: public void addExtension(IExtensionTracker tracker,
0181: IExtension extension) {
0182: //Do nothing
0183: }
0184:
0185: /* (non-Javadoc)
0186: * @see org.eclipse.core.runtime.dynamicHelpers.IExtensionChangeHandler#removeExtension(org.eclipse.core.runtime.IExtension, java.lang.Object[])
0187: */
0188: public void removeExtension(IExtension source, Object[] objects) {
0189: for (int i = 0; i < objects.length; i++) {
0190: if (objects[i] == pluggableHelpUI) {
0191: isInitialized = false;
0192: pluggableHelpUI = null;
0193: helpCompatibilityWrapper = null;
0194: // remove ourselves - we'll be added again in initalize if
0195: // needed
0196: PlatformUI.getWorkbench().getExtensionTracker()
0197: .unregisterHandler(handler);
0198: }
0199: }
0200: }
0201: };
0202:
0203: /**
0204: * Compatibility implementation of old IHelp interface.
0205: * WorkbenchHelp.getHelpSupport and IHelp were deprecated in 3.0.
0206: */
0207: private class CompatibilityIHelpImplementation implements IHelp {
0208:
0209: /** @deprecated */
0210: public void displayHelp() {
0211: // real method - forward to help UI if available
0212: AbstractHelpUI helpUI = getHelpUI();
0213: if (helpUI != null) {
0214: helpUI.displayHelp();
0215: }
0216: }
0217:
0218: /** @deprecated */
0219: public void displayContext(IContext context, int x, int y) {
0220: // real method - forward to help UI if available
0221: AbstractHelpUI helpUI = getHelpUI();
0222: if (helpUI != null) {
0223: helpUI.displayContext(context, x, y);
0224: }
0225: }
0226:
0227: /** @deprecated */
0228: public void displayContext(String contextId, int x, int y) {
0229: // convenience method - funnel through the real method
0230: IContext context = HelpSystem.getContext(contextId);
0231: if (context != null) {
0232: displayContext(context, x, y);
0233: }
0234: }
0235:
0236: /** @deprecated */
0237: public void displayHelpResource(String href) {
0238: // real method - forward to help UI if available
0239: AbstractHelpUI helpUI = getHelpUI();
0240: if (helpUI != null) {
0241: helpUI.displayHelpResource(href);
0242: }
0243: }
0244:
0245: /** @deprecated */
0246: public void displayHelpResource(IHelpResource helpResource) {
0247: // convenience method - funnel through the real method
0248: displayHelpResource(helpResource.getHref());
0249: }
0250:
0251: /** @deprecated */
0252: public void displayHelp(String toc) {
0253: // deprecated method - funnel through the real method
0254: displayHelpResource(toc);
0255: }
0256:
0257: /** @deprecated */
0258: public void displayHelp(String toc, String selectedTopic) {
0259: // deprecated method - funnel through the real method
0260: displayHelpResource(selectedTopic);
0261: }
0262:
0263: /** @deprecated */
0264: public void displayHelp(String contextId, int x, int y) {
0265: // deprecated method - funnel through the real method
0266: displayContext(contextId, x, y);
0267: }
0268:
0269: /** @deprecated */
0270: public void displayHelp(IContext context, int x, int y) {
0271: // deprecated method - funnel through the real method
0272: displayContext(context, x, y);
0273: }
0274:
0275: /** @deprecated */
0276: public IContext getContext(String contextId) {
0277: // non-UI method - forward to HelpSystem
0278: return HelpSystem.getContext(contextId);
0279: }
0280:
0281: /** @deprecated */
0282: public IToc[] getTocs() {
0283: // non-UI method - forward to HelpSystem
0284: return HelpSystem.getTocs();
0285: }
0286:
0287: /** @deprecated */
0288: public boolean isContextHelpDisplayed() {
0289: // real method - forward to pluggedhelp UI
0290: return isContextHelpDisplayed();
0291: }
0292: }
0293:
0294: /**
0295: * A wrapper for action help context that passes the action
0296: * text to be used as a title.
0297: * @since 3.1
0298: */
0299: private static class ContextWithTitle implements IContext2 {
0300: private IContext context;
0301: private String title;
0302:
0303: ContextWithTitle(IContext context, String title) {
0304: this .context = context;
0305: this .title = title;
0306: }
0307:
0308: public String getTitle() {
0309: if (context instanceof IContext2) {
0310: String ctitle = ((IContext2) context).getTitle();
0311: if (ctitle != null) {
0312: return ctitle;
0313: }
0314: }
0315: return title;
0316: }
0317:
0318: public String getStyledText() {
0319: if (context instanceof IContext2) {
0320: return ((IContext2) context).getStyledText();
0321: }
0322: return context.getText();
0323: }
0324:
0325: public String getCategory(IHelpResource topic) {
0326: if (context instanceof IContext2) {
0327: return ((IContext2) context).getCategory(topic);
0328: }
0329: return null;
0330: }
0331:
0332: public IHelpResource[] getRelatedTopics() {
0333: return context.getRelatedTopics();
0334: }
0335:
0336: public String getText() {
0337: return context.getText();
0338: }
0339: }
0340:
0341: /**
0342: * Compatibility wrapper, or <code>null</code> if none. Do not access
0343: * directly; see getHelpSupport().
0344: */
0345: private IHelp helpCompatibilityWrapper = null;
0346:
0347: /**
0348: * The listener to attach to various widgets.
0349: */
0350: private static HelpListener helpListener;
0351:
0352: /**
0353: * For debug purposes only.
0354: *
0355: * @return the desired help system id
0356: */
0357: public String getDesiredHelpSystemId() {
0358: return desiredHelpSystemId;
0359: }
0360:
0361: /**
0362: * For debug purposes only.
0363: *
0364: * @param desiredHelpSystemId the desired help system id
0365: */
0366: public void setDesiredHelpSystemId(String desiredHelpSystemId) {
0367: dispose(); // prep for a new help system
0368: this .desiredHelpSystemId = desiredHelpSystemId;
0369: }
0370:
0371: /**
0372: * Singleton Constructor.
0373: */
0374: private WorkbenchHelpSystem() {
0375: }
0376:
0377: /**
0378: * Return the singleton instance of this class.
0379: *
0380: * @return the singleton instance
0381: */
0382: public static WorkbenchHelpSystem getInstance() {
0383: if (instance == null) {
0384: instance = new WorkbenchHelpSystem();
0385: }
0386:
0387: return instance;
0388: }
0389:
0390: /**
0391: * Disposed of the singleton of this class if it has been created.
0392: */
0393: public static void disposeIfNecessary() {
0394: if (instance != null) {
0395: instance.dispose();
0396: instance = null;
0397: }
0398: }
0399:
0400: /**
0401: * Dispose of any resources allocated by this instance.
0402: */
0403: public void dispose() {
0404: pluggableHelpUI = null;
0405: helpCompatibilityWrapper = null;
0406: isInitialized = false;
0407: PlatformUI.getWorkbench().getExtensionTracker()
0408: .unregisterHandler(handler);
0409: }
0410:
0411: /**
0412: * Returns the help UI for the platform, if available. This method will
0413: * initialize the help UI if necessary.
0414: *
0415: * @return the help UI, or <code>null</code> if none
0416: */
0417: private AbstractHelpUI getHelpUI() {
0418: if (!isInitialized) {
0419: isInitialized = initializePluggableHelpUI();
0420: }
0421: return pluggableHelpUI;
0422: }
0423:
0424: /**
0425: * Initializes the pluggable help UI by getting an instance via the
0426: * extension point.
0427: */
0428: private boolean initializePluggableHelpUI() {
0429: final boolean[] ret = new boolean[] { false };
0430:
0431: BusyIndicator.showWhile(Display.getCurrent(), new Runnable() {
0432:
0433: /*
0434: * (non-Javadoc)
0435: *
0436: * @see java.lang.Runnable#run()
0437: */
0438: public void run() {
0439: // get the help UI extension from the registry
0440: IExtensionPoint point = Platform.getExtensionRegistry()
0441: .getExtensionPoint(HELP_SYSTEM_EXTENSION_ID);
0442: if (point == null) {
0443: // our extension point is missing (!) - act like there was
0444: // no help UI
0445: return;
0446: }
0447: IExtension[] extensions = point.getExtensions();
0448: if (extensions.length == 0) {
0449: // no help UI present
0450: return;
0451: }
0452:
0453: IConfigurationElement elementToUse = null;
0454: if (desiredHelpSystemId == null) {
0455: elementToUse = getFirstElement(extensions);
0456: } else {
0457: elementToUse = findElement(desiredHelpSystemId,
0458: extensions);
0459: }
0460:
0461: if (elementToUse != null) {
0462: ret[0] = initializePluggableHelpUI(elementToUse);
0463: }
0464: }
0465:
0466: private IConfigurationElement findElement(
0467: String desiredHelpSystemId, IExtension[] extensions) {
0468: for (int i = 0; i < extensions.length; i++) {
0469: IExtension extension = extensions[i];
0470: if (desiredHelpSystemId.equals(extension
0471: .getUniqueIdentifier())) {
0472: IConfigurationElement[] elements = extensions[0]
0473: .getConfigurationElements();
0474: if (elements.length == 0) {
0475: // help UI present but mangled - act like there was
0476: // no help
0477: // UI
0478: return null;
0479: }
0480: return elements[0];
0481: }
0482:
0483: }
0484: return null;
0485: }
0486:
0487: private IConfigurationElement getFirstElement(
0488: IExtension[] extensions) {
0489: // There should only be one extension/config element so we just
0490: // take the first
0491: IConfigurationElement[] elements = extensions[0]
0492: .getConfigurationElements();
0493: if (elements.length == 0) {
0494: // help UI present but mangled - act like there was no help
0495: // UI
0496: return null;
0497: }
0498: return elements[0];
0499: }
0500:
0501: private boolean initializePluggableHelpUI(
0502: IConfigurationElement element) {
0503: // Instantiate the help UI
0504: try {
0505: pluggableHelpUI = (AbstractHelpUI) WorkbenchPlugin
0506: .createExtension(element,
0507: HELP_SYSTEM_CLASS_ATTRIBUTE);
0508: // start listening for removals
0509: PlatformUI.getWorkbench().getExtensionTracker()
0510: .registerHandler(handler, null);
0511: // register the new help UI for removal notification
0512: PlatformUI.getWorkbench().getExtensionTracker()
0513: .registerObject(
0514: element.getDeclaringExtension(),
0515: pluggableHelpUI,
0516: IExtensionTracker.REF_WEAK);
0517: return true;
0518: } catch (CoreException e) {
0519: WorkbenchPlugin
0520: .log(
0521: "Unable to instantiate help UI" + e.getStatus(), e);//$NON-NLS-1$
0522: }
0523: return false;
0524: }
0525:
0526: });
0527: return ret[0];
0528: }
0529:
0530: /**
0531: * Determines the location for the help popup shell given the widget which
0532: * orginated the request for help.
0533: *
0534: * @param display
0535: * the display where the help will appear
0536: */
0537: private static Point computePopUpLocation(Display display) {
0538: Point point = display.getCursorLocation();
0539: return new Point(point.x + 15, point.y);
0540: }
0541:
0542: /**
0543: * Returns the help listener which activates the help support system.
0544: *
0545: * @return the help listener
0546: */
0547: private HelpListener getHelpListener() {
0548: if (helpListener == null) {
0549: helpListener = new WorkbenchHelpListener();
0550: }
0551: return helpListener;
0552: }
0553:
0554: /**
0555: * Returns the help support system for the platform, if available.
0556: *
0557: * @return the help support system, or <code>null</code> if none
0558: * @deprecated Use the static methods on this class and on
0559: * {@link org.eclipse.help.HelpSystem HelpSystem}instead of the
0560: * IHelp methods on the object returned by this method.
0561: */
0562: public IHelp getHelpSupport() {
0563: AbstractHelpUI helpUI = getHelpUI();
0564: if (helpUI != null && helpCompatibilityWrapper == null) {
0565: // create instance only once, and only if needed
0566: helpCompatibilityWrapper = new CompatibilityIHelpImplementation();
0567: }
0568: return helpCompatibilityWrapper;
0569:
0570: }
0571:
0572: /**
0573: * Sets the given help contexts on the given action.
0574: * <p>
0575: * Use this method when the list of help contexts is known in advance. Help
0576: * contexts can either supplied as a static list, or calculated with a
0577: * context computer (but not both).
0578: * </p>
0579: *
0580: * @param action
0581: * the action on which to register the computer
0582: * @param contexts
0583: * the contexts to use when F1 help is invoked; a mixed-type
0584: * array of context ids (type <code>String</code>) and/or help
0585: * contexts (type <code>IContext</code>)
0586: * @deprecated use setHelp with a single context id parameter
0587: */
0588: public void setHelp(IAction action, final Object[] contexts) {
0589: for (int i = 0; i < contexts.length; i++) {
0590: Assert.isTrue(contexts[i] instanceof String
0591: || contexts[i] instanceof IContext);
0592: }
0593: action.setHelpListener(new HelpListener() {
0594: public void helpRequested(HelpEvent event) {
0595: if (contexts != null && contexts.length > 0
0596: && getHelpUI() != null) {
0597: // determine the context
0598: IContext context = null;
0599: if (contexts[0] instanceof String) {
0600: context = HelpSystem
0601: .getContext((String) contexts[0]);
0602: } else if (contexts[0] instanceof IContext) {
0603: context = (IContext) contexts[0];
0604: }
0605: if (context != null) {
0606: Point point = computePopUpLocation(event.widget
0607: .getDisplay());
0608: displayContext(context, point.x, point.y);
0609: }
0610: }
0611: }
0612: });
0613: }
0614:
0615: /**
0616: * Sets the given help context computer on the given action.
0617: * <p>
0618: * Use this method when the help contexts cannot be computed in advance.
0619: * Help contexts can either supplied as a static list, or calculated with a
0620: * context computer (but not both).
0621: * </p>
0622: *
0623: * @param action
0624: * the action on which to register the computer
0625: * @param computer
0626: * the computer to determine the help contexts for the control
0627: * when F1 help is invoked
0628: * @deprecated context computers are no longer supported, clients should
0629: * implement their own help listener
0630: */
0631: public void setHelp(IAction action, final IContextComputer computer) {
0632: action.setHelpListener(new HelpListener() {
0633: public void helpRequested(HelpEvent event) {
0634: Object[] helpContexts = computer.computeContexts(event);
0635: if (helpContexts != null && helpContexts.length > 0
0636: && getHelpUI() != null) {
0637: // determine the context
0638: IContext context = null;
0639: if (helpContexts[0] instanceof String) {
0640: context = HelpSystem
0641: .getContext((String) helpContexts[0]);
0642: } else if (helpContexts[0] instanceof IContext) {
0643: context = (IContext) helpContexts[0];
0644: }
0645: if (context != null) {
0646: Point point = computePopUpLocation(event.widget
0647: .getDisplay());
0648: displayContext(context, point.x, point.y);
0649: }
0650: }
0651: }
0652: });
0653: }
0654:
0655: /**
0656: * Sets the given help contexts on the given control.
0657: * <p>
0658: * Use this method when the list of help contexts is known in advance. Help
0659: * contexts can either supplied as a static list, or calculated with a
0660: * context computer (but not both).
0661: * </p>
0662: *
0663: * @param control
0664: * the control on which to register the contexts
0665: * @param contexts
0666: * the contexts to use when F1 help is invoked; a mixed-type
0667: * array of context ids (type <code>String</code>) and/or help
0668: * contexts (type <code>IContext</code>)
0669: * @deprecated use setHelp with single context id parameter
0670: */
0671: public void setHelp(Control control, Object[] contexts) {
0672: for (int i = 0; i < contexts.length; i++) {
0673: Assert.isTrue(contexts[i] instanceof String
0674: || contexts[i] instanceof IContext);
0675: }
0676:
0677: control.setData(HELP_KEY, contexts);
0678: // ensure that the listener is only registered once
0679: control.removeHelpListener(getHelpListener());
0680: control.addHelpListener(getHelpListener());
0681: }
0682:
0683: /**
0684: * Sets the given help context computer on the given control.
0685: * <p>
0686: * Use this method when the help contexts cannot be computed in advance.
0687: * Help contexts can either supplied as a static list, or calculated with a
0688: * context computer (but not both).
0689: * </p>
0690: *
0691: * @param control
0692: * the control on which to register the computer
0693: * @param computer
0694: * the computer to determine the help contexts for the control
0695: * when F1 help is invoked
0696: * @deprecated context computers are no longer supported, clients should
0697: * implement their own help listener
0698: */
0699: public void setHelp(Control control, IContextComputer computer) {
0700: control.setData(HELP_KEY, computer);
0701: // ensure that the listener is only registered once
0702: control.removeHelpListener(getHelpListener());
0703: control.addHelpListener(getHelpListener());
0704: }
0705:
0706: /**
0707: * Sets the given help contexts on the given menu.
0708: * <p>
0709: * Use this method when the list of help contexts is known in advance. Help
0710: * contexts can either supplied as a static list, or calculated with a
0711: * context computer (but not both).
0712: * </p>
0713: *
0714: * @param menu
0715: * the menu on which to register the context
0716: * @param contexts
0717: * the contexts to use when F1 help is invoked; a mixed-type
0718: * array of context ids (type <code>String</code>) and/or help
0719: * contexts (type <code>IContext</code>)
0720: * @deprecated use setHelp with single context id parameter
0721: */
0722: public void setHelp(Menu menu, Object[] contexts) {
0723: for (int i = 0; i < contexts.length; i++) {
0724: Assert.isTrue(contexts[i] instanceof String
0725: || contexts[i] instanceof IContext);
0726: }
0727: menu.setData(HELP_KEY, contexts);
0728: // ensure that the listener is only registered once
0729: menu.removeHelpListener(getHelpListener());
0730: menu.addHelpListener(getHelpListener());
0731: }
0732:
0733: /**
0734: * Sets the given help context computer on the given menu.
0735: * <p>
0736: * Use this method when the help contexts cannot be computed in advance.
0737: * Help contexts can either supplied as a static list, or calculated with a
0738: * context computer (but not both).
0739: * </p>
0740: *
0741: * @param menu
0742: * the menu on which to register the computer
0743: * @param computer
0744: * the computer to determine the help contexts for the control
0745: * when F1 help is invoked
0746: * @deprecated context computers are no longer supported, clients should
0747: * implement their own help listener
0748: */
0749: public void setHelp(Menu menu, IContextComputer computer) {
0750: menu.setData(HELP_KEY, computer);
0751: // ensure that the listener is only registered once
0752: menu.removeHelpListener(getHelpListener());
0753: menu.addHelpListener(getHelpListener());
0754: }
0755:
0756: /**
0757: * Sets the given help contexts on the given menu item.
0758: * <p>
0759: * Use this method when the list of help contexts is known in advance. Help
0760: * contexts can either supplied as a static list, or calculated with a
0761: * context computer (but not both).
0762: * </p>
0763: *
0764: * @param item
0765: * the menu item on which to register the context
0766: * @param contexts
0767: * the contexts to use when F1 help is invoked; a mixed-type
0768: * array of context ids (type <code>String</code>) and/or help
0769: * contexts (type <code>IContext</code>)
0770: * @deprecated use setHelp with single context id parameter
0771: */
0772: public void setHelp(MenuItem item, Object[] contexts) {
0773: for (int i = 0; i < contexts.length; i++) {
0774: Assert.isTrue(contexts[i] instanceof String
0775: || contexts[i] instanceof IContext);
0776: }
0777: item.setData(HELP_KEY, contexts);
0778: // ensure that the listener is only registered once
0779: item.removeHelpListener(getHelpListener());
0780: item.addHelpListener(getHelpListener());
0781: }
0782:
0783: /**
0784: * Sets the given help context computer on the given menu item.
0785: * <p>
0786: * Use this method when the help contexts cannot be computed in advance.
0787: * Help contexts can either supplied as a static list, or calculated with a
0788: * context computer (but not both).
0789: * </p>
0790: *
0791: * @param item
0792: * the menu item on which to register the computer
0793: * @param computer
0794: * the computer to determine the help contexts for the control
0795: * when F1 help is invoked
0796: * @deprecated context computers are no longer supported, clients should
0797: * implement their own help listener
0798: */
0799: public void setHelp(MenuItem item, IContextComputer computer) {
0800: item.setData(HELP_KEY, computer);
0801: // ensure that the listener is only registered once
0802: item.removeHelpListener(getHelpListener());
0803: item.addHelpListener(getHelpListener());
0804: }
0805:
0806: /**
0807: * Creates a new help listener for the given command. This retrieves the
0808: * help context ID from the command, and creates an appropriate listener
0809: * based on this.
0810: *
0811: * @param command
0812: * The command for which the listener should be created; must
0813: * not be <code>null</code>.
0814: * @return A help listener; never <code>null</code>.
0815: */
0816: public HelpListener createHelpListener(ICommand command) {
0817: // TODO Need a help ID from the context
0818: // final String contextId = command.getHelpId();
0819: final String contextId = ""; //$NON-NLS-1$
0820: return new HelpListener() {
0821: public void helpRequested(HelpEvent event) {
0822: if (getHelpUI() != null) {
0823: IContext context = HelpSystem.getContext(contextId);
0824: if (context != null) {
0825: Point point = computePopUpLocation(event.widget
0826: .getDisplay());
0827: displayContext(context, point.x, point.y);
0828: }
0829: }
0830: }
0831: };
0832: }
0833:
0834: /*
0835: * (non-Javadoc)
0836: *
0837: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp()
0838: */
0839: public void displayHelp() {
0840: AbstractHelpUI helpUI = getHelpUI();
0841: if (helpUI != null) {
0842: helpUI.displayHelp();
0843: }
0844: }
0845:
0846: /*
0847: * (non-Javadoc)
0848: *
0849: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displaySearch()
0850: */
0851: public void displaySearch() {
0852: AbstractHelpUI helpUI = getHelpUI();
0853: if (helpUI != null) {
0854: helpUI.displaySearch();
0855: }
0856: }
0857:
0858: /*
0859: * (non-Javadoc)
0860: *
0861: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displaySearch()
0862: */
0863: public void displayDynamicHelp() {
0864: AbstractHelpUI helpUI = getHelpUI();
0865: if (helpUI != null) {
0866: helpUI.displayDynamicHelp();
0867: }
0868: }
0869:
0870: /*
0871: * (non-Javadoc)
0872: *
0873: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#search(java.lang.String)
0874: */
0875: public void search(String expression) {
0876: AbstractHelpUI helpUI = getHelpUI();
0877: if (helpUI != null) {
0878: helpUI.search(expression);
0879: }
0880: }
0881:
0882: /* (non-Javadoc)
0883: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#resolve(java.lang.String, boolean)
0884: */
0885: public URL resolve(String href, boolean documentOnly) {
0886: AbstractHelpUI helpUI = getHelpUI();
0887: if (helpUI != null) {
0888: return helpUI.resolve(href, documentOnly);
0889: }
0890: return null;
0891: }
0892:
0893: /*
0894: * (non-Javadoc)
0895: *
0896: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayContext(org.eclipse.help.IContext,
0897: * int, int)
0898: */
0899: public void displayContext(IContext context, int x, int y) {
0900: if (context == null) {
0901: throw new IllegalArgumentException();
0902: }
0903: AbstractHelpUI helpUI = getHelpUI();
0904: if (helpUI != null) {
0905: helpUI.displayContext(context, x, y);
0906: }
0907: }
0908:
0909: /*
0910: * (non-Javadoc)
0911: *
0912: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelpResource(java.lang.String)
0913: */
0914: public void displayHelpResource(String href) {
0915: if (href == null) {
0916: throw new IllegalArgumentException();
0917: }
0918: AbstractHelpUI helpUI = getHelpUI();
0919: if (helpUI != null) {
0920: helpUI.displayHelpResource(href);
0921: }
0922: }
0923:
0924: /*
0925: * (non-Javadoc)
0926: *
0927: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp(java.lang.String)
0928: */
0929: public void displayHelp(String contextId) {
0930: IContext context = HelpSystem.getContext(contextId);
0931: if (context != null) {
0932: Point point = computePopUpLocation(Display.getCurrent());
0933: displayContext(context, point.x, point.y);
0934: }
0935: }
0936:
0937: /*
0938: * (non-Javadoc)
0939: *
0940: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp(org.eclipse.help.IContext)
0941: */
0942: public void displayHelp(IContext context) {
0943: Point point = computePopUpLocation(Display.getCurrent());
0944: AbstractHelpUI helpUI = getHelpUI();
0945: if (helpUI != null) {
0946: helpUI.displayContext(context, point.x, point.y);
0947: }
0948: }
0949:
0950: /*
0951: * (non-Javadoc)
0952: *
0953: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#isContextHelpDisplayed()
0954: */
0955: public boolean isContextHelpDisplayed() {
0956: if (!isInitialized) {
0957: return false;
0958: }
0959: AbstractHelpUI helpUI = getHelpUI();
0960: return helpUI != null && helpUI.isContextHelpDisplayed();
0961: }
0962:
0963: /*
0964: * (non-Javadoc)
0965: *
0966: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.jface.action.IAction,
0967: * java.lang.String)
0968: */
0969: public void setHelp(final IAction action, final String contextId) {
0970: action.setHelpListener(new HelpListener() {
0971: public void helpRequested(HelpEvent event) {
0972: if (getHelpUI() != null) {
0973: IContext context = HelpSystem.getContext(contextId);
0974: if (context != null) {
0975: Point point = computePopUpLocation(event.widget
0976: .getDisplay());
0977: displayContext(new ContextWithTitle(context,
0978: action.getText()), point.x, point.y);
0979: }
0980: }
0981: }
0982: });
0983: }
0984:
0985: /*
0986: * (non-Javadoc)
0987: *
0988: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.Control,
0989: * java.lang.String)
0990: */
0991: public void setHelp(Control control, String contextId) {
0992: control.setData(HELP_KEY, contextId);
0993: // ensure that the listener is only registered once
0994: control.removeHelpListener(getHelpListener());
0995: control.addHelpListener(getHelpListener());
0996: }
0997:
0998: /*
0999: * (non-Javadoc)
1000: *
1001: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.Menu,
1002: * java.lang.String)
1003: */
1004: public void setHelp(Menu menu, String contextId) {
1005: menu.setData(HELP_KEY, contextId);
1006: // ensure that the listener is only registered once
1007: menu.removeHelpListener(getHelpListener());
1008: menu.addHelpListener(getHelpListener());
1009: }
1010:
1011: /*
1012: * (non-Javadoc)
1013: *
1014: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.MenuItem,
1015: * java.lang.String)
1016: */
1017: public void setHelp(MenuItem item, String contextId) {
1018: item.setData(HELP_KEY, contextId);
1019: // ensure that the listener is only registered once
1020: item.removeHelpListener(getHelpListener());
1021: item.addHelpListener(getHelpListener());
1022: }
1023:
1024: /* (non-Javadoc)
1025: * @see org.eclipse.ui.help.IWorkbenchHelpSystem#hasHelpUI()
1026: */
1027: public boolean hasHelpUI() {
1028: return getHelpUI() != null;
1029: }
1030: }
|