001: /*******************************************************************************
002: * Copyright (c) 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: import org.eclipse.jface.action.IAction;
016: import org.eclipse.swt.widgets.Control;
017: import org.eclipse.swt.widgets.Menu;
018: import org.eclipse.swt.widgets.MenuItem;
019:
020: /**
021: * <p>
022: * The interface that is used to access the workbench help system. Replaces
023: * static methods on <code>WorkbenchHelp</code>.
024: * </p>
025: * <p>
026: * This interface is not intended to be implemented by clients.
027: * </p>
028: *
029: * @since 3.1
030: */
031: public interface IWorkbenchHelpSystem {
032:
033: /**
034: * Returns whether there is a UI help system installed.
035: *
036: * @return whether there is a UI help system installed
037: */
038: boolean hasHelpUI();
039:
040: /**
041: * Displays the entire help bookshelf.
042: * <p>
043: * Ignored if no help UI is available.
044: * </p>
045: */
046: void displayHelp();
047:
048: /**
049: * Displays the help search system.
050: * <p>
051: * Ignored if no help UI is available.
052: * </p>
053: */
054: void displaySearch();
055:
056: /**
057: * Displays the dynamic help for the current UI context.
058: * <p>
059: * Ignored if no help UI is available.
060: * </p>
061: */
062: void displayDynamicHelp();
063:
064: /**
065: * Starts the search using the help search system.
066: * <p>
067: * Ignored if no help UI is available.
068: * </p>
069: *
070: * @param expression
071: * the search expression. The actual syntax rules of the
072: * expression are dependent on the active
073: * help system. Refer to the help system
074: * documentation for more details.
075: */
076: void search(String expression);
077:
078: /**
079: * Displays context-sensitive help for the given context.
080: * <p>
081: * (x,y) coordinates specify the location where the context sensitive help
082: * UI will be presented. These coordinates are screen-relative (ie: (0,0) is
083: * the top left-most screen corner). The platform is responsible for calling
084: * this method and supplying the appropriate location.
085: * </p>
086: * <p>
087: * Ignored if no help UI is available.
088: * </p>
089: *
090: * @param context
091: * the context to display
092: * @param x
093: * horizontal position
094: * @param y
095: * verifical position
096: */
097: void displayContext(IContext context, int x, int y);
098:
099: /**
100: * Displays help content for the help resource with the given URL.
101: * <p>
102: * This method is called by the platform to launch the help system UI,
103: * displaying the documentation identified by the <code>href</code>
104: * parameter.
105: * </p>
106: * <p>
107: * The help system makes no guarantee that all the help resources can be
108: * displayed or how they are displayed.
109: * </p>
110: * <p>
111: * Ignored if no help UI is available.
112: * </p>
113: *
114: * @param href
115: * the URL of the help resource.
116: * <p>
117: * Valid href are as described in
118: * {@link org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
119: * </p>
120: */
121: void displayHelpResource(String href);
122:
123: /**
124: * Calls the help support system to display the given help context id.
125: * <p>
126: * May only be called from a UI thread.
127: * <p>
128: *
129: * @param contextId
130: * the id of the context to display
131: */
132: void displayHelp(String contextId);
133:
134: /**
135: * Displays context-sensitive help for the given context.
136: * <p>
137: * May only be called from a UI thread.
138: * <p>
139: *
140: * @param context
141: * the context to display
142: */
143: void displayHelp(IContext context);
144:
145: /**
146: * Returns whether the context-sensitive help window is currently being
147: * displayed. Returns <code>false</code> if the help UI has not been
148: * activated yet.
149: *
150: * @return <code>true</code> if the context-sensitive help window is
151: * currently being displayed, <code>false</code> otherwise
152: */
153: boolean isContextHelpDisplayed();
154:
155: /**
156: * Sets the given help context id on the given action.
157: *
158: * @param action
159: * the action on which to register the context id
160: * @param contextId
161: * the context id to use when F1 help is invoked
162: */
163: void setHelp(IAction action, String contextId);
164:
165: /**
166: * Sets the given help context id on the given control.
167: *
168: * @param control
169: * the control on which to register the context id
170: * @param contextId
171: * the context id to use when F1 help is invoked
172: */
173: void setHelp(Control control, String contextId);
174:
175: /**
176: * Sets the given help context id on the given menu.
177: *
178: * @param menu
179: * the menu on which to register the context id
180: * @param contextId
181: * the context id to use when F1 help is invoked
182: */
183: void setHelp(Menu menu, String contextId);
184:
185: /**
186: * Sets the given help context id on the given menu item.
187: *
188: * @param item
189: * the menu item on which to register the context id
190: * @param contextId
191: * the context id to use when F1 help is invoked
192: */
193: void setHelp(MenuItem item, String contextId);
194:
195: /**
196: * Resolves the help resource href by converting it into a legitimate URL
197: * according to the implementation of the help system. Help resources that
198: * already have a protocol will be unchanged.
199: *
200: * @param href
201: * @param documentOnly if <code>true</code>, the resulting URL must point
202: * at the document referenced by href. Otherwise, it can be a URL that
203: * contains additional elements like navigation that the help system
204: * adds to the document.
205: * @return the resolved URL or <code>null</code> if no help UI is
206: * available.
207: */
208: URL resolve(String href, boolean documentOnly);
209: }
|