NetBeans Selection Management Tutorial I—Using a TopComponent's Lookup

Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under Projects, select NetBeans Platform Application:

Click Next.

In the Name and Location panel, type EventManager in Project Name. Change the Project Location to any directory on your computer:

Click Finish.

You now have a NetBeans Platform application project, which is the container for the modules that you will be creating throughout this tutorial:

Via the configuration files shown in the screenshot above, the NetBeans Platform application project provides a set of pre-defined modules, such as modules that give your application a window system and an action system. The configuration files also sets up the application to be built via the Ant build system. In the next steps, you will be adding three custom modules to the application. The first module will provide an API class, while the other two will share that API module between them. That will ensure that the other two modules do not depend on each other, making them loosely coupled. More on this will become clear as you work through this tutorial.

Choose File > New Project (Ctrl-Shift-N) again. Under Categories, select NetBeans Modules. Under Projects, select Module:

Click Next.

(Alternatively, expand the "EventManager" project node, right-click the "Modules" node, and then choose "Add New".)

In the Name and Location panel, type MyAPI in Project Name. Now look at the Project Location field and the Project Folder field. As you can see, the default in the wizard is to create the module within the directory where you just created the "EventManager" application, which means that the module's sources will be organized within the folder where the application is defined. That is the standard way to organize NetBeans Platform application sources.

Click Next.

In the Basic Module Configuration panel, set the following values:

• Code Name Base. The code name base is a string that uniquely identifies a module. By convention, the value of the code name base is the main package of the module. Therefore, if the main package of your module is going to be "org.me.foo", then that would normally also be the value of the code name base of the module. In this case, since the base package will be "org.myorg.myapi", set the code name base to org.myorg.myapi. That will be the string used to identify the module, so that that will also be the string used by other modules that will need to make use of code within this module.
• Module Display Name. Set the module display name to My API. That is the text you will see displayed for the module in the Projects window in the IDE.
• Localizing Bundle. Leave the location of the localizing bundle, so that localization keys/values will be stored in the main package, with the name org/myorg/myapi.
• Generate OSGi Bundle. Two module systems are supported by the NetBeans Platform, the NetBeans module system and the OSGi framework. Depending on your business requirements, select the module system of your choice. We will use the default module system in this tutorial, that is, the NetBeans module system.

The result should be as follows:

Click Finish.

You're going to create two more modules now—follow step 3, 4, and 5 above, twice, using the names "MyEditor" (code name base org.myorg.myeditor) and "MyViewer" (code name base org.myorg.myviewer).

At the end of this step, the structure of the application should be as follows:

The reason you are creating three modules in the application is that you are creating a modular application, where the viewer and editor modules will be loosely coupled from each other, only sharing the API module between them. The usefulness of this approach will become clearer as you continue with this tutorial.

Right click the org.myorg.myapi package and choose New > Java Class.

public final class Event {

   private final Date date = new Date();
   private static int count = 0;
   private final int index;

   public Event() {
      index = count++;
   }

   public Date getDate() {
      return date;
   }

   public int getIndex() {
      return index;
   }
   
   @Override
   public String toString() {
       return index + " - " + date;
   }
   
}
                    

In the API Versioning page in the Project Properties dialog box, check the checkbox for org.myorg.api in the Public Packages list, shown below:

Click OK. Now expand the Important Files node and open the Project Metadata file. On disk, this file is named project.xml. Inside this file, notice the following section, which was added when you clicked OK in the dialog above:

<public-packages>
    <package>org.myorg.myapi</package>
</public-packages>

When the module is compiled, the information above in the project.xml file is added to the module's manifest file.

In the Libraries page of the Project Properties dialog box of both My Editor and My Viewer, click the Add Dependency button. In the dialog box that pops up, type Event—there should be only one match, which is your API module. Select it and click OK to add the dependency. You should see the following:

Click OK. When you open the Project Metadata file in the Important Files node of the My Editor module and the My Viewer module, you should see that the section below has been added:

<module-dependencies>
    <dependency>
        <code-name-base>org.myorg.myapi</code-name-base>
        <build-prerequisite/>
        <compile-dependency/>
        <run-dependency>
            <specification-version>1.0</specification-version>
        </run-dependency>
    </dependency>
</module-dependencies>

Notice that the code name base of the MyAPI module is used to identify it here. When the module is compiled, the information above in the project.xml file is added to the module's manifest file.

On the "Basic Settings" page of the wizard, select explorer as the location in which to place your viewer component, and check the checkbox to cause the window to open on startup, as shown below:

Drag two JLabels to the form from the Palette (Ctrl-Shift-8), one below the other.

Change the text of the first as shown above, so that by default it displays "[nothing selected]".

public class MyViewerTopComponent extends TopComponent implements LookupListener {
                    

Put the caret in the signature line as shown below. A lightbulb glyph should appear in the editor margin. Press Alt-Enter, and then Enter again when the popup appears with the text "Implement All Abstract Methods". This will add the LookupListener method to your class:

You now have a class that implements LookupListener. Now it needs something to listen to. In your case, there is a convenient global Lookup object, which simply proxies the Lookup of whatever component has focus—it can be obtained from the call Utilities.actionsGlobalContext(). So rather than tracking what component has focus yourself, you can simply listen to this one global selection lookup, which will fire appropriate changes whenever focus changes.

Edit the source code of the MyViewerTopComponent so that its componentOpened, componentClosed, and resultChanged methods are as follows:

    private Lookup.Result<Event> result = null;

    @Override
    public void componentOpened() {
        result = Utilities.actionsGlobalContext().lookupResult(Event.class);
        result.addLookupListener (this);
    }
    
    @Override
    public void componentClosed() {
        result.removeLookupListener (this);
        result = null;
    }
    
    @Override
    public void resultChanged(LookupEvent lookupEvent) {
        Collection<? extends Event> allEvents = result.allInstances();
        if (!allEvents.isEmpty()) {
            Event event = allEvents.iterator().next();
            jLabel1.setText(Integer.toString(event.getIndex()));
            jLabel2.setText(event.getDate().toString());
        } else {
            jLabel1.setText("[no selection]");
            jLabel2.setText("");
        }
    }
                    

• componentOpened() is called whenever the component is made visible by the window system; componentClosed() is called whenever the user clicks the X button on its tab to close it. So whenever the component is showing, you want it to be tracking the selection—which is what the above code does.
• The resultChanged() method is your implementation of LookupListener. Whenever the selected Event changes, it will update the two JLabels you put on the form.

The required import statements for the MyViewerTopComponent are as follows:

import java.util.Collection;
import org.myorg.myapi.Event;
import org.netbeans.api.settings.ConvertAsProperties;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.util.*;
import org.openide.windows.TopComponent;

@TopComponent.Description(preferredID = "MyEditorTopComponent", 
persistenceType = TopComponent.PERSISTENCE_NEVER)
@TopComponent.Registration(mode = "explorer", openAtStartup = false)
@TopComponent.OpenActionRegistration(displayName = "#CTL_MyEditorAction")
@ActionID(category = "Window", id = "org.myorg.myviewer.MyEditorTopComponent")
@ActionReference(path = "Menu/Window")

public class MyEditor extends TopComponent {

CTL_MyEditorAction=Open Editor
                    

Event obj = new Event();
associateLookup (Lookups.singleton (obj));
jTextField1.setText ("Event #" + obj.getIndex());
jTextField2.setText ("Created: " + obj.getDate());
setDisplayName ("MyEditor " + obj.getIndex());

import org.myorg.myapi.Event;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.util.lookup.Lookups;
import org.openide.windows.TopComponent;

public class MyEditor extends TopComponent {

    private final InstanceContent content = new InstanceContent();

associateLookup (new AbstractLookup (content)); 

jButton1ActionPerformed (null);

private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {
    Event obj = new Event();
    jTextField1.setText ("Event #" + obj.getIndex());
    jTextField2.setText ("Created: " + obj.getDate());
    setDisplayName ("MyEditor " + obj.getIndex());
    content.set(Collections.singleton (obj), null);
}