Figure 29. Introspecting (Mr.) Bean Properties

The NetBeans Platform includes an Options API that handles the so called System Options. These are properties that you set in a module so that the user can modify them easily through the Options Dialog. These options are automatically persisted on disk, so you don't have to worry about storing them yourself. This is something similar the Java Preferences API, but much more powerful.

As we will see, the Options API is so powerful that you can add your custom properties to a Java Bean you're defining, and have all those properties automagically persisted for you. The fact is that the NetBeans Platform uses Java Bean Introspection to seek for those properties.

In fact the NetBeans team has been always concerned about standards, and this introspection mechanism follows the Java Beans Specification. This basically means that you can use BeanInfos to customize how your properties are edited (this is, you could add custom property editors to edit them), or to specify descriptions for those options.

I won't be covering BeanInfos at the moment (I don't think I really need them now). If you think you need them then you should probably go take a look at the Java Editor Options package, the Java Editor Options has a powerful BeanInfo you can learn from.

The NetBeans Editor Module uses the Options API to handle editor-related settings, such as the number of spaces per tab, the caret blink rate, the abbreviations, the font size, the indentation engine to use, the color of the caret, the key bindings, different colors and many, many other settings. It does so using a special class, called "BaseOptions" that is included in the Editor Module.

Of course it's important to associate at least a default set of options to an editor, otherwise you won't be able to work with it (you won't have key bindings, for instance!). That's the problem we were facing in the previous section: our SchemeEditorKit had no options at all (not even default ones) so the NetBeans Platform was confused and didn't know how to properly render our SchemeEditorKit, resulting in an unusable editor.

In previous sections I suggested that you should be doing different things in different modules. This makes your application much more flexible. But, should we place the options in a new module of its own? Or should we just add the single class inside the Scheme Editor Module?

I could build a separate module just for options (following my self advice of making tiny modules) but, why would anyone want a Scheme Editor Module with a SchemeEditorKit that does not work? Wouldn't it be better to include the Scheme editor options stuff inside the Scheme Editor Module, so that everything works correctly?

Yes. I think it's a better idea. So let's place all the stuff inside the Scheme Editor Module. But let's try to separate it from other classes. Let's store the new classes and files inside the "net.antonioshome.scheme.editor.options" package.

So let's build a new package "net.antonioshome.scheme.editor.options" and let's create a new class, call it SchemeEditorOptions.java, and make it extend the BaseOptions in the NetBeans Editor Module.

As we said before, the "BaseOptions" class is a derivative of the "SystemOptions" class (in the "Options API") that contains predefined options for editors (key bindings, caret blink rate, and many others). Base Options is a Java Bean with properties for editors. It has setters and getters. There's a "setCaretBlinkRate(int)" method, for instance, that sets the caret blink rate. If we wanted to add another property to

Since BaseOptions (and SchemeEditorOptions) are JavaBeans, we can add new properties of our liking. And these will be persisted to disk and restored when the Scheme IDE starts up. This is cool!

Just for fun, and to see how things work, I've added a "MyFunnyProperty" to the SchemeEditorOptions class. I don't know yet what sort of options I'll have to add to an Scheme editor, but I now know where I should be storing them!

The "SchemeEditorOptions.java" class, that we have to create, looks something like this:

package net.antonioshome.scheme.editor.options;

import org.netbeans.module.editor.options.BaseOptions;

/**
 * SchemeEditorOptions is responsible for handling Scheme options.
 * @author $Author: $ Antonio Vieiro (antonio@antonioshome.net)
 * @version $Revision: $
 */
public class SchemeEditorOptions 
  extends org.netbeans.modules.editor.options.BaseOptions
{
  /** A name for these options */
  public static String SCHEME_PREFIX= "scheme"; // NOI18N 

  /** A default constructor */
  public SchemeEditorOptions()
  {
    super( SchemeEditorKit.class, SCHEME_PREFIX ); 
    // Just for fun: modify a property in the base class ;-)
    setCaretBlinkRate( 450 );
  }

  /** A funny property */
  private int myFunnyProperty; 

  public void setMyFunnyProperty( int aValue ) 
  {
    myFunnyProperty = aValue;
  }

  public int getMyFunnyProperty() 
  {
    return myFunnyProperty;
  }

  /**
   * This is used to retrieve display names to
   *   easy internationalization of options.
   */
  protected String getString(String key) 
  {
    try
    {
      return NbBundle.getMessage(SchemeEditorOptions.class, key);
    }
    catch (MissingResourceException e)
    {
      return super.getString(key);
    }
  }
}
    

Let's review what this code does.

# Resource Bundle file for Scheme Editor Options.
OPTIONS_scheme=Scheme Editor Options
        

Of course we'll have to tell the NetBeans Platform that we have created this class, and that we want it to be executed so as to get those default options in our EditorKit. We have to register our custom SchemeEditorOptions within the platform. Any idea on how to do it?

No? Really? Think of it again...

Yep. We'll be registering it with... the XML Layer File! Of course! Let's add another layer of options to our sandwich.

Registering options with the sandwich file is performed in two steps. First we'll add an entry pointing to an external XML file, and then we'll have to write that XML file in a special format, obeying a special DTD just for options.

This may seem complicated, but it's again a piece of cake once you know what you're doing. Just think of all the hassle we're avoiding (persistence, for instance). Isn't it worth the effort? I think so!

Figure 30. Registering editor options in the XML Layer

The entry to add to the XML Layer File is a "file" entry named "Settings.settings" (this name is fixed by the platform). The "file" entry has an "url" attribute pointing to our external XML file for options. Since URLs are relative to the location of the XML Layer File, we'll set the value of the "url" attribute to "options/SchemeEditorOptions.settings", and will create an empty XML file named "SchemeEditorOptions.settings" under the "net.antonioshome.scheme.editors.options" package.

So to summarize, the XML layer file has a new entry (located under the "Editors/text/x-scheme" folder) that looks like Figure 30, “Registering editor options in the XML Layer”.

The external file ("SchemeEditorOptions.settings") is much more involved than the XML Layer file, and looks like this:

<?xml version="1.0"?>
<!DOCTYPE settings PUBLIC "-//NetBeans//DTD Session settings 1.0//EN"
"http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
<settings version="1.0">
  <module name="net.antonioshome.scheme.editor"/>
  <instanceof class="java.io.Externalizable"/>
  <instanceof class="org.openide.util.SharedClassObject"/>
  <instanceof class="java.beans.beancontext.BeanContextProxy"/>
  <instanceof class="java.io.Serializable"/>
  <instanceof class="org.openide.options.SystemOption"/>
  <instanceof class="org.netbeans.modules.editor.options.OptionSupport"/>
  <instanceof class="org.netbeans.modules.editor.options.BaseOptions"/>
  <instance class="net.antonioshome.scheme.editor.options.SchemeEditorOptions"/>
</settings>

    

This "settings" file specifies settings for the module "net.antonioshome.scheme.editor" (see the "module" element at the beginning?). And then it specifies all the class hierarchy until our "net.antonioshome.scheme.editor.SchemeEditorOptions" file. Note that this is a Serializable class (because we will be persisting data from SchemeEditorOptions to disk!)

Figure 31. Scheme Editor Options

(Click to enlarge)

I assume^[4] that specifying the class hierarchy explicitly is needed in order to correctly deserialize the class. After all deserializing the class will require loading classes from different modules and libraries (the libraries containing org.openide.util, and org.openide.options and the editor module and the Scheme editor module). Specifying them explicitly avoids the NetBeans Platform having to load too many modules: the platform will be able to load only those modules required to deserialize our options. This, of course, is better for performance!

Once we've updated our XML Layer file we, of course, have to wash our hands. This is, validate it. Right-click on the editor and select "XML Validate" in the popup menu

And we're almost ready to run our editor. You can run the SCHEMESUITE project now, but you won't yet be able to correctly edit Scheme files. We need another little step: we need to recognize the syntax of Scheme files.

Since I don't want to make this section too long I think it's better to introduce some plain syntax, and dedicate the whole next section (still on the frying pan ;-)) to syntax highlighting.

A plain syntax just recognices words. And words are printed on black on white. Just like plain text files. That's why it's called plain, after all!.

Adding a plain syntax is just a piece of cake. You'll have to add the following method to the SchemeEditorKit:

public Syntax createSyntax(Document document)
{
  return new PlainSyntax();
}
      

And, of course, add a dependency to the module containing the PlainSyntax class using the steps we talked about earlier at Section 6.4, “Adding dependencies to other modules”. PlainSyntax is useful to have a quick and dirty syntax for editors, or for editors that do not need to have syntax highlighting. Indeed a handy class.

In this section we had a snack with NetBeans options for editors, we introduced the XML file for settings and we added a plain syntax for Scheme files. Our editor should be working now, and we should be able to open and save Scheme files.

In the next section we'll add some color to those ugly black-on-white Scheme files, adding special colors for Scheme library procedures and constructs. That's going to be fun all the way long. Keep tuned for some colorful Scheme!