Hacking NetBeans #1 - First Steps
By Roman Strobl on VII 25, 2005
I'm starting hereby a new series of posts called Hacking NetBeans. Through this I want to share my experiences with using NetBeans APIs when writing NetBeans plug-ins. I know almost nothing about NetBeans APIs at the moment so I'll meet many obstacles. My advantage is that I can ask anyone in the Prague building for an answer and by writing these answers down I hope to provide simple answers for other developers (you'll probably have similar issues as I do). The disadvantage is that not every information has to be correct but hopefully I'll learn by making mistakes.
So you decided to write your NetBeans plug-in. Good. For 4.1 you have to prepare the backbone of your plug-in manually but development version of 4.2 comes with a nice GUI you can use. Geertjan wrote a good tutorial which can help you with the first steps or you can take a look at my little Googlefight plug-in.
Once you'll capture the basics (how to create a hello world plug-in, how to customize it, how to add dependencies, etc.) you're biggest friend will be this page which describes the NetBeans API (or it's 4.1 brother). Here you can find the APIs of both NetBeans platform and NetBeans IDE you'll need to use in your plug-in. Your second friend is the openide mailing list archive which can provide answers to many questions.
As described in the tutorials here and here, usually the plug-in becomes a part of NetBeans by defining an action in the layer.xml file. Here you define the class which will be called once the users click on the menu item. So your the method performAction() of your class which extends CallableSystemAction and is defined in layer.xml is called and your code starts to be executed.
Inside the peformAction() method you can do basicly whatever you want - run your code and call various NetBeans APIs to do someting useful with your plug-in. Seems easy, but you'll probably have many questions soon. Like:
Question #1: How do I place my menu item to a different position in the menu?
Answer: Like this:
<filesystem> <folder name="Menu"> <attr name="Tools/Games" boolvalue="true" /> <attr name="Games/Window" boolvalue="true" /> <folder name="Games"> <file name="com-toy-anagrams-OpenAnagramAction.instance"/> </folder> </folder> </filesystem>
By this you are saying that the Games menu containing your menu item will be after the Tools menu and before the Window menu. This works for the top menu, you can do it similarly inside a menu:
<filesystem> <folder name="Menu"> <folder name="File"> <attr name="org-netbeans-modules-project-ui-SetMainProject.shadow/org-netbeans-modules-projectpackager-ZipProject.instance" boolvalue="true" /> <attr name="org-netbeans-modules-projectpackager-ZipProject.instance/org-netbeans-modules-project-ui-CustomizeProject.shadow" boolvalue="true" /> <file name="org-netbeans-modules-projectpackager-ZipProject.instance"/> </folder> </folder> </filesystem>
Question #2: How do I dock my component into the IDE?
Answer: Explained in the tutorial here in section Embedding and Displaying the Anagram Plug-in. You need to create a class which extends the TopComponent class and do described steps to dock it and activate it.
Question #3: I've sent the sources of my plug-in to my friend but he can't the project in the IDE. What's wrong?
Answer: When you distribute your project you need to make sure not to include the private subfolder of the nbproject folder. This subfolder contains information about paths on your computer. Once you try to open a project with this subfolder somewhere else, the dialog fails to open the project folder without giving an error, so this is quite tricky. Thus don't forget to remove the private folder if you send the project anywhere.
Question #4: I can't find a method on an object although my intuition tells me it should be there. Where is it?
Answer: Some of the methods are not connected with the object you're using. For example the object Project has several methods like getProjectDirectory but if you want to find more information about the project you need to use a static method ProjectUtils.getInformation(Project). Similarly to get a list of opened projects you won't find through classes around the Project class but you need to find the OpenProjects class. My advice is to look around in the javadoc or search for usage of such classes in NetBeans sources.
Enough about hacking of NetBeans for today. Good night.