AbstractHelpUI


1   /*******************************************************************************
2    * Copyright (c) 2003, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.help;
12  
13  import java.net.URL  ;
14  
15  import org.eclipse.help.IContext;
16  
17  /**
18   * Abstract base class for the help system UI.
19   * <p>
20   * The Eclipse platform provides an extension point (<code>"org.eclipse.ui.helpSupport"</code>)
21   * for plugging in a help system UI. The help system UI is an optional
22   * component; applications may provide a UI for presenting help to the user by
23   * implementing a subclass and including the name of their class in the
24   * <code>&lt;config&gt;</code> element in an extension to the
25   * <code>"org.eclipse.ui.helpSupport"</code> extension point.
26   * </p>
27   * <p>
28   * Note that the standard implementation of the help system UI is provided by
29   * the <code>"org.eclipse.help.ui"</code> plug-in. Since the platform can only
30   * make use of a single help system UI implementation, make sure that the
31   * platform is not configured with more than one plug-in trying to extend this
32   * extension point.
33   * </p>
34   * 
35   * @since 3.0
36   */
37  public abstract class AbstractHelpUI {
38  
39      /**
40       * Displays the entire help bookshelf.
41       */
42      public abstract void displayHelp();
43  
44      /**
45       * Displays the help search facility. For backward compatibility, the
46       * default implementation does nothing.
47       * 
48       * @since 3.1
49       */
50      public void displaySearch() {
51          // do nothing
52      }
53  
54      /**
55       * Displays the dynamic help for the active context. For backward
56       * compatibility, the default implementation does nothing.
57       * 
58       * @since 3.1
59       */
60      public void displayDynamicHelp() {
61          // do nothing
62      }
63  
64      /**
65       * Starts the help search using the help search facility. For backward
66       * compatibility, the default implementation does nothing.
67       * 
68       * @param expression
69       *            the search expression
70       * @since 3.1
71       */
72      public void search(String   expression) {
73          // do nothing
74      }
75  
76      /**
77       * Resolves the help resource href according to the help system
78       * implementation.
79       * 
80       * @param href
81       *            the help resource
82       * @param documentOnly
83       *            if <code>true</code>, the resulting URL must point at the
84       *            document referenced by href. Otherwise, it can be a URL that
85       *            contains additional elements like navigation that the help
86       *            system adds to the document.
87       * @return the fully resolved URL of the help resource or <code>null</code>
88       *         if not supported. Help systems that use application servers
89       *         typically return URLs with http: protocol. Simple help system
90       *         implementations can return URLs with file: protocol.
91       * 
92       * @since 3.1
93       */
94      public URL   resolve(String   href, boolean documentOnly) {
95          return null;
96      }
97  
98      /**
99       * Displays context-sensitive help for the given context.
100      * <p>
101      * (x,y) coordinates specify the location where the context sensitive help
102      * UI will be presented. These coordinates are screen-relative (ie: (0,0) is
103      * the top left-most screen corner). The platform is responsible for calling
104      * this method and supplying the appropriate location.
105      * </p>
106      * 
107      * @param context
108      *            the context to display
109      * @param x
110      *            horizontal position
111      * @param y
112      *            verifical position
113      */
114     public abstract void displayContext(IContext context, int x, int y);
115 
116     /**
117      * Displays help content for the help resource with the given URL.
118      * <p>
119      * This method is called by the platform to launch the help system UI,
120      * displaying the documentation identified by the <code>href</code>
121      * parameter.
122      * </p>
123      * <p>
124      * The help system makes no guarantee that all the help resources can be
125      * displayed or how they are displayed.
126      * </p>
127      * 
128      * @param href
129      *            the URL of the help resource.
130      *            <p>
131      *            Valid href are as described in
132      *            {@link  org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
133      *            </p>
134      */
135     public abstract void displayHelpResource(String   href);
136 
137     /**
138      * Returns whether the context-sensitive help window is currently being
139      * displayed.
140      * 
141      * @return <code>true</code> if the context-sensitive help window is
142      *         currently being displayed, <code>false</code> if not
143      */
144     public abstract boolean isContextHelpDisplayed();
145 }
146
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags