bundles/org.eclipse.platform.doc.isv/guide/firstplugin_minimal.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
 <HEAD>
 <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>
 A minimal plug-in
 </TITLE>


 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <H2>
 A minimal plug-in</H2>
 <P >
 We all know what &quot;Hello World&quot; looks like in plain old Java without using any user interface or other framework.</P>
 <font color='#4444CC'><pre>
    public class HelloWorld {
       public static void main(String[] args) {
          System.out.println(&quot;Hello World&quot;);
       }
    }
 </pre></font>
 <P >
 What happens to this old standard in the context of the Eclipse platform?  Instead of thinking of Hello World as a self-contained program, we recast it as an extension of the platform. Since we want to say hello to the world, we need to figure out how to extend the workbench to include our greeting.</P>
 <P >
 When we get deeper into the platform user interface components, we'll do an exhaustive review of the ways that you can extend and customize the workbench
 UI. For now, let's start with one of the simplest workbench extensions - a view.&nbsp;</P>

 <p>You can think of the workbench window as a frame that presents various visual
 parts. These parts fall into two major categories: views and editors.&nbsp; We
 will look at editors later.&nbsp; <b>Views</b>
 provide information about some object that the user is working with in the
 workbench. Views often change their content as the user selects different
 objects in the workbench.</p>

 <H3>
 Hello world view</H3>
 <P >
 For our hello world plug-in, we will implement our own view to greet the user with &quot;Hello World.&quot;</P>
 <P >
 The package <b><a href="../reference/api/org/eclipse/ui/package-summary.html"> org.eclipse.ui</a></b>
 and its sub packages contain the public interfaces that define the workbench
 user interface (UI) API. Many of these interfaces have
 default implementation classes that you can extend to provide simple modifications to the system. In our hello world example, we will extend a workbench view to provide a label that says hello.</P>
 <P >
 The interface of interest is <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, which defines the methods that must be implemented to contribute a view to the workbench. The class
 <b><a href="../reference/api/org/eclipse/ui/part/ViewPart.html">ViewPart</a></b> provides a default implementation of this interface. In a nutshell, a view part is responsible for creating the widgets needed to show the view.</P>
 <P > The standard views in the workbench often display some information about
   an object that the user has selected or is navigating. Views update their contents
   based on actions that occur in the workbench. In our case, we are just saying
   hello, so our view is quite simple.</P>
 <h4 >Using the tools to write our plug-in</h4>
 <P >You can use any Java IDE you wish to build Eclipse plug-ins, but we'll walk
   through the steps for building our plug-in with the Eclipse Java IDE.&nbsp;
   If you are not already familiar with the Eclipse workbench and the Java IDE,
   consult the Java Development User Guide for further explanations of the steps
   we are taking.&nbsp; For now we are focusing on the code, not the tool.&nbsp;
   However, there are some IDE logistics for getting started.</P>
 <h4 >Setting up your environment</h4>
 <p >If you are starting with a clean environment, you will need to ensure that
   your code has access to the plug-ins <b><a href="../reference/api/org/eclipse/ui/package-summary.html">
   org.eclipse.ui</a></b>. Import this plug-in and any plug-ins it requires into
   your run-time workbench instance by performing the steps below. If you already
   have these plug-ins in your workbench instance, proceed to the section &quot;Creating
   your plug-in project&quot;.</p>
 <ol>
   <li>From the resource perspective, use <strong>File &gt; Import... &gt; External
     Plug-ins and Fragments</strong>.</li>
   <li>Continue clicking on the <strong>Next &gt;</strong> buttons until you get
     to the screen called <strong>Selection</strong>. This screen will contain
     a list of all of the plug-ins in your host workbench instance.</li>
   <li>Select org.eclipse.ui and then click the button <strong>Add Required Plug-ins</strong>.</li>
   <li>Click on the <strong>Finish</strong> button. Your Navigator view should
     contain org.eclipse.ui and all of the plug-ins it requires (including org.eclipse.swt).</li>
 </ol>
 <p>For a complete discussion of setting up host and run-time workbench instances
   consult the PDE Guide.</p>
 <h4>Creating your plug-in project</h4>
 <ol>
   <li>You will need to create a project to do your work.&nbsp; The simplest way
     is to open the <b>New Project...</b> wizard (<strong>File &gt; New &gt; Project...</strong>)
     and choose <b>Plug-in Project </b>from the <b>Plug-in Development</b> category.&nbsp;
     This will set up your project for writing Java code and give you a default
     plug-in manifest file (explained in a moment.)&nbsp; Use <b>org.eclipse.examples.helloworld</b>
     as the name for your project. By default, the wizard sets <strong>org.eclipse.examples.helloworld</strong>
     as the id as well.&nbsp; The wizard gives you the option of generating code
     for different kinds of plug-ins, but we want to keep this simple.&nbsp; For
     now, be sure to choose <b>Create a blank plug-in project </b>on the <strong>Plug-in
     Code Generators</strong> page.</li>
   <li>When asked if you would like to switch to the Plug-in Development perspective,
     answer <strong>Yes</strong>.</li>
   <li>Create a package <b>org.eclipse.examples.helloworld</b> underneath the <b>src</b>
     directory for the project. To do this, double click on the project <strong>org.eclipse.examples.helloworld</strong>
     in the Package Explorer view. This expands the project and shows you the <strong>src</strong>
     directory. Right click on the <strong>src</strong> directory to get the context
     menu. Use <strong>New &gt; Package</strong> to create a new package and give
     it the name <b>org.eclipse.examples.helloworld</b></li>
   <li>Create a new class called <b>HelloWorldView</b> in this package. Right click
     on the package you just created in the previous step to get the context menu.
     Use <strong>New &gt; Class</strong> to create your new class with the name
     <b>HelloWorldView</b>.</li>
 </ol>
 <h4>Writing the code</h4>
 <P >Now we're ready to study some code.&nbsp; Here is everything you need in
 your <b>HelloWorldView</b>.&nbsp; (You can copy the contents below into the
 class you created.)&nbsp;</P>
 <font color='#4444CC'><pre>
    package org.eclipse.examples.helloworld;

    import org.eclipse.swt.widgets.Composite;
    import org.eclipse.swt.widgets.Label;
    import org.eclipse.swt.SWT;
    import org.eclipse.ui.part.ViewPart;

    public class HelloWorldView extends ViewPart {
       Label label;
       public HelloWorldView() {
       }
       public void createPartControl(Composite parent) {
          label = new Label(parent, SWT.WRAP);
          label.setText(&quot;Hello World&quot;);
       }
       public void setFocus() {
          // set focus to my widget.  For a label, this doesn't
          // make much sense, but for more complex sets of widgets
          // you would decide which one gets the focus.
       }
    }
 </pre></font>
 <P >
 The view part creates the widgets that will represent it in the <b> createPartControl</b> method. In this example, we create an SWT label and set the &quot;Hello World&quot; text into it.&nbsp;</P>
 <P >
 This is all we need!&nbsp; We can compile our new class, but we better make sure
 that our .classpath is set up properly so that we can compile the
 code.&nbsp;&nbsp;</P>

 <ol>
   <li>Select the <b>org.eclipse.examples.helloWorld</b> project and open the <b>Properties</b>
     dialog (right click on the project <b>org.eclipse.examples.helloWorld</b>
     <strong>&gt; Properties</strong>).</li>
   <li>In the <b>Java Build Path</b> properties, select the <b>Projects</b> tab,
     and check the projects&nbsp; <b>org.eclipse.ui</b> and <b>org.eclipse.swt</b>.
     These are the projects that contain the classes we imported.</li>
   <li><b>Rebuild</b> the project.&nbsp;</li>
 </ol>
 <P >
 Okay, so we've compiled the view.&nbsp; Our new view is supposed to look something like this:</P>

 <p>

 <img src="images/hello.gif" alt="Simple view that says Hello World" border="0" width="377" height="120">
 </p>
 <P >
 How do we run the code and add this view to the workbench?</P>


 <H3>
 The hello world plug-in</H3>
 <P >
 We need to inform the platform that we want to contribute our view. This is done by extending the
 <b><a href="../reference/extension-points/org_eclipse_ui_views.html"> org.eclipse.ui.views</a></b> extension point. We register our extension by providing a manifest file,<b>
 plugin.xml</b>, which describes our plug-in, including where its code is located, and the extension
 we are adding.</P>
 <P >
 (If you are still following along, you can copy this information into the <b>plugin.xml
 </b>that was generated when you created the project.)</P>
 <font color='#4444CC'><pre>
    &lt;?xml version=&quot;1.0&quot; ?&gt;
    &lt;plugin
       name=&quot;Hello World Example&quot;
       id=&quot;org.eclipse.examples.helloworld&quot;
       version=&quot;1.0&quot;&gt;
       &lt;requires&gt;
          &lt;import plugin=&quot;org.eclipse.ui&quot; /&gt;
       &lt;/requires&gt;
       &lt;runtime&gt;
          &lt;library name=&quot;helloworld.jar&quot; /&gt;
       &lt;/runtime&gt;
       &lt;extension point=&quot;org.eclipse.ui.views&quot;&gt;
          &lt;category
             id=&quot;org.eclipse.examples.helloworld.hello&quot;
             name=&quot;Hello&quot; /&gt;
          &lt;view
             id=&quot;org.eclipse.examples.helloworld.helloworldview&quot;
             name=&quot;Hello Greetings&quot;
             category=&quot;org.eclipse.examples.helloworld.hello&quot;
             class=&quot;org.eclipse.examples.helloworld.HelloWorldView&quot; /&gt;
       &lt;/extension&gt;
    &lt;/plugin&gt;
 </pre></font>
 <P >
 In this file, we define the <b>name</b>, <b>id</b>, and <b>version</b> for our plug-in. </P>
 <P >
 We also list our required plug-ins. Since we use workbench and SWT API in our
 plug-in, we must list
 <b>org.eclipse.ui</b>. We must also describe where our executable code is located.
 We intend to package the code in
 <b>helloworld.jar</b>, so we register that as our <b>library</b> name.</P>
 <P >
 Finally, we declare what extension point our plug-in is contributing. The <b><a href="../reference/extension-points/org_eclipse_ui_views.html"> org.eclipse.ui.views</a></b> extension has several different configuration parameters.
 We first declare a <b> category</b> for our view extension. Categories can be used to group related views together in the workbench
 <b> Show View</b> dialog. We define our own category, &quot;Hello,&quot; so that it will display in its own group.&nbsp;
 We declare a unique <b> id</b> for our view and specify the name of the
 <b> class</b> that provides the implementation of the view. We also specify a
 <b> name</b> for the view, &quot;Hello Greetings&quot; which will be shown in the Show View dialog and in our view's title bar.</P>

 <h4 >
 <a name="firstplugin_minimal_pluginid">Plug-in ids</a></h4>
 <P>
 There are many ids used in a plug-in manifest file. Individual extension points often define configuration parameters that require ids (such as the category id used above for the views extension point). We also define a plug-in id. In general, you should use Java package name prefixes for all of your ids in order to ensure uniqueness among all the
 installed plug-ins.&nbsp;</P>

 <P>
  The specific name that you use after the prefix is completely up to you.
 However, if your plug-in id prefix is exactly the same name as one of your packages, you
 should avoid using class names from that package.&nbsp;&nbsp; Otherwise it will become difficult to tell whether you are looking at an id name or a class name.&nbsp;</P>

 <P>
  You should also avoid using the same id for different extension configuration parameters.
 In the above manifest, we have used a common id prefix (<b>org.eclipse.examples.helloworld</b>)
 but all of our ids are unique.&nbsp; This naming approach helps us to read the
 file and see which ids are related.&nbsp; </P>

 <h4>
  What next? </h4>

 <P>
  At this point, we have implemented a view and declared our contribution in our
  plug-in manifest.&nbsp; Now we need to install our plug-in into the platform so
  that we can run it. </P>

 <p><a href="../hglegal.htm"><img border="0" src="../ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="324" height="14"></a></p>

 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
	<HEAD>
	<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>
	A minimal plug-in
	</TITLE>


	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<H2>
	A minimal plug-in</H2>
	<P >
	We all know what "Hello World" looks like in plain old Java without using any user interface or other framework.</P>
	<font color='#4444CC'><pre>
	public class HelloWorld {
	public static void main(String[] args) {
	System.out.println("Hello World");
	}
	}
	</pre></font>
	<P >
	What happens to this old standard in the context of the Eclipse platform? Instead of thinking of Hello World as a self-contained program, we recast it as an extension of the platform. Since we want to say hello to the world, we need to figure out how to extend the workbench to include our greeting.</P>
	<P >
	When we get deeper into the platform user interface components, we'll do an exhaustive review of the ways that you can extend and customize the workbench
	UI. For now, let's start with one of the simplest workbench extensions - a view. </P>

	<p>You can think of the workbench window as a frame that presents various visual
	parts. These parts fall into two major categories: views and editors.  We
	will look at editors later.  <b>Views</b>
	provide information about some object that the user is working with in the
	workbench. Views often change their content as the user selects different
	objects in the workbench.</p>

	<H3>
	Hello world view</H3>
	<P >
	For our hello world plug-in, we will implement our own view to greet the user with "Hello World."</P>
	<P >
	The package <b><a href="../reference/api/org/eclipse/ui/package-summary.html"> org.eclipse.ui</a></b>
	and its sub packages contain the public interfaces that define the workbench
	user interface (UI) API. Many of these interfaces have
	default implementation classes that you can extend to provide simple modifications to the system. In our hello world example, we will extend a workbench view to provide a label that says hello.</P>
	<P >
	The interface of interest is <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, which defines the methods that must be implemented to contribute a view to the workbench. The class
	<b><a href="../reference/api/org/eclipse/ui/part/ViewPart.html">ViewPart</a></b> provides a default implementation of this interface. In a nutshell, a view part is responsible for creating the widgets needed to show the view.</P>
	<P > The standard views in the workbench often display some information about
	an object that the user has selected or is navigating. Views update their contents
	based on actions that occur in the workbench. In our case, we are just saying
	hello, so our view is quite simple.</P>
	<h4 >Using the tools to write our plug-in</h4>
	<P >You can use any Java IDE you wish to build Eclipse plug-ins, but we'll walk
	through the steps for building our plug-in with the Eclipse Java IDE.
	If you are not already familiar with the Eclipse workbench and the Java IDE,
	consult the Java Development User Guide for further explanations of the steps
	we are taking.  For now we are focusing on the code, not the tool.
	However, there are some IDE logistics for getting started.</P>
	<h4 >Setting up your environment</h4>
	<p >If you are starting with a clean environment, you will need to ensure that
	your code has access to the plug-ins <b><a href="../reference/api/org/eclipse/ui/package-summary.html">
	org.eclipse.ui</a></b>. Import this plug-in and any plug-ins it requires into
	your run-time workbench instance by performing the steps below. If you already
	have these plug-ins in your workbench instance, proceed to the section "Creating
	your plug-in project".</p>
	<ol>
	<li>From the resource perspective, use <strong>File > Import... > External
	Plug-ins and Fragments</strong>.</li>
	<li>Continue clicking on the <strong>Next ></strong> buttons until you get
	to the screen called <strong>Selection</strong>. This screen will contain
	a list of all of the plug-ins in your host workbench instance.</li>
	<li>Select org.eclipse.ui and then click the button <strong>Add Required Plug-ins</strong>.</li>
	<li>Click on the <strong>Finish</strong> button. Your Navigator view should
	contain org.eclipse.ui and all of the plug-ins it requires (including org.eclipse.swt).</li>
	</ol>
	<p>For a complete discussion of setting up host and run-time workbench instances
	consult the PDE Guide.</p>
	<h4>Creating your plug-in project</h4>
	<ol>
	<li>You will need to create a project to do your work.  The simplest way
	is to open the <b>New Project...</b> wizard (<strong>File > New > Project...</strong>)
	and choose <b>Plug-in Project </b>from the <b>Plug-in Development</b> category.
	This will set up your project for writing Java code and give you a default
	plug-in manifest file (explained in a moment.)  Use <b>org.eclipse.examples.helloworld</b>
	as the name for your project. By default, the wizard sets <strong>org.eclipse.examples.helloworld</strong>
	as the id as well.  The wizard gives you the option of generating code
	for different kinds of plug-ins, but we want to keep this simple.  For
	now, be sure to choose <b>Create a blank plug-in project </b>on the <strong>Plug-in
	Code Generators</strong> page.</li>
	<li>When asked if you would like to switch to the Plug-in Development perspective,
	answer <strong>Yes</strong>.</li>
	<li>Create a package <b>org.eclipse.examples.helloworld</b> underneath the <b>src</b>
	directory for the project. To do this, double click on the project <strong>org.eclipse.examples.helloworld</strong>
	in the Package Explorer view. This expands the project and shows you the <strong>src</strong>
	directory. Right click on the <strong>src</strong> directory to get the context
	menu. Use <strong>New > Package</strong> to create a new package and give
	it the name <b>org.eclipse.examples.helloworld</b></li>
	<li>Create a new class called <b>HelloWorldView</b> in this package. Right click
	on the package you just created in the previous step to get the context menu.
	Use <strong>New > Class</strong> to create your new class with the name
	<b>HelloWorldView</b>.</li>
	</ol>
	<h4>Writing the code</h4>
	<P >Now we're ready to study some code.  Here is everything you need in
	your <b>HelloWorldView</b>.  (You can copy the contents below into the
	class you created.) </P>
	<font color='#4444CC'><pre>
	package org.eclipse.examples.helloworld;

	import org.eclipse.swt.widgets.Composite;
	import org.eclipse.swt.widgets.Label;
	import org.eclipse.swt.SWT;
	import org.eclipse.ui.part.ViewPart;

	public class HelloWorldView extends ViewPart {
	Label label;
	public HelloWorldView() {
	}
	public void createPartControl(Composite parent) {
	label = new Label(parent, SWT.WRAP);
	label.setText("Hello World");
	}
	public void setFocus() {
	// set focus to my widget. For a label, this doesn't
	// make much sense, but for more complex sets of widgets
	// you would decide which one gets the focus.
	}
	}
	</pre></font>
	<P >
	The view part creates the widgets that will represent it in the <b> createPartControl</b> method. In this example, we create an SWT label and set the "Hello World" text into it. </P>
	<P >
	This is all we need!  We can compile our new class, but we better make sure
	that our .classpath is set up properly so that we can compile the
	code.  </P>

	<ol>
	<li>Select the <b>org.eclipse.examples.helloWorld</b> project and open the <b>Properties</b>
	dialog (right click on the project <b>org.eclipse.examples.helloWorld</b>
	<strong>> Properties</strong>).</li>
	<li>In the <b>Java Build Path</b> properties, select the <b>Projects</b> tab,
	and check the projects  <b>org.eclipse.ui</b> and <b>org.eclipse.swt</b>.
	These are the projects that contain the classes we imported.</li>
	<li><b>Rebuild</b> the project. </li>
	</ol>
	<P >
	Okay, so we've compiled the view.  Our new view is supposed to look something like this:</P>

	<p>

	<img src="images/hello.gif" alt="Simple view that says Hello World" border="0" width="377" height="120">
	</p>
	<P >
	How do we run the code and add this view to the workbench?</P>



	<H3>
	The hello world plug-in</H3>
	<P >
	We need to inform the platform that we want to contribute our view. This is done by extending the
	<b><a href="../reference/extension-points/org_eclipse_ui_views.html"> org.eclipse.ui.views</a></b> extension point. We register our extension by providing a manifest file,<b>
	plugin.xml</b>, which describes our plug-in, including where its code is located, and the extension
	we are adding.</P>
	<P >
	(If you are still following along, you can copy this information into the <b>plugin.xml
	</b>that was generated when you created the project.)</P>
	<font color='#4444CC'><pre>
	<?xml version="1.0" ?>
	<plugin
	name="Hello World Example"
	id="org.eclipse.examples.helloworld"
	version="1.0">
	<requires>
	<import plugin="org.eclipse.ui" />
	</requires>
	<runtime>
	<library name="helloworld.jar" />
	</runtime>
	<extension point="org.eclipse.ui.views">
	<category
	id="org.eclipse.examples.helloworld.hello"
	name="Hello" />
	<view
	id="org.eclipse.examples.helloworld.helloworldview"
	name="Hello Greetings"
	category="org.eclipse.examples.helloworld.hello"
	class="org.eclipse.examples.helloworld.HelloWorldView" />
	</extension>
	</plugin>
	</pre></font>
	<P >
	In this file, we define the <b>name</b>, <b>id</b>, and <b>version</b> for our plug-in. </P>
	<P >
	We also list our required plug-ins. Since we use workbench and SWT API in our
	plug-in, we must list
	<b>org.eclipse.ui</b>. We must also describe where our executable code is located.
	We intend to package the code in
	<b>helloworld.jar</b>, so we register that as our <b>library</b> name.</P>
	<P >
	Finally, we declare what extension point our plug-in is contributing. The <b><a href="../reference/extension-points/org_eclipse_ui_views.html"> org.eclipse.ui.views</a></b> extension has several different configuration parameters.
	We first declare a <b> category</b> for our view extension. Categories can be used to group related views together in the workbench
	<b> Show View</b> dialog. We define our own category, "Hello," so that it will display in its own group.
	We declare a unique <b> id</b> for our view and specify the name of the
	<b> class</b> that provides the implementation of the view. We also specify a
	<b> name</b> for the view, "Hello Greetings" which will be shown in the Show View dialog and in our view's title bar.</P>

	<h4 >
	<a name="firstplugin_minimal_pluginid">Plug-in ids</a></h4>
	<P>
	There are many ids used in a plug-in manifest file. Individual extension points often define configuration parameters that require ids (such as the category id used above for the views extension point). We also define a plug-in id. In general, you should use Java package name prefixes for all of your ids in order to ensure uniqueness among all the
	installed plug-ins. </P>

	<P>
	The specific name that you use after the prefix is completely up to you.
	However, if your plug-in id prefix is exactly the same name as one of your packages, you
	should avoid using class names from that package.   Otherwise it will become difficult to tell whether you are looking at an id name or a class name. </P>

	<P>
	You should also avoid using the same id for different extension configuration parameters.
	In the above manifest, we have used a common id prefix (<b>org.eclipse.examples.helloworld</b>)
	but all of our ids are unique.  This naming approach helps us to read the
	file and see which ids are related.  </P>

	<h4>
	What next? </h4>

	<P>
	At this point, we have implemented a view and declared our contribution in our
	plug-in manifest.  Now we need to install our plug-in into the platform so
	that we can run it. </P>

	<p><a href="../hglegal.htm"><img border="0" src="../ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="324" height="14"></a></p>

	</BODY>
	</HTML>