Todd Fast's Blog

Tips for using NetBeans SystemOptions

A colleague asked me a few questions about using SystemOptions in NetBeans 3.6 today, so I thought I'd blog my response for everyone else. SystemOptions are the nodes you customize in the IDE's Options dialog. Unlike when using other parts of the Open API, developers generally don't usually create nodes here directly (though this is possible); instead, they define instances of SystemOption beans and the IDE takes care of presenting these instances as nodes. SystemOptions are pretty well-documented, but there are a few things that bear clarification.

First, for our purposes, all SystemOptions are JavaBeans. This means that they have accessor and mutator methods conforming to JavaBean conventions, and that they use BeanInfo to allow friendly editing in the property sheet.

The actual bean instance and how the IDE gets to it is specified in a .settings file that you include with your module and reference from your module layer file. This settings file is in a NetBeans XML format and it not only indicates the type of the instance (and all its superclasses, interfaces, and superinterfaces), but it also tells the IDE which method on which class can be called to create (or return a reference to) a singleton instance.

All of this is well-documented in the SystemOption JavaDoc, so no need to repeat it here. Note, one thing that may not be immediately clear from the docs is the fact that settings files (and any other file declared via the url property) are resolved relative to the layer file location, unless you use an absolute URL beginning with a slash (/). In other words, the resolution rules are the same as URLs in HTML/HTTP.

One caveat when using the settings file is how much information you specify. If you leave out a crucial type declaration, like java.io.Serializable, the option may not be instantiated or may otherwise behave strangely. To be safe, always include all type declarations for the SystemOption in your settings file.

In order for your option to appear in the IDE, it must be declared in a particular location in your layer file. Specifically, it must be declared as a child of the /UI/Services/ folder. It's tempting to just place the reference to the settings file here directly, but this prevents it from being picked up by the default lookup and can potentially cause unexpected behavior. Instead, you should place the instance in the /Services/Hidden/ folder and mirror it in /UI/Services/ folder using a .shadow file reference to the original. You can find full information in the Services API overview docs.

Once you've created and installed your option, you will want to make it friendly to edit by adding a BeanInfo class. This works just like it does for any other JavaBean, with one subtlety. In NetBeans, the BeanInfo's list of PropertyDescriptors is used not only for display of properties, but also to decide which properties will be persisted between IDE sessions. Therefore, unlike other uses of JavaBeans, you cannot omit a property from the PropertyDescriptor list to hide it from the UI while also saving the value of the hidden property. Furthermore, if I recall correctly, the hidden property of the PropertyDescriptor is not respected when displaying the option. If you want to keep some hidden options, create a new option class, place it in the /Services/ folder, but omit it from the /UI/Services/ folder in your layer. It will then be persisted if changed (from your module code), but will not appear in the UI. This is useful if you want to do something like remember selections, dialog locations, or anything else that the user doesn't want to manipulate.

--
Posted at 07:21PM Nov 04, 2004 by Todd Fast in NetBeans  | 
Tags: /
Like this post?  |  | | |