001: /*******************************************************************************
002: * Copyright (c) 2003, 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 java.net.URL;
013:
014: import org.eclipse.help.IContext;
015:
016: /**
017: * Abstract base class for the help system UI.
018: * <p>
019: * The Eclipse platform provides an extension point (<code>"org.eclipse.ui.helpSupport"</code>)
020: * for plugging in a help system UI. The help system UI is an optional
021: * component; applications may provide a UI for presenting help to the user by
022: * implementing a subclass and including the name of their class in the
023: * <code><config></code> element in an extension to the
024: * <code>"org.eclipse.ui.helpSupport"</code> extension point.
025: * </p>
026: * <p>
027: * Note that the standard implementation of the help system UI is provided by
028: * the <code>"org.eclipse.help.ui"</code> plug-in. Since the platform can only
029: * make use of a single help system UI implementation, make sure that the
030: * platform is not configured with more than one plug-in trying to extend this
031: * extension point.
032: * </p>
033: *
034: * @since 3.0
035: */
036: public abstract class AbstractHelpUI {
037:
038: /**
039: * Displays the entire help bookshelf.
040: */
041: public abstract void displayHelp();
042:
043: /**
044: * Displays the help search facility. For backward compatibility, the
045: * default implementation does nothing.
046: *
047: * @since 3.1
048: */
049: public void displaySearch() {
050: // do nothing
051: }
052:
053: /**
054: * Displays the dynamic help for the active context. For backward
055: * compatibility, the default implementation does nothing.
056: *
057: * @since 3.1
058: */
059: public void displayDynamicHelp() {
060: // do nothing
061: }
062:
063: /**
064: * Starts the help search using the help search facility. For backward
065: * compatibility, the default implementation does nothing.
066: *
067: * @param expression
068: * the search expression
069: * @since 3.1
070: */
071: public void search(String expression) {
072: // do nothing
073: }
074:
075: /**
076: * Resolves the help resource href according to the help system
077: * implementation.
078: *
079: * @param href
080: * the help resource
081: * @param documentOnly
082: * if <code>true</code>, the resulting URL must point at the
083: * document referenced by href. Otherwise, it can be a URL that
084: * contains additional elements like navigation that the help
085: * system adds to the document.
086: * @return the fully resolved URL of the help resource or <code>null</code>
087: * if not supported. Help systems that use application servers
088: * typically return URLs with http: protocol. Simple help system
089: * implementations can return URLs with file: protocol.
090: *
091: * @since 3.1
092: */
093: public URL resolve(String href, boolean documentOnly) {
094: return null;
095: }
096:
097: /**
098: * Displays context-sensitive help for the given context.
099: * <p>
100: * (x,y) coordinates specify the location where the context sensitive help
101: * UI will be presented. These coordinates are screen-relative (ie: (0,0) is
102: * the top left-most screen corner). The platform is responsible for calling
103: * this method and supplying the appropriate location.
104: * </p>
105: *
106: * @param context
107: * the context to display
108: * @param x
109: * horizontal position
110: * @param y
111: * verifical position
112: */
113: public abstract void displayContext(IContext context, int x, int y);
114:
115: /**
116: * Displays help content for the help resource with the given URL.
117: * <p>
118: * This method is called by the platform to launch the help system UI,
119: * displaying the documentation identified by the <code>href</code>
120: * parameter.
121: * </p>
122: * <p>
123: * The help system makes no guarantee that all the help resources can be
124: * displayed or how they are displayed.
125: * </p>
126: *
127: * @param href
128: * the URL of the help resource.
129: * <p>
130: * Valid href are as described in
131: * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
132: * </p>
133: */
134: public abstract void displayHelpResource(String href);
135:
136: /**
137: * Returns whether the context-sensitive help window is currently being
138: * displayed.
139: *
140: * @return <code>true</code> if the context-sensitive help window is
141: * currently being displayed, <code>false</code> if not
142: */
143: public abstract boolean isContextHelpDisplayed();
144: }
|