platform-help-home/proposals/helpview/index.htm

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (view) (download) (as text)

1 : dejan 1.1 <html>
2 :    
3 :     <head>
4 :     <meta http-equiv="Content-Language" content="en-us">
5 :     <meta name="GENERATOR" content="Microsoft FrontPage 6.0">
6 :     <meta name="ProgId" content="FrontPage.Editor.Document">
7 :     <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
8 :     <title>Help Enhancements in Eclipse 3</title>
9 :     </head>
10 :    
11 :     <body>
12 :    
13 :     <h1 align="center">Help Enhancements in Eclipse 3.1</h1>
14 :     <p>This document describes new features added to provide for help and user
15 :     assistance in Eclipse 3.1 release. The enhancements are still in progress and
16 :     feedback is welcome. This document will be updated as changes are made towards
17 :     the general availability of the release.</p>
18 :     <h2>Help View</h2>
19 :     <p>Most of the new help features revolve around the newly added Help view. The
20 :     view is designed to be the universal location of most of the help needs inside
21 :     the Eclipse workbench. The standard standalone help window from previous version
22 :     is retained and is available via File&gt;Help Contents. The role of the view is to
23 :     bring help contents closer to the user inside the perspective where most of the
24 :     work is done.</p>
25 :     <p>The new Help view can show various classes of content in pages that are shown
26 :     one at a time. The following classes are currently available: Related Topics,
27 :     All Topics and Search.</p>
28 :     <h3>Related Topics</h3>
29 :     <p>This page shows help topics related to the current workbench context. It
30 :     replaces the yellow info pop window when F1 is pressed in the workbench. It is
31 :     also shown when context help is asked for programmatically. The topics
32 :     include context help contributed via help context help extension point, as well
33 :     as the result of a local help search on the query formed from the current
34 :     context. For example, if the currently active workbench part is 'Package
35 :     Explorer' inside the Java perspective, local help will be searched for (&quot;Package
36 :     Explorer view&quot; OR &quot;Java perspective&quot;). The first few results will be shown in
37 :     place, with the possibility to follow the link to more elaborate search.</p>
38 :     <p align="center">
39 :     <img border="0" src="related-topics.gif" width="275" height="705"></p>
40 :     <p>Related Topics page tracks changes in the workbench and updates accordingly.
41 :     Workbench parts can affect the way Related Topics page works by supporting <code>
42 :     IContextProvider</code> interface. This interface defines how the page should
43 :     react to the active part:</p>
44 :     <pre>public interface IContextProvider {
45 :     /**
46 :     * State change trigger indicating a static context provider.
47 :     */
48 :     int NONE = 0x0;
49 :    
50 :     /**
51 :     * State change trigger indicating that the provider should be asked for
52 :     * context help on each selection change.
53 :     */
54 :     int SELECTION = 0x1;
55 :    
56 :     /**
57 :     * Returns the mask created by combining supported change triggers using the
58 :     * bitwise OR operation.
59 :     *
60 :     * @return a bitwise-OR combination of state change triggers or
61 :     * &lt;code&gt;NONE&lt;/code&gt; for a static provider.
62 :     */
63 :     int getContextChangeMask();
64 :    
65 :     /**
66 :     * Returns a help context for the given target. The number of times this
67 :     * method will be called depends on the context change mask. Static context
68 :     * providers will be called each time the owner of the target is activated.
69 :     * If change triggers are used, the method will be called each time the
70 :     * trigger occurs.
71 :     *
72 :     * @param target
73 :     * the focus of the context help
74 :     * @return context help for the provided target or &lt;code&gt;null&lt;/code&gt; if
75 :     * none is defined.
76 :     */
77 :     IContext getContext(Object target);
78 :    
79 :     /**
80 :     * Returns a search expression that should be used to find more information
81 :     * about the current target. If provided, it can be used for background
82 :     * search.
83 :     *
84 :     * @param target
85 :     * the focus of the context help
86 :     * @return search expression as defined by the help system search, or
87 :     * &lt;code&gt;null&lt;/code&gt; if background search is not desired.
88 :     */
89 :     String getSearchExpression(Object target);
90 :     }</pre>
91 :     <p>Using the interface above can yield some interesting behavior. For example,
92 :     if the context change mask is <code>SELECTION</code>, and <code>getContext</code>
93 :     dynamically computes the context help for each selection, <b>Related Topics</b>
94 :     will be highly dynamic. An example of this is support for Java editor where
95 :     selections in the editor are reflected in the help view by showing the first
96 :     sentence of Javadoc for the selected type.</p>
97 :     <h3>All Topics</h3>
98 :     <p>This page shows the Table of Contents tree you can also see in the classic <b>
99 :     Help</b> window. The native Tree widget is tweaked somewhat to continue the
100 :     'web' user experience of the rest of the view. As a consequence, topics are
101 :     opened on a single mouse click and cursor turns into a hand pointer when over
102 :     the topics. However, tree item selections by the keyboard will not initiate the
103 :     'open' action - one needs to press 'Enter' to view the topic. This behavior
104 :     provides for the expected keyboard navigation and makes the tree close in
105 :     behavior to the counterpart in the Help window.</p>
106 :     <p align="center">[<img border="0" src="all-topics.gif" width="278" height="709"></p>
107 :     <h3>Search</h3>
108 :     <p>One of the key new features in the new view is the <b>Search</b> page. The
109 :     new mechanism supports federated search of multiple search engines running as
110 :     background jobs. All engines run on the common search expression, but each
111 :     engine's scope can be individually configured. Search expression follows certain
112 :     rules that can be found when the label links above the text field is expanded:</p>
113 :     <p align="center">
114 :     <img border="0" src="expanded-expression.gif" width="276" height="202"></p>
115 :     <p>If the provided text is not sufficient, the help link should be followed to
116 :     find more information.</p>
117 :     <h4>Search Types</h4>
118 :     <p>The new search support starts by providing the new extension point for
119 :     contributing <b>engine types </b>(extension point id 'org.eclipse.help.ui.searchEngine'). An
120 :     engine type is a proto-engine that can be
121 :     instantiated and configured to perform a particular search. At the moment,
122 :     Eclipse Help view provides three engine types out of the box:</p>
123 :     <ul>
124 :     <li><b>Local Help</b> - searches the local help documentation. Instances of
125 :     this type
126 :     do not require any configuration.</li>
127 :     <li><b>Info Center</b> - searches Eclipse help remote installation as Info
128 :     Center. Instances of this type require the remote server URL.</li>
129 :     <li><b>Web Search</b> - searches a general-purpose Web search engine.
130 :     Instances of this type require the web search URL template with substitution
131 :     variable for the query.</li>
132 :     </ul>
133 :     <p>Most search needs can be satisfied by configuring one of the above search
134 :     types. If that is not enough, new search types can be contributed using the
135 :     above mentioned extension point. A good reason to contribute a new engine type is the existence
136 :     of a separate domain where Eclipse users can find information for which there is
137 :     a mechanism to issue complex queries and get results in a format suitable for
138 :     parsing and presenting individually. For example, <b>Info Center</b> engine
139 :     talks to the remote Web application to fetch the help books for scope
140 :     configuration, as well as running the search and getting results in the XML
141 :     format. If the remote search application does not provide results in a format
142 :     that can be parsed, <b>Web Search</b> can be used to show the results in
143 :     HTML format.</p>
144 :     <p>Instances of search engine types can be created in two ways:</p>
145 :     <ul>
146 :     <li>Products can create engine instances as extension point contributions so
147 :     that they show up out of the box</li>
148 :     <li>Users can create new engines by choosing from the list of available types
149 :     and configuring the selected engine type on the fly</li>
150 :     </ul>
151 :     <h4>Configuring engines</h4>
152 :     <p align="center">
153 :     <img border="0" src="scope-section.gif" width="275" height="323"></p>
154 :     <p>Users can influence the search outcome in several ways. The fastest way to
155 :     tweak the search is to control which engine should run when 'Go' is pressed.
156 :     This is done by expanding the 'Scope Settings' section and checking the engines
157 :     that need to run. More detailed scope manipulation can be done when 'Advanced
158 :     Settings' link is selected.</p>
159 :     <p align="center">
160 :     <img border="0" src="search-scope-local.gif" width="627" height="542"></p>
161 :     <p align="center">
162 :     <img border="0" src="search-scope-web.gif" width="628" height="542"></p>
163 :     <p>The scope settings dialog is similar to preference pages and has nodes for
164 :     each configured search engine. Each engine has a page that contains the master
165 :     switch (linked to the one exposed in the scope section) and other scope settings
166 :     below it. The actual widgets for configuring scope settings depend on the engine
167 :     type. Local Help and Info Center types provide for narrowing the scope by
168 :     selecting particular books. Web search type provides the URL template that is
169 :     executed when search is performed.</p>
170 :     <p>Users can add to the list of preconfigured engines by pressing the 'New...'
171 :     button at the lower left edge of the dialog. This button brings up a dialog
172 :     allowing users to choose the search engine type:</p>
173 :     <p align="center">
174 :     <img border="0" src="engine-types.gif" width="401" height="500"></p>
175 :     <p>All the settings made to the search engines are stored under one named
176 :     preference set or <b>Scope Set</b>. Out of the box, the scope set that keeps the
177 :     engine preferences is called 'Default'. By clicking on the scope name link in
178 :     the <b>Search</b> page, it is possible to manipulate scope sets by creating new,
179 :     editing and deleting them. Scope sets provide for quick switching between
180 :     different search engine settings for all the configured engines at once.</p>
181 :     <p align="center"><img border="0" src="scope-sets.gif" width="320" height="376"></p>
182 :     <h4>Search results</h4>
183 :     <p>When engines are selected for search, search expression is entered and Go is
184 :     pressed, Search page will start each engine as a separate background job. As
185 :     results arrive, they will be shown below the scope section grouped by
186 :     engine (subject to selection of the tool bar button
187 :     <img border="0" src="../../../org.eclipse.help.ui/icons/elcl16/desc_obj.gif" width="16" height="16">). Search results consist of entries that can be navigated to, and optional
188 :     short description if the search engine supports it. When there are many results,
189 :     the page is kept manageable by breaking results in to groups of 10 (this number
190 :     will be configurable in the future). Search results can be shown flat, or
191 :     additionally grouped by category (tool bar button
192 :     <img border="0" src="../../../org.eclipse.help.ui/icons/elcl16/show_categories.gif" width="16" height="16">),
193 :     where category definition is provided by the results. For local help and Info
194 :     Center, categories are books the results are coming from (e.g. Workbench User
195 :     Guide, JDT ISV Guide etc.). Custom search engines can define their own
196 :     categories.</p>
197 :     <p align="center">
198 :     <img border="0" src="search-results.gif" width="276" height="705"></p>
199 :     <h3>Document Link Navigation</h3>
200 :     <p>All the pages in the new Help view can be opened in two ways:</p>
201 :     <ul>
202 :     <li>Internal-&nbsp; the page content will replace the content area of the
203 :     view (except the quick links at the bottom)</li>
204 :     <li>External - the page will be shown in a separate window</li>
205 :     </ul>
206 :     <p>The actual choice between the two options is controlled by several factors:</p>
207 :     <ul>
208 :     <li>If the creation of the embedded browser page fails or the embedded
209 :     browser in not supported on the particular OS, all links will be opened as
210 :     external.</li>
211 :     <li>If the link represents a help topic, it will be shown as internal.
212 :     However, external window can be forced either from the link's pop-up menu or
213 :     (in case of search results) from the image link next to the topic. Topics
214 :     shown in the external window will be shown in the context of the help system
215 :     (with TOC).</li>
216 :     <li>If the link represents a random URL, it will be shown as internal. If
217 :     external window is forced, it will be shown in a standalone web browser.</li>
218 :     <li>Search result objects that implement <code>ISearchEngineResult</code>
219 :     interface can demand that their link is opened as external (see <code>
220 :     ISearchEngineResult.getForceExternalWindow()).</code></li>
221 :     <li>Help document shown inside the Help view can be opened in the external
222 :     mode by following the tool bar button <img border="0" src="browser.gif">.</li>
223 :     </ul>
224 :    
225 :    
226 :    
227 :     <p align="center">
228 :     <img border="0" src="browser-part.gif" width="277" height="705"></p>
229 :    
230 :    
231 :    
232 :     <table border="1" cellpadding="0" style="border-collapse: collapse" width="100%" id="table1" bgcolor="#CCFFCC" bordercolor="#000000">
233 :     <tr>
234 :     <td>An orthogonal effort is currently under way to provide Platform UI
235 :     support for showing URLs. URLs can be shown in a read-only web browser
236 :     editor or an external browser suitable for the current OS/WS
237 :     combination. When/if this support becomes available, the definition of
238 :     'External' in the context of Help view will be 'the page will be shown
239 :     in a separate <b>browser</b>'. Whether this browser opens in the editor
240 :     area or as a separate browser window will be user
241 :     preference.</td>
242 :     </tr>
243 :     </table>
244 :    
245 :    
246 :    
247 :     </body>
248 :    
249 :     </html>