platform-ua/proposals/helpview/index.htm - www.eclipse.org/eclipse - Git at Google

 <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&gt;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 (&quot;Package
 Explorer view&quot; OR &quot;Java perspective&quot;). 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
 	 *         &lt;code&gt;NONE&lt;/code&gt; 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 &lt;code&gt;null&lt;/code&gt; 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
 	 *         &lt;code&gt;null&lt;/code&gt; 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-&nbsp; 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>
	<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>