NetBeans Nodes, Explorer Manager, and Component Palette Tutorial

Setting Up an Explorer Manager

An Explorer Manager is the NetBeans API class that manages a view. For example, it notifies PropertyChangeListeners about changes to the nodes in the view. It also controls the root node in a view. For example, when you want to define a root node, you need to use the Explorer Manager's setRootContext() method. To provide an Explorer Manager in a TopComponent, you must implement ExplorerManager.Provider, as shown in this subsection.

1. Open the MyFirstTopComponent.java in the Source view and add implements ExplorerManager.Provider to the signature at the top of the class.

2. Next, instantiate the ExplorerManager as a transient object:

   private transient ExplorerManager explorerManager = new ExplorerManager();

3. Place the cursor in the signature. A lightbulb will prompt you to let the IDE insert an import statement and implement the abstract methods. Follow its advice, by clicking on the suggestion, and then fill out the generated getExplorerManager() as follows:

   public ExplorerManager getExplorerManager() {
        return explorerManager;
   }

4. Now go to the Constructor and add the following after the last existing line:

   associateLookup(ExplorerUtils.createLookup(explorerManager, getActionMap()));
   explorerManager.setRootContext(new AbstractNode(new CategoryChildren()));
   explorerManager.getRootContext().setDisplayName("Marilyn Monroe's Movies");

   Here we place the Explorer Manager in the TopComponent's Lookup. We set a class called "CategoryChildren" as the root node. We will create this class in the next section, and we will display it as the first node in our view. As display name it receives "Marilyn Monroe's Movies".

5. Fix imports. A red underline will remain because we have not created the CategoryChildren class yet. We will do so in the next section.

Creating a Category

Let's first define what a "Category" is.

1. Create a class called Category.java and add the following content:

   public class Category {
       
       private String name;
       
       /** Creates a new instance of Category */
       public Category() {
       }
       
       public String getName() {
           return name;
       }
       
       public void setName(String name) {
           this.name = name;
       }
       
   }

   From the above, you can see that a category has a name, and nothing more.

2. Create another class, this time for creating the nodes for the categories:

   public class CategoryChildren extends Children.Keys {
       
       private String[] Categories = new String[]{
           "Adventure",
           "Drama",
           "Comedy",
           "Romance",
           "Thriller"};
       
       public CategoryChildren() {
       }
       
        protected Node[] createNodes(Object key) {
           Category obj = (Category) key;
           return new Node[] { new CategoryNode( obj ) };
       }
       
       protected void addNotify() {
           super.addNotify();
           Category[] objs = new Category[Categories.length];
           for (int i = 0; i < objs.length; i++) {
               Category cat = new Category();
               cat.setName(Categories[i]);
               objs[i] = cat;
           }
           setKeys(objs);
       }
       
   }

   In this example, a popular children implementation called Children.Keys is used. By subclassing Children.Keys, you need not explicitly keep track of the nodes. Instead, you keep track of a set of keys, which are lighter weight objects. Each key typically represents one node. You must tell the implementation how to create a node for each key. You can decide for yourself what type of keys to use.

   addNotify() is called the first time that a list of nodes is needed. An example of this is when a node is expanded. Here, when addNotify() is called, a new category is instantiated. When a child node needs to be constructed, the createNodes() method is called. It is passed the key for which it is making a node. It returns either none, one, or more nodes corresponding to what should be displayed for the key. In this example, a new instance of one category node is being created, and the key is passed into its constructor.

3. Fix imports, choosing org.openide.nodes.Children and org.openide.nodes.Node.

   Note that in the code above, we create a node called CategoryNode. We will create it in the next step.

4. Create a class called CategoryNode.java and define it as follows:

   public class CategoryNode extends AbstractNode {
       
       /** Creates a new instance of CategoryNode */
       public CategoryNode( Category category ) {
           super( new MovieChildren(category), Lookups.singleton(category) );
           setDisplayName(category.getName());
           setIconBaseWithExtension("org/netbeans/myfirstexplorer/marilyn_category.gif");
       }
       
       public PasteType getDropType(Transferable t, final int action, int index) {
           final Node dropNode = NodeTransfer.node( t, 
                   DnDConstants.ACTION_COPY_OR_MOVE+NodeTransfer.CLIPBOARD_CUT );
           if( null != dropNode ) {
               final Movie movie = (Movie)dropNode.getLookup().lookup( Movie.class );
               if( null != movie  && !this.equals( dropNode.getParentNode() )) {
                   return new PasteType() {
                       public Transferable paste() throws IOException {
                           getChildren().add( new Node[] { new MovieNode(movie) } );
                           if( (action & DnDConstants.ACTION_MOVE) != 0 ) {
                               dropNode.getParentNode().getChildren().remove( new Node[] {dropNode} );
                           }
                           return null;
                       }
                   };
               }
           }
           return null;
       }
       
       public Cookie getCookie(Class clazz) {
           Children ch = getChildren();
           
           if (clazz.isInstance(ch)) {
               return (Cookie) ch;
           }
           
           return super.getCookie(clazz);
       }
       
       protected void createPasteTypes(Transferable t, List s) {
           super.createPasteTypes(t, s);
           PasteType paste = getDropType( t, DnDConstants.ACTION_COPY, -1 );
           if( null != paste )
               s.add( paste );
       }
       
       public Action[] getActions(boolean context) {
           return new Action[] {
               SystemAction.get( NewAction.class ),
               SystemAction.get( PasteAction.class ) };
       }
       
       public boolean canDestroy() {
           return true;
       }
       
   }

   An AbstractNode is a basic implementation of a node. It simplifies common requirements, such as the creation of the display name and the handling of icons. Other common requirements are handled as well. To understand what each of the methods in the code above does, click the method's link to jump to the related Javadoc.

5. Fix imports. After you fic the import statements, several red underlines will remain, because we have not created Movie.java, MovieChildren.java, and MovieNode.java. yet. We will do so in the next section.

Creating a Movie

Next, we'll work on adding the children belonging to the categories. And the children are movies. Let's begin by defining what a "movie" is.

1. Create a class called Movie.java, with the following content:

   public class Movie {
       
       private Integer number;
       private String category;
       private String title;
       
       /** Creates a new instance of Instrument */
       public Movie() {
       }
       
       public Integer getNumber() {
           return number;
       }
       
       public void setNumber(Integer number) {
           this.number = number;
       }
       
       public String getCategory() {
           return category;
       }
       
       public void setCategory(String category) {
           this.category = category;
       }
       
       public String getTitle() {
           return title;
       }
       
       public void setTitle(String title) {
           this.title = title;
       }
       
   }

   From the above, you can see that a movie has a number, belongs to a category, and has a title.

2. Now let's create the category's children. The class to be created is called MovieChildren.java. We use Index.ArrayChildren, so that we can put the nodes in an array list, which is loaded as needed. Until a child node is needed, such as when the parent node is expanded, it is not created. This is the content of the class:

   public class MovieChildren  extends Index.ArrayChildren {
       
       private Category category;
       
       private String[][] items = new String[][]{
           {"0", "Adventure", "River of No Return"},
           {"1", "Drama", "All About Eve"},
           {"2", "Drama", "Home Town Story"},
           {"3", "Comedy", "We're Not Married!"},
           {"4", "Comedy", "Love Happy"},
           {"5", "Romance", "Some Like It Hot"},
           {"6", "Romance", "Let's Make Love"},
           {"7", "Romance", "How to Marry a Millionaire"},
           {"8", "Thriller", "Don't Bother to Knock"},
           {"9", "Thriller", "Niagara"},
       };
       
       public MovieChildren(Category Category) {
           this.category = Category;
       }
       
       protected java.util.List<Node> initCollection() {
           ArrayList childrenNodes = new ArrayList( items.length );
           for( int i=0; i<items.length; i++ ) {
               if( category.getName().equals( items[i][1] ) ) {
                   Movie item = new Movie();
                   item.setNumber(new Integer(items[i][0]));
                   item.setCategory(items[i][1]);
                   item.setTitle(items[i][2]);
                   childrenNodes.add( new MovieNode( item ) );
               }
           }
           return childrenNodes;
       }
   }

3. Right-click the project, choose Properties, and use the Sources category to change the source level from 1.4 to 1.5. Click OK.

4. Fix imports. A red underline will remain because we have not create MovieNode.java, which we will do in the next step.

5. Create a class called MovieNode.java and define it as follows:

   public class MovieNode extends AbstractNode {
       
       private Movie movie;
       
       /** Creates a new instance of InstrumentNode */
       public MovieNode(Movie key) {
           super(Children.LEAF, Lookups.fixed( new Object[] {key} ) );
           this.movie = key;
           setDisplayName(key.getTitle());
           setIconBaseWithExtension("org/netbeans/myfirstexplorer/marilyn.gif");
       }
       
       public boolean canCut() {
           
           return true;
       }
       
       public boolean canDestroy() {
           return true;
       }
       
       public Action[] getActions(boolean popup) {
           return new Action[] {
               SystemAction.get( CopyAction.class ),
               SystemAction.get( CutAction.class ),
               null,
               SystemAction.get( DeleteAction.class ) };
       }
       
   }

   Fix imports.

   Notice that most of this class is about defining actions on the movie nodes. When you right-click a movie, you'll be able to choose "Copy" or "Cut" or "Delete".

Creating a Root Node

Now we are going to install our module. When we do so, we will test our module's functionality and see if everything is as we would want it to be.

1. Right-click the module and choose Install/Reload in Development IDE.

2. Examine the result:

   

3. Notice that even though you can drag and drop movies from one category to another (by dragging with your mouse, with the Ctrl key held down when you want to copy a node), the menu items are greyed out. Also, notice that the root node does not have an icon.

4. First, we need to enable the menu items by adding the actions to the TopComponent's action map. Do this by adding the following snippet to the end of the TopComponent's Constructor:

   ActionMap map = getActionMap();
   map.put(DefaultEditorKit.copyAction, ExplorerUtils.actionCopy(explorerManager));
   map.put(DefaultEditorKit.cutAction, ExplorerUtils.actionCut(explorerManager));
   map.put(DefaultEditorKit.pasteAction, ExplorerUtils.actionPaste(explorerManager));
   map.put("delete", ExplorerUtils.actionDelete(explorerManager, true));

5. Next, to be able to control the icon displayed by the root node, we need to create a class for that node. Currently, we are using a default AbstractNode, over which we have no control.

   Create a class called RootNode.java, with this content:

   public class RootNode extends AbstractNode {
       
       /** Creates a new instance of RootNode */
       public RootNode(Children children) {
           super(children);
       }
       
       public Image getIcon(int type) {
           return Utilities.loadImage("org/netbeans/myfirstexplorer/right-rectangle.png");
       }
       
       public Image getOpenedIcon(int type) {
           return Utilities.loadImage("org/netbeans/myfirstexplorer/down-rectangle.png");
       }
       
   }

   Notice that here we set one icon for when the node is in its closed state and another for when it is expanded. To use this node, we need to change this line in the TopComponent:

   explorerManager.setRootContext(new AbstractNode(new CategoryChildren()));

   We need to replace that line with this line:

   explorerManager.setRootContext(new RootNode(new CategoryChildren()));

6. Install the module again and notice the icons displayed for the root node's collapsed and expanded states. Here, the icon for the expanded state is shown:

   

   Also notice that the movie node's menu items are now enabled and functional.

List View

List view is an explorer view that displays items in a list. It is provided by the ListView class, which belongs to the Explorer And Property Sheet API.

1. Add this line to the end of the TopComponent's Constructor:

   listView = new ListView();

   Put the cursor in the line and let the IDE generate an import statement for org.openide.explorer.view.ListView. Also let the IDE create the listView field.

2. Below the line above, add this line, which adds the view to the TopComponent:

   add(listView, BorderLayout.CENTER);

   Let the IDE generate the java.awt.BorderLayout import statement for BorderLayout.

   Note: When you created the TopComponent earlier in this tutorial, you should have set the layout manager to BorderLayout. If you did not do this, make the JScrollPane smaller, right-click the TopComponent, choose Set Layout, and select BorderLayout.

3. Install the module again. Notice that the view is now as follows:

   

   When you click on a category, the movies are displayed:

   

Choice View

Choice view is an explorer view based on a combo box. It is provided by the ChoiceView class, which belongs to the Explorer And Property Sheet API.

1. Add this line to the end of the TopComponent's Constructor:

   choiceView = new ChoiceView();

   Put the cursor in the line and let the IDE generate an import statement for org.openide.explorer.view.ChoiceView. Also let the IDE create the choiceView field.

2. Instead of the line that adds a ListView to the TopComponent, write a line that adds the ChoiceView:

   add(choiceView, BorderLayout.CENTER);

3. Install the module again. Notice that the view is now as follows:

   

   Note: If your TopComponent is very large, the combo box provided by the choice view will be very large as well.

Menu View

Menu view is an explorer view that displays the hierarchy of nodes in a popup menu. Initially, it shows a left button which opens a popup menu from the root context and a right button which opens a popup menu from the currently explored context. It is provided by the MenuView class, which belongs to the Explorer And Property Sheet API.

1. Add this line to the end of the TopComponent's Constructor:

   menuView = new MenuView();

   Put the cursor in the line and let the IDE generate an import statement for org.openide.explorer.view.MenuView. Also let the IDE create the menuView field.

2. Instead of the line that adds a ChoiceView to the TopComponent, write a line that adds the MenuView:

   add(menuView, BorderLayout.CENTER);

3. Install the module again. Notice that the view is now as follows:

   

   When you click on the first button, the complete list of categories is displayed:

   

   When you click with the right mouse button on the "Browse from root" button, the "Browse from current point" button is enabled and you can browse to movies within the selected category:

   

Other Views

The org.openide.explorer.view package provides many other explorer views, in addition to those outlined above. For example, IconView presents the categories and its contents as icons:

Other views include ContextTreeView and ListTableView.

Finally, a TreeTableView could also be used. This NetBeans API class lets you create a view tree of nodes on the left and its properties in a table on the right. This is an area that deserves a tutorial of its own. Similarly, creating you own explorer view is a worthwhile but complex project that will be described in a separate tutorial.