Attachment 129905 Details for Bug 270042 – Preliminary work

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

[patch] Preliminary work

clipboard.txt (text/plain), 18.59 KB, created by Francis Upton IV

on 2009-03-25 19:18:52 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: Francis Upton IV

Created: 2009-03-25 19:18:52 EDT

Size: 18.59 KB

patch

obsolete

>### Eclipse Workspace Patch 1.0
>#P org.eclipse.platform.doc.isv
>Index: guide/cnf.htm
>===================================================================
>RCS file: /cvsroot/eclipse/org.eclipse.platform.doc.isv/guide/cnf.htm,v
>retrieving revision 1.5
>diff -u -r1.5 cnf.htm
>--- guide/cnf.htm	26 Aug 2008 00:09:17 -0000	1.5
>+++ guide/cnf.htm	25 Mar 2009 23:17:30 -0000
>@@ -3,7 +3,7 @@
> <HEAD>
> 
> <meta name="copyright"
>-	content="Copyright (c) Oakland Software and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+	content="Copyright (c) Oakland Software and others 2008, 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
> 
> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
> <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>@@ -17,6 +17,94 @@
> <BODY BGCOLOR="#ffffff">
> <H1>Common Navigator Framework</H1>
> 
>+A Viewer provides the user with a view of objects using a single
>+content provider, label provider, sorter and filter. The Common
>+Navigator Framework (CNF) extends this idea by allowing a single view to
>+dynamically use multiple and unrelated sets of content providers, label
>+providers, sorters and filters. These can be activated in the view
>+depending on declarative expressions or using API calls.
>+The CNF implemented by the <a
>+	href="../reference/api/org/eclipse/ui/navigator/package-summary.html">
>+org.eclipse.ui.navigator</a> plugin.
>+
>+The CNF uses the idea of Navigator Content Extensions
>+(NCE) which can refer to a content provider, label provider, sorter, or
>+drag adaptor (note that filters are configured separately). An NCE has
>+associated expressions that tell it when it is active. NCEs are also
>+presented to the user in the view context menu so that user can turn
>+them on or off in order to show the view in different ways. Examples of
>+NCEs are a resource content extension that controls how resources are
>+presented and Java content extension that shows Java projects. In the
>+IDE's Project Explorer, you can turn off the Java content extension
>+getting a pure resource view of the workspace.
>+
>+By using the NCEs it's possible to include different model objects directly 
>+in the view. These model objects might be related in a cascading fashion. For example
>+a resource object (an <code>IFile</code>) might refer to a Java class object. This Java class
>+object can be presented directly in the view by defining an NCE. The Java class object
>+can have children (representing methods, fields, etc) all of which appear in the view.
>+You can then add another NCE to display model objects related to the Java (or resource
>+object) that display content related to a Java Server Page object. This can
>+all be done without the "lower level" NCEs (resources, Java) being aware of the existence of the "outer" NCEs (JSP).
>+Further, it's possible for outer NCEs to override by suppressing processing associated with 
>+lower level NCEs according to their requirements. And even further, it's possible (using 
>+the pipelining mechanism) for even level in this cascaded set of NCEs to arrange the presentation
>+of the objects according to their specifications, moving, adding, or suppressing objects as necessary.
>+
>+
>+???The CNF has depends only on <code>org.eclipse.ui</code> 
>+and is suitable for use both within the IDE and in an RCP application.
>+
>+The CNF is highly configurable and many of its components can be used separately (though this is not
>+the typical case). For example,
>+it's possible use the service that manages content extensions with a viewer other than the standard
>+<code>CommonViewer</code>. 
>+
>+
>+<h2>Major Components of the Common Navigator Framework</h2>
>+
>+The CNF has the following major parts:
>+<ol>
>+	<li>View Part - <a
>+		href="../reference/api/org/eclipse/ui/navigator/CommonNavigator.html">CommonNavigator
>+	</a>.</li>
>+	<li>Viewer -<a
>+		href="../reference/api/org/eclipse/ui/navigator/CommonViewer.html">CommonViewer
>+	</a> the implementation of a viewer that is contained in the above view
>+	part.</li>
>+	<li>Navigator Content Service - <a
>+		href="../reference/api/org/eclipse/ui/navigator/INavigatorContentService.html">INavigatorContentService
>+	</a> a service that manages content extensions and allows them to be
>+	discovered based on objects associated with a viewer. Most users do not
>+	interact directly with the Content Service, but it is possible to use
>+	it independently from the common navigator view part.</li>
>+</ol>
>+
>+<h2>Navigators - Where the CNF Fits</h2>
>+
>+There are currently 3 major navigators in the Eclipse IDE.
>+<ol>
>+<li>Project Explorer - This is an instance of the CommonNavigator that is provided by the <a
>+	href="../reference/api/org/eclipse/ui/navigator/resources/package-summary.html">
>+org.eclipse.ui.navigator.resources</a> plugin. It provides a view of the workspace
>+and has a large number of NCEs contributed for resources, Java, C, Web Tools, Data Tools, PHP, etc.</li>
>+<li>
>+Package Explorer - Provided by the Java Development Tools (JDT) UI project, this provides
>+a view of Java classes for the workspace. Generally speaking, the presentation of the Package Explorer 
>+and Project Explorer for Java objects is substantially similar. The JDT is not used for projects beyond Java.
>+</li>
>+<li>Navigator - This view is an implementation of the now deprecated (as of 3.5) 
>+ResourceNavigator class
>+provided in the <code>org.eclipse.ui.ide</code> plugin. It shows only the workspace resources and does not
>+support extensibility to show other content. In a future release, the Navigator view will 
>+be provided by an implementation of the CommonNavigator.
>+</li>
>+</ol>
>+The only navigator intended for general purpose client use if the CNF, which can be used
>+either by adding NCEs visable in the Project Explorer (if developing an IDE plugin), or using a
>+separate instance of the CommonNavigator as a view.
>+
>+
> 
> The Common Navigator Framework (CNF) provides a general purpose
> configurable navigator view which can be shared by many applications
>Index: guide/cnf_steps_rcp.htm
>===================================================================
>RCS file: guide/cnf_steps_rcp.htm
>diff -N guide/cnf_steps_rcp.htm
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ guide/cnf_steps_rcp.htm	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,119 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<HTML>
>+<HEAD>
>+
>+<meta name="copyright"
>+	content="Copyright (c) Oakland Software and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+
>+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
>+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>+
>+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"
>+	TYPE="text/css">
>+<TITLE>Using the Common Navigator in an RCP Application</TITLE>
>+
>+<link rel="stylesheet" type="text/css" HREF="../book.css">
>+</HEAD>
>+<BODY BGCOLOR="#ffffff">
>+<h1>Using the Common Navigator in an RCP Application</h1>
>+
>+
>+To add the Common Navigator to an RCP application and have it manipulate the
>+workspace resources, first follow the <a href="cnf_steps_resources.htm">steps</a>
>+and then follow these. If you don't want to have the CN to use resources, omit
>+the resources steps.
>+
>+
>+<ol>
>+<li>
>+Add the following as dependent plug-ins:
>+<ol type="a">
>+<li>org.eclipse.ui.navigator</li>
>+</ol>
>+</li>
>+<li>Add a View extension (org.eclipse.ui.views) which uses the class org.eclipse.ui.navigator.CommonNavigator.
>+<pre>
>+ &lt;extension
>+ point="org.eclipse.ui.views"&gt;
>+ &lt;view
>+ name="View"
>+ class="org.eclipse.ui.navigator.CommonNavigator"
>+ id="example.view"&gt;
>+ &lt;/view&gt;
>+ &lt;/extension&gt;
>+</pre>
>+</li>
>+<li>Update your perspective factory (IPerspectiveFactory) code to show the new View (this is necessary when adding any View):
>+
>+<pre>
>+	public void createInitialLayout(IPageLayout layout) {
>+		String editorArea = layout.getEditorArea();
>+		layout.setEditorAreaVisible(false);
>+		layout.setFixed(true);
>+		
>+		layout.addStandaloneView("example.view", true /* show title */, IPageLayout.LEFT, 1.0f, editorArea);
>+	}
>+</pre>
>+
>+
>+Note that for the moment you need to specify "true" to show title, otherwise the viewer will not render correctly
>+(<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=235171">bug 235171</a>).
>+</li>
>+<li>
>+Add a org.eclipse.ui.navigator.viewer extension that has:
>+<ul>
>+<li>viewerContentBinding, point this to your View Id above (example.view)
>+<ul>
>+<li>includes of:
>+<ul>
>+<li>com.yourcompany.yourapp.yournav.*</li>
>+</ul>
>+</li>
>+</ul>
>+</li>
>+</ul>
>+
>+<pre>
>+
>+ &lt;extension
>+ point="org.eclipse.ui.navigator.viewer"&gt;
>+ &lt;viewerContentBinding 
>+ viewerId="example.view"&gt;
>+ &lt;includes&gt;
>+ 	 &lt;contentExtension pattern="com.yourcompany.yourapp.yournav.*" /&gt;		 	 
>+ &lt;/includes&gt;
>+ &lt;/viewerContentBinding&gt;
>+ &lt;/extension&gt;
>+</pre>
>+</li>
>+
>+<li>Add navigator content extensions as required:
>+</li>
>+
>+<li>If you need resources, add the following to your WorkbenchAdvisor
>+
>+<ol type="a">
>+<li>To get the resource workspace as input, override this method:
>+
>+<pre>
>+	public IAdaptable getDefaultPageInput() {
>+		IWorkspace workspace = ResourcesPlugin.getWorkspace();
>+		return workspace.getRoot();
>+	}
>+</pre>
>+</li>
>+<li>If you need resources, you need to have the workbench adapters correctly hooked up, so
>+add this code to the initialize() method:
>+
>+<pre>
>+	public void initialize(IWorkbenchConfigurer configurer) {
>+		IDE.registerAdapters();
>+	}
>+</pre>
>+
>+</li>
>+</ol>
>+</li>
>+</ol>
>+</BODY>
>+</HTML>
>Index: guide/cnf_steps_contents.htm
>===================================================================
>RCS file: guide/cnf_steps_contents.htm
>diff -N guide/cnf_steps_contents.htm
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ guide/cnf_steps_contents.htm	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,38 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<HTML>
>+<HEAD>
>+
>+<meta name="copyright"
>+	content="Copyright (c) Oakland Software and others 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+
>+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
>+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>+
>+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"
>+	TYPE="text/css">
>+<TITLE>Configuring the Common Navigator</TITLE>
>+</HEAD>
>+<BODY BGCOLOR="#ffffff">
>+
>+<h1>Procedures for Using the CNF</h1>
>+
>+The sections below define the set of steps for using the CNF 
>+in various scenarios.
>+Some of the sets of below have a plugin in the UI examples
>+that shows the end result.
>+
>+
>+
>+<ul>
>+<li><a href="cnf_steps_resources.htm">Using only Resources</a>
>+ (<code>org.eclipse.ui.examples.navigators.resources</code>)</li>
>+<li><a href="cnf_steps_rcp.htm">Using with an RCP Application</a></li>
>+<li><a href="cnf_steps_rn_migration.htm">Migrating from the ResourceNavigator</a></li>
>+<li><a href="cnf_steps_resources.htm">Using Resources Combined with Model Objects</a>
>+ (<code>org.eclipse.ui.examples.navigators.properties</code>)</li>
>+</ul>
>+
>+
>+
>+</BODY>
>+</HTML>
>Index: guide/cnf_steps_resources.htm
>===================================================================
>RCS file: guide/cnf_steps_resources.htm
>diff -N guide/cnf_steps_resources.htm
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ guide/cnf_steps_resources.htm	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,97 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<HTML>
>+<HEAD>
>+
>+<meta name="copyright"
>+	content="Copyright (c) Oakland Software and others 2008, 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+
>+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
>+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>+
>+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"
>+	TYPE="text/css">
>+<TITLE>Using the Common Navigator with Resources</TITLE>
>+
>+<link rel="stylesheet" type="text/css" HREF="../book.css">
>+</HEAD>
>+<BODY BGCOLOR="#ffffff">
>+<h1>Using the Common Navigator with Resources</h1>
>+
>+
>+To create a Common Navigator view that manipulates workspace resources
>+(in the IDE) use the steps below. These steps can also be applied to an RCP application, but 
>+you will also need to do the some additional <a href="cnf_steps_rcp.htm">work</a>. You don't need to
>+use any code at all to do this.
>+
>+
>+The example plugin <code>org.eclipse.ui.examples.navigators.resources</code> shows this.
>+
>+
>+<ol>
>+<li>
>+Add the following as dependent plug-ins:
>+<ol type="a">
>+<li>org.eclipse.ui.navigator</li>
>+<li>org.eclipse.ui.navigator.resources</li>
>+</ol>
>+</li>
>+<li>Add a View extension (org.eclipse.ui.views) which uses the class org.eclipse.ui.navigator.CommonNavigator.
>+<pre>
>+ &lt;extension
>+ point="org.eclipse.ui.views"&gt;
>+ &lt;view
>+ name="View"
>+ class="org.eclipse.ui.navigator.CommonNavigator"
>+ id="example.view"&gt;
>+ &lt;/view&gt;
>+ &lt;/extension&gt;
>+</pre>
>+</li>
>+
>+<li>
>+Add a org.eclipse.ui.navigator.viewer extension that has:
>+<ul>
>+<li>viewerActionBinding, point this to your View Id above (example.view)
>+<ul>
>+<li>includes of org.eclipse.ui.navigator.resources</li>
>+</ul>
>+</li>
>+<li>viewerContentBinding, point this to your View Id above (example.view)
>+<ul>
>+<li>includes of:
>+<ul>
>+<li>org.eclipse.ui.navigator.resources</li>
>+<li>org.eclipse.ui.navigator.resourceContent</li>
>+<li>org.eclipse.ui.navigator.resources.*</li>
>+</ul>
>+</li>
>+</ul>
>+</li>
>+</ul>
>+
>+<pre>
>+
>+ &lt;extension
>+ point="org.eclipse.ui.navigator.viewer"&gt;
>+ &lt;viewerActionBinding
>+ viewerId="example.view"&gt;
>+ &lt;includes&gt;
>+ &lt;actionExtension pattern="org.eclipse.ui.navigator.resources.*" /&gt;
>+ &lt;/includes&gt;
>+ &lt;/viewerActionBinding&gt;
>+ &lt;viewerContentBinding 
>+ viewerId="example.view"&gt;
>+ &lt;includes&gt;
>+ 	 &lt;contentExtension pattern="org.eclipse.ui.navigator.resourceContent" /&gt;		 	 
>+	 &lt;contentExtension pattern="org.eclipse.ui.navigator.resources.filters.*"/&gt;
>+ &lt;/includes&gt;
>+ &lt;/viewerContentBinding&gt;
>+ &lt;/extension&gt;
>+</pre>
>+</li>
>+
>+</ol>
>+</li>
>+</ol>
>+</BODY>
>+</HTML>
>Index: guide/cnf_steps_rn_migration.htm
>===================================================================
>RCS file: guide/cnf_steps_rn_migration.htm
>diff -N guide/cnf_steps_rn_migration.htm
>--- /dev/null	1 Jan 1970 00:00:00 -0000
>+++ guide/cnf_steps_rn_migration.htm	1 Jan 1970 00:00:00 -0000
>@@ -0,0 +1,97 @@
>+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
>+<HTML>
>+<HEAD>
>+
>+<meta name="copyright"
>+	content="Copyright (c) Oakland Software and others 2008. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page.">
>+
>+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
>+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
>+
>+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1"
>+	TYPE="text/css">
>+<TITLE>Migrating from the ResourceNavigator</TITLE>
>+
>+<link rel="stylesheet" type="text/css" HREF="../book.css">
>+</HEAD>
>+<BODY BGCOLOR="#ffffff">
>+<h1>Migrating from the ResourceNavigator</h1>
>+
>+
>+First follow the steps to add the Common Navigator for <a href="cnf_steps_resources.htm">resources</a>.
>+If your application is an RCP application, also do the <a href="cnf_steps_resources.htm">RCP steps</a>.
>+
>+
>+The following steps discuss the migration component for each part of the ResourceNavigator
>+
>+<ol>
>+<li>
>+<code>org.eclipse.ui.ide.resourceFilters</code>
>+
>+Add the corresponding 
>+<a href="../reference/extension-points/org_eclipse_ui_navigator_navigatorContent.html">org.eclipse.ui.navigator.navigatorContent/commonFilter</a>
>+extensions.
>+
>+</li>
>+
>+<li>
>+<code>FrameList</code> support <code>get/setFrameList()</code>
>+
>+The FrameList support is used for the Go Into functionality. Support for this 
>+is included in the ProjectExplorer subclass of CommonNavigator. You should subclass ProjectExplorer
>+instead of CommonNavigator. 
>+
>+</li>
>+
>+
>+<li>
>+
>+<code>ResourcePatternFilter</code> support <code>get/setPatternFilter()</code>
>+
>+Configure the ResourcePatternFilter using the 
>+<a href="../reference/extension-points/org_eclipse_ui_navigator_navigatorContent.html">org.eclipse.ui.navigator.navigatorContent/commonFilter</a>
>+extension. Then you can access the instance of the filter using the following code (where <code>yourViewer</code> is the instance
>+of the CommonViewer and <code>yourFilterId</code> is the string of the Id of your common filter configured above:
>+<pre>
>+INavigatorContentService contentService = yourViewer.getNavigatorContentService();
>+INavigatorFilterService filterService = contentService.getFilterService();
>+ICommonFilterDescriptor[] fds = filterService.getVisibleFilterDescriptors();
>+for (int i = i; i < fds.length; i++) {
>+	if (fds[i].getId().equals(yourFilterId))
>+		return filterService.getViewerFilter(filterDescriptor);
>+}
>+</pre>
>+
>+
>+Note:
>+(??? possibly don't deprecate ResourcePatternFilter, or move this into 
>+org.eclipse.ui.navigator.resources as it is; this class does not depend on ResourceNavigator.)
>+
>+</li>
>+
>+<li>
>+<code>IWorkingSet</code> support <code>get/setWorkingSet()</code>
>+
>+??? figure out the corresponding ProjectExplorer way to do this.
>+
>+</li>
>+
>+<li>
>+<code>ResourceSorter</code> support <code>get/setResourceSorter()</code>
>+
>+??? Similar to the filter service.
>+
>+</li>
>+
>+<li>
>+<code>ResourceComparator</code> support <code>get/setResourceComparator()</code>
>+
>+??? Have to use ResourceSorter instead for now as the CN does not directly support
>+ResourceComparators
>+
>+</li>
>+
>+</ol>
>+
>+</BODY>
>+</HTML>

Actions: View | Diff

Attachments on bug 270042: 129905