| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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"> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> |
| <TITLE>org.eclipse.ui.views</TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <H3> |
| org.eclipse.ui.views</H3> |
| |
| <P >A view is a workbench part that can navigate a hierarchy of information or display properties for an |
| object. Only one instance of any given view |
| is open in a workbench page. When the user makes selections or other changes in a view, |
| those changes are immediately reflected in the workbench. Views are often provided to support a corresponding editor. |
| For example, an <b>outline</b> view shows a structured view of the information |
| in an editor. A <b>properties</b> view shows the properties of an object |
| that is currently being edited.</P> |
| |
| <P > |
| The extension point <b><a href="../reference/extension-points/org_eclipse_ui_views.html">org.eclipse.ui.views</a></b> |
| allows plug-ins to add views to the workbench. Plug-ins that contribute a view must register the view in their |
| <b> plugin.xml </b> file and provide configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.</P> |
| <P > |
| The interface for views is defined in <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, but plug-ins |
| can choose to extend the |
| <b><a href="../reference/api/org/eclipse/ui/part/ViewPart.html"> ViewPart</a></b> class rather than implement an |
| <b><a href="../reference/api/org/eclipse/ui/IViewPart.html"> IViewPart</a></b> from scratch.</P> |
| <P > |
| We implemented a minimal view extension in the hello world example. Now we'll look at one that is aware of other workbench views and responds to user navigation and selection |
| changes in the workbench. First, |
| let's take a look at the declaration of the extension in the <b>plugin.xml</b>.</P> |
| <pre><extension |
| point="org.eclipse.ui.views"> |
| <category |
| id="org.eclipse.ui.examples.readmetool" |
| name="%Views.category"> |
| </category> |
| <view |
| id="org.eclipse.ui.examples.readmetool.views.SectionsView" |
| name="%Views.ReadmeSections" |
| icon="icons/view16/sections.png" |
| category="org.eclipse.ui.examples.readmetool" |
| class="org.eclipse.ui.examples.readmetool.ReadmeSectionsView"> |
| </view> |
| </extension> |
| </pre> |
| <P > |
| This should look pretty familiar. We see that a new view, <b>ReadmeSectionsView</b>, is contributed to the workbench. The |
| <b>view id</b>, <b>name</b>, |
| and |
| <b> category</b> are specified as we've seen before. An <b> icon</b> is also provided |
| for the view, using a path relative to the plug-in's installation directory. </P> |
| <P > |
| Let's look at the <b>ReadmeSectionsView</b>. You can show any view in the |
| workbench by choosing |
| |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> |
| <b>Window > Show View > Other...</b></a> |
| |
| and selecting the view from the <b>Show View</b> list.</P> |
| <P > |
| When we show the <b>ReadmeSectionsView</b>, a view with a list in it pops up. |
| The list is empty unless we click on a file with an extension of <b>.readme</b>, in which case |
| the list is populated with sections from the readme file.</P> |
| |
| <img src="images/readmeview.png" alt="" border="0"> |
| <P > |
| How does the plug-in recognize the readme file and how did it know about selection changes? If we can track down |
| the answers to these questions, we are well on our way to understanding how to build integrated workbench plug-ins.</P> |
| <P > |
| We'll start with the familiar <b>createPartControl</b> |
| method. As we saw in the Hello World example, this is where the widgets |
| that represent a view are created. We'll ignore some of the code to get |
| started.</P> |
| <pre> |
| public void createPartControl(Composite parent) { |
| viewer = new ListViewer(parent); |
| ... |
| // add myself as a global selection listener |
| getSite().getPage().addSelectionListener(this); |
| |
| // prime the selection |
| selectionChanged(null, getSite().getPage().getSelection()); |
| } |
| </pre> |
| <P > |
| The view creates and stores a ListViewer and registers itself as a selection listener |
| on its page. It obtains the page from an |
| <b><a href="../reference/api/org/eclipse/ui/IViewSite.html">IViewSite</a></b>, which contains information about the view's context, such as its workbench window, |
| its containing page, its local services, and its plug-in. When we are notified of a selection change, what happens? |
| The following code is executed:</P> |
| <pre> |
| public void selectionChanged(IWorkbenchPart part, ISelection sel) { |
| //if the selection is a readme file, get its sections. |
| AdaptableList input = ReadmeModelFactory.getInstance().getSections(sel); |
| viewer.setInput(input); |
| } |
| </pre> |
| <P > |
| It looks like the <b> ReadmeModelFactory</b> class is responsible for turning the selection into readme |
| sections and these sections are input for |
| the viewer that we created in the <b>createPartControl</b> |
| method.</P> |
| <P > |
| But how did the viewer populate its list widgets? For now, let's assume that once the viewer was told its input element, it knew how to populate |
| its list widget with the information - it is a ListViewer, after all. If you must know right now what this viewer is all about, go to <a HREF="jface_viewers.htm" CLASS="XRef">Viewers</a>. </P> |
| <P > |
| We still do not know how readme files are detected or where the file's section |
| information comes from. A quick look at the |
| <b> ReadmeModelFactory</b> sheds some light.</P> |
| <pre> |
| public AdaptableList getSections(ISelection sel) { |
| // If sel is not a structured selection just return. |
| if (!(sel instanceof IStructuredSelection)) |
| return null; |
| IStructuredSelection structured = (IStructuredSelection)sel; |
| |
| //if the selection is a readme file, get its sections. |
| Object object = structured.getFirstElement(); |
| if (object instanceof IFile) { |
| IFile file = (IFile) object; |
| String extension = file.getFileExtension(); |
| if (extension != null && extension.equals(IReadmeConstants.EXTENSION)) { |
| return getSections(file); |
| } |
| } |
| |
| //the selected object is not a readme file |
| return null; |
| } |
| </pre> |
| <P >We check the selection to see if it is a structured (multiple) |
| selection. (The concept of a structured selection comes from JFace <a href="jface_viewers.htm">viewers</a>.) |
| For the first object in the selection, we check to see whether it is a file (<b><a href="../reference/api/org/eclipse/core/resources/IFile.html">IFile</a></b>) |
| resource. If it is, we check its extension to see if it matches the "<b>.readme</b>" |
| extension. Once we know we have a readme file, we can use other methods to |
| parse the sections. You can browse the rest of <b>ReadmeModelFactory</b>, |
| <b>MarkElement</b>, and <b> DefaultSectionsParser</b> for the |
| details about the file parsing. </P> |
| <P > |
| We've covered a lot of common workbench concepts by studying this extension. Now we'll move on to some other workbench extensions and examine how your plug-in can further contribute to the workbench UI. </P> |
| |
| |
| |
| |
| |
| </BODY> |
| </HTML> |
