1.using a topcomponents lookup

8/10/2019 1.Using a TopComponents Lookup

1/22

8/29/2014 NetBeans Selection Management Tutorial for NetBeans Platform

https://platform.netbeans.org/tutorials/nbm-selection-1.html 1/22

NetBeans IDE

NetBeans Platform

Plugins

Docs & Support

Community

Partners

Search

netbeans.org> projects > platform > Website

NetBeans Selection Management Tutorial IUsing a TopComponent'sLookupThis tutorial covers how to write components that provide a "selected object" and how to write components that

update themselves as the global selection changes.

Note: This document uses NetBeans Platform 8.0 and NetBeans IDE 8.0. If you are using an earlier version, seethe previous version of this document.

Contents

Introduction to Selection

Creating the NetBeans Platform Application Project

Creating an API and Setting Up Dependencies

Creating the Viewer Component

Creating the Editor Component

Running the Code

So, What's the Point?

Changing Selected Objects on the Fly

Providing More Than One Object

Next Steps

To follow this tutorial, you need the software and resources listed in the following table.

Software or Resource Version Required

NetBeans IDE version 8.0 or above

Java Developer Kit (JDK) version 7 or above

For troubleshooting purposes, you are welcome to download the completed tutorial source code.

Login | Join Now | Help

Jump to...

NavigationHome

My Page

Projects

People

ProjectFeatures

Mailing Lists

Issue Tracking

Bugzilla

Source Code

Repository

Platform content

Website

Website

Wiki
http://-/?-http://-/?-http://-/?-https://netbeans.org/peoplehttps://netbeans.org/community/partners/index.htmlhttps://netbeans.org/community/index.htmlhttps://netbeans.org/features/platform/index.htmlhttps://netbeans.org/features/index.htmlhttps://netbeans.org/http://platform.netbeans.org/https://netbeans.org/projects/platform/sources/platform-content/showhttps://netbeans.org/projects/platform/sourceshttp://netbeans.org/bugzilla/buglist.cgi?product=platform&order=Importance&limit=25https://netbeans.org/projects/platform/listshttps://netbeans.org/peoplehttps://netbeans.org/projectshttps://netbeans.org/mypagehttps://netbeans.org/https://netbeans.org/projects/help/pages/WebSite#WithNavigationhttps://netbeans.org/people/newhttps://netbeans.org/people/login?original_uri=https%3A%2F%2Fplatform.netbeans.org%2Ftutorials%2Fnbm-selection-1.htmlhttp://java.net/projects/nb-api-samples/sources/api-samples/show/versions/8.0/tutorials/selection-management/1-of-4/EventManagerhttp://java.sun.com/javase/downloads/index.jsphttps://netbeans.org/downloads/index.htmlhttp://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-http://-/?-https://platform.netbeans.org/tutorials/74/nbm-selection-1.htmlhttps://netbeans.org/projects/platform/contenthttps://netbeans.org/projects/platformhttps://netbeans.org/projectshttps://netbeans.org/https://netbeans.org/community/partners/index.htmlhttps://netbeans.org/community/index.htmlhttps://netbeans.org/kb/index.htmlhttp://plugins.netbeans.org/PluginPortal/https://netbeans.org/features/platform/index.htmlhttps://netbeans.org/features/index.htmlhttps://netbeans.org/


2/22



Introduction to Selection

"Selection" is an important concept for any non-trivial application. NetBeans has two basic concepts of selectionthe

contents of the focused TopComponent's Lookup, and the focused TopComponent's activated Node(s). Here you will

deal only with the Lookup portion of selectiondoing more advanced things will be covered in a later tutorial in this

four part series.

Selection is used to make possible such things as context sensitive actions (actions that are enabled or disabled

depending on what is displayed), and palette windows such as the Property Sheet or Navigator components in the

IDE, which each display some aspect of whatever is selected.

Basically, each TopComponent has a bag of objects that it can put things into, and which other code is able to query.

That bag of objects is its Lookupessentially a Map where the keys are class objects and the values are objects that

extend or implement the key-class. The thing that makes this approach tremendously useful is the ability to use this

mechanism to decouple the components that provide some object and the components that consume those objects

so they can be implemented in separate modules, or new editors for old objects can be provided and the rest of the

system will continue to work transparently.

Creating the NetBeans Platform Application Project

The loosely-coupled modular example used in this tutorial will contain three modules constituting a NetBeans Platform

application, as illustrated below:

Start by creating the NetBeans Platform application that will contain all three modules:

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

NetBeans Platform Application:

NetBeans Platform

Wiki

WikiHomePage

WikiHomePage

Project Links Screenshots

Customer

Testimonials

Quick Start

About thisProjectPlatform was

started in

November 2009, is

owned by Antonin

Nebuzelsky, andhas 142 members.

Join This Project

NetBeans.orgJoin

News

Releases &

Planning

Mailing Lists

Bugzilla

Contribute

Teams

Guidelines
https://netbeans.org/community/guidelines/https://netbeans.org/community/teams/https://netbeans.org/community/contribute/https://netbeans.org/community/issues.htmlhttps://netbeans.org/community/lists/https://netbeans.org/community/releases/https://netbeans.org/community/news/https://netbeans.org/people/newhttps://netbeans.org/projects/platform/watchhttps://netbeans.org/projects/platform/membershttps://netbeans.org/people/4-Antonin-Nebuzelskyhttps://netbeans.org/projects/platformhttp://platform.netbeans.org/tutorials/nbm-google.htmlhttp://platform.netbeans.org/testimonials.htmlhttp://platform.netbeans.org/screenshots.htmlhttps://netbeans.org/projects/platform/pages/Homehttps://netbeans.org/projects/platform/pages/Homehttp://wiki.netbeans.org/wiki/view/DevFaqWhatIsANodehttp://wiki.netbeans.org/wiki/view/DevFaqLookuphttp://wiki.netbeans.org/wiki/view/DevFaqWindowsTopComponent


3/22



Click Next.

2. In the Name and Location panel, type EventManager in Project Name. Change the Project Location to any

directory on your computer:

Click Finish.


4/22



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.

3. 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


5/22


6/22


7/22



other kind of data that is being modelled programmatically. For the purposes of this tutorial it will suffice to have a

simple object named "Event", representing a random event, possibly an event such as a calendar event or an event

within a programmatic sequence. An Event has an index, providing a unique identifier, and a date.

1. Right click the org.myorg.myapi package and choose New > Java Class. Name the class Event and click

Finish. Replace the default code with the following:

package org.myorg.myapi

import java.util.Date

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

}

}

This will be all of the code that this module contains. As you can see, each time a new instance of Event is

created, a counter is incrementedso there will be some unique identifier to each instance of Event.

2. The next step is to have your API module export the org.myorg.myapi package so other modules can see

the Event class in it. By default, all packages are hidden from all other modules in the application. Right click

the My API project and choose Properties. In the API Versioning page in the Project Properties dialog box,check the checkbox for org.myorg.myapi in the Public Packages list, as shown below:


8/22



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:

org.myorg.myapi

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

manifest file.

3. Now you need to set up some dependencies between your modules. The other two modules, My Editor and

My Viewer, will use the Event class, so each of them needs to say that they depend on the API module. For

each of these two modules in turn, right-click the project node and choose Properties. In the Libraries page of

the Project Properties dialog box of both My Editor and My Viewer, click the Add Dependency button. In thedialog box that pops up, type Eventthere should be only one match, which is your API module. Select it


9/22



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:

org.myorg.myapi

1.0

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. In the

Projects window, the new contract between the modules is represented as follows:


10/22



Creating the Viewer Component

Now you will create a singleton component that will track if there is an Event available in the global selection (i.e., if

the focused TopComponent has one in its Lookup). If there is one, it will display some data about it. One common use

case for this sort of thing is creating master/detail views.

Generating a Singleton TopComponentA "singleton component" is a component like the Projects window in the NetBeans IDE, or the Property Sheet or

the Navigatora component that there is only ever one of in the system. The Window wizard will automatically

generate all of the code needed to create such a singleton componentyou just have to use the form designer or

write code to provide the contents of your singleton component.

1. Right click the org.myorg.myviewer package and choose New > Other. In the resulting dialog, select

Module Development > Window, as shown below:


11/22



Click Next (or press Enter).

2. 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:


12/22



3. Click Next to continue to the "Name, Icon and Location" page of the wizard. Set MyViewer as the class

name prefix:


13/22



4. Click Finish and you should see the following:

5. You now have a skeleton TopComponenta singleton component called MyViewerTopComponent. Open

theMyViewerTopComponent

file and click its Source tab. Via the annotations that you can see at the top

of the Java source file, MyViewerTopComponent will be registered in the layer file of the MyViewer


14/22



module, together with an Action for opening the MyViewerTopComponent from the Window menu:

@TopComponent.Description(

preferredID = "MyViewerTopComponent",

persistenceType = TopComponent.PERSISTENCE_ALWAYS)

@TopComponent.Registration(

mode = "explorer",

openAtStartup = true)

@ActionID( category = "Window",

id = "org.myorg.myviewer.MyViewerTopComponent")

@ActionReference(

path = "Menu/Window"

/*, position = 333 */)

@TopComponent.OpenActionRegistration(

displayName = "#CTL_MyViewerAction",

preferredID = "MyViewerTopComponent")

Creating a Context Sensitive TopComponentOpen the MyViewerTopComponent file and click its Design tabthe "Matisse" GUI Builder (also known as the

"form editor") opens. You will add two labels to the component, which will display some information about the

selected Event if there is one.

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

Press F2 on the first label and then change the text as shown above, so that by default it displays "

[nothing selected]".

2. Click the Source button in the editor toolbar to switch to the code editor. Modify the signature of the

class, so that MyViewerTopComponent implements LookupListener:

public class MyViewerTopComponent extends TopComponent implements

LookupListener {

Right-click in the editor and choose Fix Imports, so that LookupListener is imported. Put the caret inthe signature line as shown below. A lightbulb glyph should appear in the editor margin. Press Alt-
http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.OpenActionRegistration.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionReference.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionID.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Registration.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Description.html


15/22


16/22



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 selectionwhich 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.Collectionimport 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

Creating the Editor Component

Now you need something to actually provide instances of Event, for this code to be of any use. Fortunately this is

quite simple.

You will create another TopComponent, this time, one that opens in the editor area and offers an instance of

Event from its Lookup. You could use the Window template again, but that template is designed for creating

singleton components, rather than components there can be many of. So you will simply create a TopComponent

subclass without the template, and an action which will open additional ones.

1. You will need to add four dependencies to the My Editor module for it to be able to find the classes you will

be using. Right click the My Editor project and choose Properties. On the Library page of the Project

Properties dialog box, click the Add Dependency button, and type TopComponent. The dialog should

automatically suggest setting a dependency on the Window System API. Do the same thing for Lookups

(Lookup API). Also set a dependency on the Utilities API, as well the UI Utilities API, which provide various

helpful supporting classes that are made available by the NetBeans Platform.

2. Right-click the org.myorg.myeditor package in the My Editor project, and choose New > JPanel Form.

3. Name it "MyEditor", and finish the wizard.

4. When the form editor opens, drop two JTextFields on the form, one above the other. On the property

sheet, set the Editable property (checkbox) to false for each one.

5. Click the Source button in the editor toolbar to switch to the code editor.

6. Change the signature of MyEditor to extends TopComponent instead of javax.swing.JPanel and

annotate the class to specify the location of the window and the menu item for opening it:


17/22



@TopComponent.Description(

preferredID = "MyEditorTopComponent",

persistenceType = TopComponent.PERSISTENCE_ALWAYS)

@TopComponent.Registration(

mode = "editor",

openAtStartup = true)

@ActionID(

category = "Window",

id = "org.myorg.myeditor.MyEditorTopComponent")@ActionReference(

path = "Menu/Window")

@TopComponent.OpenActionRegistration(

displayName = "#CTL_MyEditorAction")

@NbBundle.Messages({

"CTL_MyEditorAction=MyEditor"

})

public class MyEditor extends TopComponent {

7. Add the following code to the constructor of MyEditor, after the initComponents() statement:

Event obj = new Event()

associateLookup(Lookups.singleton(obj))

jTextField1.setText ("Event #" + obj.getIndex())

jTextField2.setText ("Created: " + obj.getDate())

setDisplayName ("MyEditor " + obj.getIndex())

8. Right-click in the editor and choose Fix Imports, which should result in the following import section at the

top of your class:

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

The line associateLookup(Lookups.singleton(obj)) will create a Lookup that contains only one objectthe

new instance of Eventand assign that Lookup to be what is returned by MyEditor.getLookup(). While this is an

artificial example, you can imagine how Event might represent a file, an entity in a database, or anything else you

might want to edit or view. Probably you can also imagine one component that allows you to select or edit multipleunique instances of Eventthat will be the subject of the next tutorial.
http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/NbBundle.Messages.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.OpenActionRegistration.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionReference.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionID.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Registration.htmlhttp://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Description.html


18/22



To make your editor component at least somewhat interesting (though it doesn't actually edit anything), you set the

text fields' values to values from the Event, so you have something to display.

Running the Code

Now you're ready to run the tutorial. Simply right click EventManager, the application which contains your three

modules, and choose Run from the popup menu. When the IDE opens, simply choose Window > Open Editorinvoke

your action. Do this a couple of times, so that there are several of your editor components open. Your singleton

MyViewer window should also be open. Notice how the MyViewer window's contents change as you click different

tabs, as shown here:

If you click in the Viewer window, notice that the text changes to "[No Selection]", as shown below:


19/22



Note: If you do not see the MyViewer window, you probably did not check the checkbox in the wizard to open it

on system startsimply go to the Window menu and choose MyViewer to display it.

So, What's the Point?

You might be wondering what the point of this exercise isyou've just shown that you can handle selectionbig deal!

The key to the importance of this is the way the code is split into three modulesthe My Viewer module knows

nothing about the My Editor moduleeither one can run by itself. They only share a common dependency on My API.

That's importantit means two things: 1. My Viewer and My Editor can be developed and shipped independently, and

2. Any module that wants to provide a different sort of editor than My Editor can do so, and the viewer component will

work perfectly with it, as long as the replacement editor offers an instance of Event from its Lookup.

To really picture the value of this, imagine Event were something much more complex imagine that MyEditor is an

image editor, and Event represents an image being edited. The thing that's powerful here is that you could replaceMyEditor with, say, an SVG vector-based editor, and the viewer component (presumably showing attributes of the

currently edited image) will work transparently with that new editor. It is this model of doing things that is the reason

you can add new tools into the NetBeans IDE that work against Java files, and they will work in different versions of

NetBeans, and that you can have an alternate editor (such as the form editor) for Java files and all the components

and actions that work against Java files still work when the form editor is used.

This is very much the way NetBeans works with Java and other source filesin their case, the thing that is available

from the editor's Lookup is a DataObject, and components like Navigator and the Property Sheet are simply

watching what object is being made available by the focused TopComponent.

Another valuable thing about this approach is that often people are migrating existing applications to the NetBeans

Platform. The object that is part of the data model, in that case, is probably existing, working code that should not bechanged in order to integrate it into NetBeans. By keeping the data model's API in a separate module, the NetBeans
http://wiki.netbeans.org/wiki/view/DevFaqDataObject


20/22



integration can be kept separate from the core business logic.

Changing Selected Objects on the Fly

To make it really evident how powerful this approach can be, you'll take one more step, and add a button to your

editor component that lets it replace the Event it has with a new one on the fly.

1. Open MyEditor in the form editor (click the Design toolbar button in the editor toolbar), and drag a

JButton to it.

2. Set the text property of the JButton to "Replace".

3. Right click the JButton and choose Events > Action > actionPerformed. This will cause the code editor to

open with the caret in an event handler method.

4. At the head of the class definition, you will add one final field:

public class MyEditor extends TopComponent {

private final InstanceContent content = new InstanceContent()

InstanceContent is a class which allows us to modify the content of a Lookup (specifically an instance of

AbstractLookup) on the fly.

5. Copy all of the lines you added earlier to the constructor to the clipboard, and delete them from the

constructor, except for the line beginning "associateLookup...". That line of the constructor should be

changed as follows:

associateLookup (new AbstractLookup (content))

6. You will be using the lines that you put on the clipboard in the action handler for the JButtonso you should

run this code once when you first initialize the component. Add the following line to the constructor, after the

line above:

jButton1ActionPerformed (null)

7. Modify the event handler method so it appears as follows, pasting from the clipboard and adding the line at

the end:

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())
http://bits.netbeans.org/dev/javadoc/org-openide-util-lookup/org/openide/util/lookup/InstanceContent.html


21/22



content.set(Collections.singleton (obj), null)

}

8. Right-click in the editor and choose Fix Imports.

You're now ready to run the Event Manager again. Right click EventManager again and choose Run. Notice how, now,

when you click the Replace button, all of the components update, including the instance of MyViewereverything.

Providing More Than One Object

This is all well and good for decoupling, but isn't providing this one object from your component a bit like having a

Map that only contains one key and one value? The answer is, yes, it is like that. Where this technique becomes even

more powerful is when you provide multiple objects from multiple APIs.

As an example, it is very common in NetBeans to provide context sensitive actions. A case in point is the built-in

SaveAction that is part of NetBeans' Actions API. What this action actually does is, it simply listens for the presence

of something called SaveCookie on the global contextthe same way your viewer window listens for Event. If a

SaveCookie appears (editors typically add one to their Lookup when the content of the file is modified but not yet

saved), the action becomes enabled, so the Save toolbar button and menu items become enabled. When the Save

action is invoked, it calls SaveCookie.save(), which in turn causes the SaveCookie to disappear, so the Save

action then becomes disabled until a new one appears.

So the pattern in practice is to provide more than just a single object from your component's Lookupdifferent

auxilliary components and different actions will be interested in different aspects of the object being edited. These

aspects can be cleanly separated into interfaces which those auxilliary components and actions can depend on and

listen for.


22/22



Send Us Your FeedbackNext Steps

By now you may have noticed that some components have more granular selection logic,

and even involve multiple selection. In the next tutorial you will cover how to use the Nodes API to handle that.

SiteMap

About Us

Contact

Legal & Licences

By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20140718.4a68f04). 2014, Oracle Corporation and/or itsaffiliates. Sponsored by
https://netbeans.org/projects/help/pages/ReleaseNoteshttps://platform.netbeans.org/about/legal/terms-of-use.htmlhttps://netbeans.org/about/legal/index.htmlhttps://netbeans.org/about/contact.htmlhttps://netbeans.org/about/index.htmlhttps://netbeans.org/sitemaps/www_map.htmlhttps://netbeans.org/download/dev/javadoc/org-openide-nodes/overview-summary.htmlhttps://platform.netbeans.org/tutorials/nbm-selection-2.htmlhttps://twitter.com/netbeanshttps://plus.google.com/105597468329838196909/http://www.youtube.com/user/netbeansvideoshttp://www.facebook.com/NetBeanshttps://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Selection%208.0%20Tutorial%20Part%201%20

1.using a topcomponents lookup

Documents