Yesterday we magically transformed one of the Filthy Rich Client samples into a plugin. However, when we installed our plugin into NetBeans IDE, we discovered that the functionality we were providing was superfluous, or even contradictory, to what NetBeans IDE already had, because NetBeans IDE already caters for a progress bar, thanks to its reliance on the NetBeans Platform. Kind of like moving all your furniture to your new house, only to discover that your new house already has furniture. But, better furniture! Attractive furniture. Furniture that has withstood the test of time.

So, before we create a new application , as promised yesterday, let's create a new plugin . We'll take another of the Filthy Rich Client samples. This one is called StackLayout and is discussed in chapter 10 of the book. This is what it looks like when you run it:

Now that's a pretty application! When you use your mouse to select a photo in the background, it comes to the foreground, and all the others move to the back. A custom layout is used to create this effect, and if you want to know more about it, get the book and read chapter 10! So, what we will do now is create a plugin that holds all the code that is used to create the above effect. When we are done, we will install that plugin into NetBeans IDE. It will look like this:

So, we will create a new window in NetBeans IDE and we will also copy all the code from the Filthy Rich Client sample into our module's source structure, as done yesterday. (All the classes in our plugin are shown in the screenshot above, in the left part, where you see the complete source structure of our plugin-to-be.) However, because we now have a more useful example (i.e., imagine the above as a splash screen or as a standlone photo application, for example), we will be doing a pretty useful thing by porting the sample to a plugin, since we will then (as we will see) be able to install that same plugin into a variety of other applications too.

So, let's begin! Everything will be explained, down to the smallest detail, using screenshots to guide you on your journey.

1. So, our journey begins by taking a quick look at the Filthy Rich Client sample's source structure. The Projects window shows us the following:

   

   At the same time, the Files window shows that we also have a folder that contains the sample's photos:

   

2. Let's get going. The sooner we get the beautiful sample above transformed into a plugin, the better! In the New Project wizard (Ctrl-Shift-N), select the Module template, highlighted below:

   

3. Click Next, fill in the name of the plugin, and leave all other values at their defaults:

   

4. Click Next again and fill in some more details, such as the 'code name base', which is simply a unique identifier of your module:

   

5. Click Finish. Now we have the source structure of our plugin, shown here below the sample in NetBeans IDE:

   

6. And now, just copy ALL the Java classes and the photos into your module's source structure:

   

   What I did was, I put everything that was in the original sample's default package into the module's main package. I then had to add package statements to each of these classes, because they didn't have package statements to begin with (since they were in the default package in the original sample). I created a new subpackage called 'images'and just copied the images into that. I added the original 'io' package from the original sample to the module source structure, without changing anything.

7. Right. We haven't done any coding yet, have we? We've rudely plagiarized everything thus far. Let's continue, because now we need a window that will display the cool photos from the original sample. We'll get a handy template for creating new windows, if we go to the New File wizard:

   

8. Click Next. Here we specify the area where we want the window to appear. Let's choose the 'editor' area, i.e., the area where the Source Editor is found:

   

9. Next, we type a name, which will be the prefix of the generated classes and files:

   

   As you can see, NetBeans IDE helpfully tells you what is about to be done for you, i.e., which classes and files will be generated and which existing files will be changed.

10. Click Finish. Now you see a bunch of new classes and files in your plugin source structure:

    

    You now have a TopComponent , which is your window, two XML files for serialization (neither of which you will ever need to touch), and an Action class that will appear in the Window menu (because of registration entries generated into your XML layer file), for opening the window.

11. Right-click and choose "Install/Reload in Development IDE". The plugin is then installed in the same NetBeans IDE where you are currently developing, displaying a beautifully empty window, ready for you to work with:

    

    What we now have, i.e., that window, is called a TopComponent . Think of it as a JFrame , but then an extremely magical JFrame . A JFrame on steroids. It is a JFrame that integrates into NetBeans Platform applications, as can be seen in NetBeans IDE above. You can use Matisse to design it, just like any other Swing container. Alternatively, you can just code everything into the source view, without using the design view at all.

12. For the sample's code to work with our TopComponent , we need to set the layout of our TopComponent to BorderLayout , so in the Design view, right-click on the window and choose Set Layout | BorderLayout.

13. We need to move the code from the original JFrame (called ApplicationFrame ) into our TopComponent . Open the JFrame and notice the constructor is defined as follows:

    

    Copy that code, but not the last three lines which are not needed since the NetBeans Platform already handles those details, and paste in into the TopComponent constructor:

    

    Now copy all the other methods, that are in the original JFrame , i.e., only the ones that are needed by the method calls above, into the TopComponent .

14. Finally, in the AvatorChooser class, goto line 577 or thereabouts and tweak the reference to the location of the images. Originally, they were in "./images", now they are in "images". Make that small change and your images will be found correctly. (You might encounter problems with the loading of the images, despite this change, which I want to come back to at a later point.)

15. Install the plugin again and the same user experience as before with the JFrame will have been transformed to the TopComponent :

    

16. Okay, now what's the point of all this? Right-click the plugin that you created and choose the "Create NBM" menu item, shown below:

    

17. Now take a look in the Files window, where you should now see a file that ends with the letters "NBM":

    

    An NBM file is an archive file. It is essentially a ZIP file and you can open it with any tools you use for unzipping any other ZIP file. However, it contains metadata that any NetBeans Platform application understands. What this means will become apparent later.

18. Since our NBM file can be installed in any other NetBeans Platform application, it is polite to provide some information about the plugin. When you right-click on the project node, you can go to the Project Properties dialog and use the following two panels to provide some basic info:

    

    

19. And now... it is time to reveal that all applications on the NetBeans Platform (except where this might have been disabled, although there's no reason for that) have a Plugin Manager under the Tools menu. Think 'Synaptic Package Manager', if you are a Linux Ubuntu user. The NBM file we created can be installed via that Plugin Manager, as can be seen here, in any other NetBeans Platform application:

    

20. So now, let's create a NetBeans Platform application of our own. Back in the New Project wizard, choose the Module Suite template:

    

21. Click Next, give it a name, click Finish. Go to the Project Properties dialog, to the Libraries panel, and unselect everything except the platform7 item, as shown here:

    

    All the others in that list have been added on top of platform7 , to create NetBeans IDE. We don't want NetBeans IDE. We only want the NetBeans Platform. And, by deselecting all the others, above, we have the absolute basic set of modules, i.e., the bare minimum, which together constitute the NetBeans Platform.

22. Right-click the project and run it. Now... we have the NetBeans Platform. Tada...

    

    The above is a modular Swing application framework . In fact, it is the only application framework for which all those words are true. It is the basis of your Swing application, providing all the features (and more) that every Swing application typically needs.

    Note: Anything you do not want from the NetBeans Platform can easily be excluded. What you see above is the basic starting point. You can weed and tweak and hide and disable items from here and then add and extend to your heart's content! Splash screen and title bar can be set in the module suite's Project Properties dialog, back in NetBeans IDE.

23. Under the Tools menu you have... the Plugin Manager! What did you do to get that? Nothing. Choose that Plugin Manager and install the NBM file. Now you have your new window with photos! You also have a lot more. Under the Window menu you will, for example find the 'Favorites' window, which is a file browser that the NetBeans Platform gives you for free. Open the Favorites window and your own picture gallery and you see the following:

    

    Note: Not all plugins in your application would be installed via the Plugin Manager. (For example, the Favorites window you see above comes from a plugin too, but that one is part of the NetBeans Platform.) If you look in the Projects window, at the module suite's 'Modules' node, you will see that you can add modules there. Those will be the ones that your user gets by default. The Plugin Manager is for adding additional ones, either updates to existing functionality or new features that you distribute via 'update centers'. An 'update center' is defined by an XML file that describes the location (and other info) of each plugin that you want to make available. Your users would register that XML file (which you would have on-line somewhere) in their Plugin Manager and then the Plugin Manager would download those plugins on request.

24. Chances are, though, that you want to replace those images with your own. That's the point of a picture gallery, isn't it? You don't want these anonymous (though pretty) pictures in your personal photo gallery. One thing you can do is... go to the Tools menu and choose Options. Wow... you have an Options window:

    

    You can extend that Options window. (You can also hide as much of it as you like, even all of it, if you don't want to give your users any options at all.) Add your own panels and let the user specify pictures they would like to see in their picture gallery. That Options window extension would be part of the same plugin that provides the picture gallery. There is a wizard that, just as in the case of the window earlier in this story, generates the basic classes required for Options Window extensions. Here is a tutorial that will explain everything in this regard.

25. Finally, there's something else to notice. You can drag your window around the frame, moving it to wherever you feel most comfortable with it. You can even move it right out of the frame altogether, which is a new feature in NetBeans Platform 6:

    

    And that is the meaning of a 'docking system', also known as a 'windowing system'. You get that out of the box when you create your application on the NetBeans Platform. In other words, each TopComponent comes prepackaged with functionality for minimizing, maximing, dragging, and undocking itself. Together, all these TopComponents constitute the docking system.

So, in conclusion, what have we gained from the NetBeans Platform? I think the answer is obvious. We have a pluggable application, for free. Free not only in the sense of money, but also in the sense of coding. For no coding whatsoever, we're able to extend our application. Even if it were to be small in the beginning, it now at least has the potential to grow. Other features we have seen here are a docking system, an Options window, and a file browser. But that's all just the tip of the iceberg. Virtually every part of the NetBeans Platform can be extended, as in the case of the Options window, pointed out above. Resources are many and complementary: the NetBeans Javadoc and NetBeans Platform Learning Trail , together with the vital mailing list ( dev at openide dot netbeans dot org ) and the recently published Rich Client Programming: Plugging into the NetBeans Platform .

And this is the end of this 3 part series! I hope it has shown a lot of different interrelated things. How NetBeans IDE can be a filthy rich client, for example. But also, how the richness of one NetBeans Platform application can make all other NetBeans Platform applications equally rich. A lot of functionality is interchangeable because of the pluggable nature of NetBeans Platform applications.

Update: Jump to part 1 or part 2 .