- * The Eclipse platform provides an extension point
- * ("org.eclipse.ui.helpSupport") for plugging in a help system UI.
- * The help system UI is an optional component; applications may provide a UI
- * for presenting help to the user by implementing a subclass and including the
- * name of their class in the <config> element in an
- * extension to the "org.eclipse.ui.helpSupport" extension point.
+ * The Eclipse platform provides an extension point ("org.eclipse.ui.helpSupport")
+ * for plugging in a help system UI. The help system UI is an optional
+ * component; applications may provide a UI for presenting help to the user by
+ * implementing a subclass and including the name of their class in the
+ * <config> element in an extension to the
+ * "org.eclipse.ui.helpSupport" extension point.
*
* Note that the standard implementation of the help system UI is provided by
* the "org.eclipse.help.ui" plug-in. Since the platform can only
* make use of a single help system UI implementation, make sure that the
- * platform is not configured with more than one plug-in trying to extend
- * this extension point.
+ * platform is not configured with more than one plug-in trying to extend this
+ * extension point.
*
null. Implementors are expected
- * to provide a non-trivial implementation.
- *
- * @param href the help resource
- * @param documentOnly if true, the resulting URL must point
- * at the document referenced by href. Otherwise, it can be a URL that
- * contains additional elements like navigation that the help system
- * adds to the document.
- * @return null
+ /**
+ * Displays the entire help bookshelf.
+ */
+ public abstract void displayHelp();
+
+ /**
+ * Displays the help search facility. For backward compatibility, the
+ * default implementation does nothing.
+ *
+ * @since 3.1
+ */
+ public void displaySearch() {
+ // do nothing
+ }
+
+ /**
+ * Displays the dynamic help for the active context. For backward
+ * compatibility, the default implementation does nothing.
+ *
+ * @since 3.1
+ */
+ public void displayDynamicHelp() {
+ // do nothing
+ }
+
+ /**
+ * Starts the help search using the help search facility. For backward
+ * compatibility, the default implementation does nothing.
+ *
+ * @param expression
+ * the search expression
+ * @since 3.1
+ */
+ public void search(String expression) {
+ // do nothing
+ }
+
+ /**
+ * Resolves the help resource href according to the help system
+ * implementation.
+ *
+ * @param href
+ * the help resource
+ * @param documentOnly
+ * if true, the resulting URL must point at the
+ * document referenced by href. Otherwise, it can be a URL that
+ * contains additional elements like navigation that the help
+ * system adds to the document.
+ * @return the fully resolved URL of the help resource or null
+ * if not supported. Help systems that use application servers
+ * typically return URLs with http: protocol. Simple help system
+ * implementations can return URLs with file: protocol.
+ *
* @since 3.1
*/
public URL resolve(String href, boolean documentOnly) {
return null;
}
+
/**
- * Restores the original help resource previously resolved
- * using the resolve method.
- * For backward compatibility, the default implementation
- * returns the source url. Implementors are expected
- * to provide a non-trivial implementation.
+ * Restores the original help resource previously resolved using the
+ * resolve method.
*
- * @param url the url to unresolve
- * @return the unchanged source url
+ * @param url
+ * the url to unresolve
+ * @return the original help resource that is part of the source URL or
+ * null if not supported.
*
* @since 3.1
+ * @see #resolve(java.lang.String,boolean)
*/
public String unresolve(URL url) {
- return url.toString();
+ return null;
}
- /**
- * Displays context-sensitive help for the given context.
- * - * (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. - *
- * - * @param context the context to display - * @param x horizontal position - * @param y verifical position - */ - public abstract void displayContext(IContext context, int x, int y); - - /** - * Displays help content for the help resource with the given URL. - *
- * This method is called by the platform to launch the help system UI, displaying
- * the documentation identified by the href parameter.
- *
- * The help system makes no guarantee that all the help resources can be displayed or how they are displayed. - *
- * @param href the URL of the help resource. - *Valid href are as described in - * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()} - *
- */ - public abstract void displayHelpResource(String href); - - /** - * Returns whether the context-sensitive help window is currently being - * displayed. - * - * @returntrue if the context-sensitive help
- * window is currently being displayed, false if not
- */
- public abstract boolean isContextHelpDisplayed();
+ /**
+ * Displays context-sensitive help for the given context.
+ * + * (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. + *
+ * + * @param context + * the context to display + * @param x + * horizontal position + * @param y + * verifical position + */ + public abstract void displayContext(IContext context, int x, int y); + + /** + * Displays help content for the help resource with the given URL. + *
+ * This method is called by the platform to launch the help system UI,
+ * displaying the documentation identified by the href
+ * parameter.
+ *
+ * The help system makes no guarantee that all the help resources can be + * displayed or how they are displayed. + *
+ * + * @param href + * the URL of the help resource. + *+ * Valid href are as described in + * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()} + *
+ */ + public abstract void displayHelpResource(String href); + + /** + * Returns whether the context-sensitive help window is currently being + * displayed. + * + * @returntrue if the context-sensitive help window is
+ * currently being displayed, false if not
+ */
+ public abstract boolean isContextHelpDisplayed();
}
Index: Eclipse UI/org/eclipse/ui/help/IWorkbenchHelpSystem.java
===================================================================
RCS file: /home/eclipse/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/help/IWorkbenchHelpSystem.java,v
retrieving revision 1.9
diff -u -r1.9 IWorkbenchHelpSystem.java
--- Eclipse UI/org/eclipse/ui/help/IWorkbenchHelpSystem.java 29 Mar 2005 01:26:10 -0000 1.9
+++ Eclipse UI/org/eclipse/ui/help/IWorkbenchHelpSystem.java 29 Mar 2005 02:35:58 -0000
@@ -216,7 +216,7 @@
*
* @param url
* the URL that needs to be unresolved into an href.
- * @return the unresolved href or the source url if no help UI is available.
+ * @return the unresolved href or null if no help UI is available.
*/
String unresolve(URL url);
}
\ No newline at end of file