platform-help-home/proposals/helpview/index.htm
Parent Directory
| 
Revision Log
Revision 1.1 -
(download)
(as text)
(annotate)
Mon Feb 7 18:35:36 2005 UTC (4 years, 9 months ago) by dejan
Branch: MAIN
CVS Tags: R3_1, HEAD
Mon Feb 7 18:35:36 2005 UTC (4 years, 9 months ago) by dejan
Branch: MAIN
CVS Tags: R3_1, HEAD
*** empty log message ***
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Help Enhancements in Eclipse 3</title>
</head>
<body>
<h1 align="center">Help Enhancements in Eclipse 3.1</h1>
<p>This document describes new features added to provide for help and user
assistance in Eclipse 3.1 release. The enhancements are still in progress and
feedback is welcome. This document will be updated as changes are made towards
the general availability of the release.</p>
<h2>Help View</h2>
<p>Most of the new help features revolve around the newly added Help view. The
view is designed to be the universal location of most of the help needs inside
the Eclipse workbench. The standard standalone help window from previous version
is retained and is available via File>Help Contents. The role of the view is to
bring help contents closer to the user inside the perspective where most of the
work is done.</p>
<p>The new Help view can show various classes of content in pages that are shown
one at a time. The following classes are currently available: Related Topics,
All Topics and Search.</p>
<h3>Related Topics</h3>
<p>This page shows help topics related to the current workbench context. It
replaces the yellow info pop window when F1 is pressed in the workbench. It is
also shown when context help is asked for programmatically. The topics
include context help contributed via help context help extension point, as well
as the result of a local help search on the query formed from the current
context. For example, if the currently active workbench part is 'Package
Explorer' inside the Java perspective, local help will be searched for ("Package
Explorer view" OR "Java perspective"). The first few results will be shown in
place, with the possibility to follow the link to more elaborate search.</p>
<p align="center">
<img border="0" src="related-topics.gif" width="275" height="705"></p>
<p>Related Topics page tracks changes in the workbench and updates accordingly.
Workbench parts can affect the way Related Topics page works by supporting <code>
IContextProvider</code> interface. This interface defines how the page should
react to the active part:</p>
<pre>public interface IContextProvider {
/**
* State change trigger indicating a static context provider.
*/
int NONE = 0x0;
/**
* State change trigger indicating that the provider should be asked for
* context help on each selection change.
*/
int SELECTION = 0x1;
/**
* Returns the mask created by combining supported change triggers using the
* bitwise OR operation.
*
* @return a bitwise-OR combination of state change triggers or
* <code>NONE</code> for a static provider.
*/
int getContextChangeMask();
/**
* Returns a help context for the given target. The number of times this
* method will be called depends on the context change mask. Static context
* providers will be called each time the owner of the target is activated.
* If change triggers are used, the method will be called each time the
* trigger occurs.
*
* @param target
* the focus of the context help
* @return context help for the provided target or <code>null</code> if
* none is defined.
*/
IContext getContext(Object target);
/**
* Returns a search expression that should be used to find more information
* about the current target. If provided, it can be used for background
* search.
*
* @param target
* the focus of the context help
* @return search expression as defined by the help system search, or
* <code>null</code> if background search is not desired.
*/
String getSearchExpression(Object target);
}</pre>
<p>Using the interface above can yield some interesting behavior. For example,
if the context change mask is <code>SELECTION</code>, and <code>getContext</code>
dynamically computes the context help for each selection, <b>Related Topics</b>
will be highly dynamic. An example of this is support for Java editor where
selections in the editor are reflected in the help view by showing the first
sentence of Javadoc for the selected type.</p>
<h3>All Topics</h3>
<p>This page shows the Table of Contents tree you can also see in the classic <b>
Help</b> window. The native Tree widget is tweaked somewhat to continue the
'web' user experience of the rest of the view. As a consequence, topics are
opened on a single mouse click and cursor turns into a hand pointer when over
the topics. However, tree item selections by the keyboard will not initiate the
'open' action - one needs to press 'Enter' to view the topic. This behavior
provides for the expected keyboard navigation and makes the tree close in
behavior to the counterpart in the Help window.</p>
<p align="center">[<img border="0" src="all-topics.gif" width="278" height="709"></p>
<h3>Search</h3>
<p>One of the key new features in the new view is the <b>Search</b> page. The
new mechanism supports federated search of multiple search engines running as
background jobs. All engines run on the common search expression, but each
engine's scope can be individually configured. Search expression follows certain
rules that can be found when the label links above the text field is expanded:</p>
<p align="center">
<img border="0" src="expanded-expression.gif" width="276" height="202"></p>
<p>If the provided text is not sufficient, the help link should be followed to
find more information.</p>
<h4>Search Types</h4>
<p>The new search support starts by providing the new extension point for
contributing <b>engine types </b>(extension point id 'org.eclipse.help.ui.searchEngine'). An
engine type is a proto-engine that can be
instantiated and configured to perform a particular search. At the moment,
Eclipse Help view provides three engine types out of the box:</p>
<ul>
<li><b>Local Help</b> - searches the local help documentation. Instances of
this type
do not require any configuration.</li>
<li><b>Info Center</b> - searches Eclipse help remote installation as Info
Center. Instances of this type require the remote server URL.</li>
<li><b>Web Search</b> - searches a general-purpose Web search engine.
Instances of this type require the web search URL template with substitution
variable for the query.</li>
</ul>
<p>Most search needs can be satisfied by configuring one of the above search
types. If that is not enough, new search types can be contributed using the
above mentioned extension point. A good reason to contribute a new engine type is the existence
of a separate domain where Eclipse users can find information for which there is
a mechanism to issue complex queries and get results in a format suitable for
parsing and presenting individually. For example, <b>Info Center</b> engine
talks to the remote Web application to fetch the help books for scope
configuration, as well as running the search and getting results in the XML
format. If the remote search application does not provide results in a format
that can be parsed, <b>Web Search</b> can be used to show the results in
HTML format.</p>
<p>Instances of search engine types can be created in two ways:</p>
<ul>
<li>Products can create engine instances as extension point contributions so
that they show up out of the box</li>
<li>Users can create new engines by choosing from the list of available types
and configuring the selected engine type on the fly</li>
</ul>
<h4>Configuring engines</h4>
<p align="center">
<img border="0" src="scope-section.gif" width="275" height="323"></p>
<p>Users can influence the search outcome in several ways. The fastest way to
tweak the search is to control which engine should run when 'Go' is pressed.
This is done by expanding the 'Scope Settings' section and checking the engines
that need to run. More detailed scope manipulation can be done when 'Advanced
Settings' link is selected.</p>
<p align="center">
<img border="0" src="search-scope-local.gif" width="627" height="542"></p>
<p align="center">
<img border="0" src="search-scope-web.gif" width="628" height="542"></p>
<p>The scope settings dialog is similar to preference pages and has nodes for
each configured search engine. Each engine has a page that contains the master
switch (linked to the one exposed in the scope section) and other scope settings
below it. The actual widgets for configuring scope settings depend on the engine
type. Local Help and Info Center types provide for narrowing the scope by
selecting particular books. Web search type provides the URL template that is
executed when search is performed.</p>
<p>Users can add to the list of preconfigured engines by pressing the 'New...'
button at the lower left edge of the dialog. This button brings up a dialog
allowing users to choose the search engine type:</p>
<p align="center">
<img border="0" src="engine-types.gif" width="401" height="500"></p>
<p>All the settings made to the search engines are stored under one named
preference set or <b>Scope Set</b>. Out of the box, the scope set that keeps the
engine preferences is called 'Default'. By clicking on the scope name link in
the <b>Search</b> page, it is possible to manipulate scope sets by creating new,
editing and deleting them. Scope sets provide for quick switching between
different search engine settings for all the configured engines at once.</p>
<p align="center"><img border="0" src="scope-sets.gif" width="320" height="376"></p>
<h4>Search results</h4>
<p>When engines are selected for search, search expression is entered and Go is
pressed, Search page will start each engine as a separate background job. As
results arrive, they will be shown below the scope section grouped by
engine (subject to selection of the tool bar button
<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
short description if the search engine supports it. When there are many results,
the page is kept manageable by breaking results in to groups of 10 (this number
will be configurable in the future). Search results can be shown flat, or
additionally grouped by category (tool bar button
<img border="0" src="../../../org.eclipse.help.ui/icons/elcl16/show_categories.gif" width="16" height="16">),
where category definition is provided by the results. For local help and Info
Center, categories are books the results are coming from (e.g. Workbench User
Guide, JDT ISV Guide etc.). Custom search engines can define their own
categories.</p>
<p align="center">
<img border="0" src="search-results.gif" width="276" height="705"></p>
<h3>Document Link Navigation</h3>
<p>All the pages in the new Help view can be opened in two ways:</p>
<ul>
<li>Internal- the page content will replace the content area of the
view (except the quick links at the bottom)</li>
<li>External - the page will be shown in a separate window</li>
</ul>
<p>The actual choice between the two options is controlled by several factors:</p>
<ul>
<li>If the creation of the embedded browser page fails or the embedded
browser in not supported on the particular OS, all links will be opened as
external.</li>
<li>If the link represents a help topic, it will be shown as internal.
However, external window can be forced either from the link's pop-up menu or
(in case of search results) from the image link next to the topic. Topics
shown in the external window will be shown in the context of the help system
(with TOC).</li>
<li>If the link represents a random URL, it will be shown as internal. If
external window is forced, it will be shown in a standalone web browser.</li>
<li>Search result objects that implement <code>ISearchEngineResult</code>
interface can demand that their link is opened as external (see <code>
ISearchEngineResult.getForceExternalWindow()).</code></li>
<li>Help document shown inside the Help view can be opened in the external
mode by following the tool bar button <img border="0" src="browser.gif">.</li>
</ul>
<p align="center">
<img border="0" src="browser-part.gif" width="277" height="705"></p>
<table border="1" cellpadding="0" style="border-collapse: collapse" width="100%" id="table1" bgcolor="#CCFFCC" bordercolor="#000000">
<tr>
<td>An orthogonal effort is currently under way to provide Platform UI
support for showing URLs. URLs can be shown in a read-only web browser
editor or an external browser suitable for the current OS/WS
combination. When/if this support becomes available, the definition of
'External' in the context of Help view will be 'the page will be shown
in a separate <b>browser</b>'. Whether this browser opens in the editor
area or as a separate browser window will be user
preference.</td>
</tr>
</table>
</body>
</html>| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |