Writing POV-Ray Support for NetBeans I - File Support

Tim Boudreau
6 June 2006

Feedback

This is a DRAFT!

The POV-Ray tutorial demonstrates integrating basic support for a new language, and writing a project type for creating projects specific to language. Even if you are not planning to do those exact things, it will familiarize you with a lot of NetBeans concepts that will be useful in writing any module.

POV-Ray - The Persistence Of Vision Raytracer is an open-source 3D rendering engine - one that only a programmer could love. Rather than having a graphical modelling tool, it is based around a scene language which is "compiled" into an image.

We will walk through creating two modules. The first implements support for POV-Ray Scene Files. The second provides a POV-Ray project type, and allows scene files to be rendered into image files.

Requirements

This tutorial assumes you have NetBeans 5.x or greater, and at least update 1 of the Module Development Environment (apisupport) module. Update 1 can be downloaded from the Update Center - just select Tools > Update Center from the main menu.

If you haven't developed a NetBeans module before, it may be useful to read a few other documents before this tutorial - it will familiarize you with some of the concepts presented here. Particularly recommended are:

• Introduction to NetBeans Idioms and Infrastructure — covers a lot of the concepts you will encounter here
• Selection in NetBeans — Not directly relevant to writing project types, but will familiarize you with using the Lookup API which pops up in a number of places here
•  — The Loaders API and supporting new file types
• The Developer FAQ — Contains definitions and descriptions of API classes and concepts, and how to do various things

Implementation Notes

Many of the instructions will tell you to add some code and then run Fix Imports to generate import statements. In a few cases, the classes used will be NetBeans classes which have the same name as classes in the JDK. In all of these cases you want the NetBeans class, not the JDK class. Watch for the following:

• ErrorManager is always org.openide.ErrorManager
• Node is always org.openide.nodes.Node

In general, wherever there is a reference to a keybinding such as Ctrl-I (override methods) or Alt-Shift-F (fix imports), if you are using a Macintosh, Ctrl- bindings will map to Command instead; and Alt bindings will map to Ctrl.

Creating the Module Suite and Projects

Since support for POV-Ray will be made up of multiple modules, we will start by creating a module suite - a container that can hold multiple interdependent modules.

1. Select File > New Project from the main menu

2. In the New Project dialog, select NetBeans Plug-In Modules > Module Suite Project and click Next or press Enter
   

3. Name the suite "povsuite" on the next screen, choose a location on your hard disk to put it, and press Enter or click Finish

4. Now we will create the first module for our suite - support for .pov files - POV-Ray scene language files. Select File > New Project again from the main menu

5. This time, select NetBeans Plug-In Modules > Module Project in the New Project wizard, and click Next or press Enter

6. On the next page of the wizard, give the module the code name "org.netbeans.examples.modules.povfile" and the display name "Povray File Support"

7. Click Finish or press Enter to create the project. It should automatically be added to the module suite we just created.
8. We will now repeat the last few steps to create another project, in which we will implement a special POV-Ray project type, whose compile actions will generate an image from a scene file. Select File > New Project again from the main menu

9. This time, select NetBeans Plug-In Modules > Module Project in the New Project wizard, and click Next or press Enter

10. On the next page of the wizard, give the module the code name "org.netbeans.examples.modules.povproject" and the display name "Povray Projects"

11. Click Finish or press Enter to create the project. It should automatically be added to the module suite we just created.

Creating a DataLoader - Basic Support for .pov Files

The first thing we will want to create is basic support that enables NetBeans to recognize .pov files, open them in the editor - which will give us a place to hang Actions, provide special icons, and other special support specific to .pov files.

A DataLoader is a factory which is registered against a particular MIME type or file extension. It creates DataObjects - typically one per file. So, when you expand a folder in the Projects or Files tab in the IDE, what happens under the hood is that all of the files in the folder you expanded are found, and for each file, the system locates the DataLoader for its file type and asks it to create a DataObject for it. DataObjects contain logic that enables them to actually parse or understand a files contents, or know what to do with that particular type of file. So there is a 1:1 mapping between files and DataObjects and a 1:1 mapping between file types and DataLoaders.

NetBeans 5.0 and up has a template called "File Type" that makes it very easy to generate basic support for a new file type:

1. Expand the Povray File Support Module and its Source Packages subnode

2. Right-click the package org.netbeans.examples.modules.povfile and choose New > File/Folder from the popup menu

3. Select NetBeans Module Development > File Type in the New File wizard and click Next or press Enter
   

4. On the next screen, you are asked to supply a MIME type and a file extension. Enter "text/x-povray" for the MIME type, and two file extensions, ".pov,.inc" for the file extensions and click Next or press Enter.
   

5. On the next screen, you are asked to supply a prefix for a the names of several Java classes that will be generated. Enter "Povray". This screen also requests an icon. Any 16x16 gif or png will do, or you can use this one . When you have entered the icon and the name, press Enter or click Finish and the IDE will generate the Java classes and metadata files needed for basic POV-Ray file support in NetBeans.

You should now have the following file structure on in the povfile package:

• org.netbeans.examples.modules.povfile/
  • Bundle.properties A resource bundle for miscellaneous localized strings
  • layer.xml A module layer file which allows the module to install some objects declaratively
  • povicon.gif The icon you chose in the wizard, which will appear on editor tabs for .pov and .inc files
  • PovrayDataLoader.java The DataLoader for POV-Ray files - it will create instances of PovrayDataObject for individual files
  • PovrayDataLoaderBeanInfo.java A BeanInfo for your DataLoader. This is used to help provide icons and properties for the node under Tools > Options > Advanced Options > IDE Configuration > System > Object Types
  • PovrayDataNode.java The node class, which will provide icons, a display name and actions for individual POV-Ray files when shown in the Projects or Files tab in NetBeans. Just as there will be one PovrayDataObject for each .pov or .inc file, so there shall also be one PovrayDataNode, provided from PovrayDataObject.getNodeDelegate()
  • PovrayDataObject.java This is the object that understands what a .pov file is. If we were to provide advanced support for POV-Ray files, we would probably parse those files here, and provide some sort of model of the structure of the file that could be shown in Navigator or manipulated programmatically
  • PovrayResolver.xml This is a small bit of XML that declares that .pov and .inc files map to the MIME type text/x-povray (which we have invented for purposes of this tutorial). This XML file is referenced from the module's layer.xml file.
  • PovrayTemplate.pov This is an empty template POV-Ray file which can be modified and will be used as the basis of new POV-Ray files in the New File wizard

  At this point we have basic support for POV-Ray files - if you right-click the module suite and click Run, NetBeans will install with both of the modules installed - and if you create a fake .pov file in your home directory and then browse, for example, in the Favorites tab (Window > Favorites from the main menu), you will see that it is indeed recognized by NetBeans, and has the icon that you specified.

  There are a few idioms worth noticing in the generated code:

  • All localized Strings are fetched using a call such as

    NbBundle.getMessage (SomeClass.class, "LBL_SomeKey");
          

    This is a NetBeans utility class that allows for fetching localized strings in a way that is friendly to NetBeans module classloaders, and allows strings to be "branded" (meaning that an application built on NetBeans can provide a substitute resource bundle that replaces the string, and this will happen transparently).

  • The DataLoader is registered in the module manifest - if you expand Povray File Support > Important Files > Module Manifest, you will see the following:

    Name: org/netbeans/modules/povray/PovDataLoader.class
    OpenIDE-Module-Class: Loader
          

    Loaders are almost the only thing registered directly in the manifest today - since loaders are one of the oldest APIs in NetBeans.
  • The layer.xml file now contains a folder, defined in XML, Loaders/text/x-povray/Actions, and all of the actions that appear on the popup menu of a .pov or .inc file are registered there. Currently the list only contains standard NetBeans API actions such as Cut and Paste; we will eventually add more. The method that makes this work is in PovrayDataObject, and was created for us:

    protected String actionsContext() {
        return "Loaders/" + REQUIRED_MIME + "/Actions"; //NOI18N
    }
          

    The return value of the above code will resolve to Loaders/text/x-povray/Actions, a virtual folder in the configuration (system) filesystem, which is where modules store runtime configuration data, and which is composed of all of the layer.xml files from all modules in the system.

  Next Steps

  The next section will cover designing and planning our project type and file support and how they will interrelate.