EditorSettingsTransitionGuidelines

Migrating Modules From The Old Editor Settings

Contents


This page describes common situations that module owners are likely to encounter when migrating their modules from the old editor settings infrastructure. If you are a module owner and have problems with rewriting your module and this page doesn't help you, please send a question to dev (at) editor (dot) netbeans (dot) org.

If you haven't done so you should probably first read Editor Settings Upgrade overview.


Replacing Settings class

The Settings class was replaced by java.util.prefs.Preferences, which can be obtained from MimeLookup for each mime type like this:

String mimeType = ... // mime type or MimePath of your language
Preferences prefs = MimeLookup.getLookup(mimeType).lookup(Preferences.class);

The Preferences class provides typed access to all editor setting that are of a primitive type. Complex value settings are generally not supported and in most cases there is a better support for them in other editor APIs (eg. colors, keybindings, code templates and macros).

The Preferences implementation obtained from MimeLookup can be used for both reading and writing editor settings. Any changes in the settings are notified through the PreferencesChangeListener.


Replacing classes implementating Settings.Initializer

In the old infrastructure default values for editor settings were supplied from classes implementing Settings.Initializer, which were registered by calling Settings.addSettingsInitializer method. This was usually done from module's installer (ie. subclass of ModuleInstall).

In the new concept all editor settings can be supplied from module's XML layer by adding an XML file to the Editors/<mime-type>/Preferences folder. The structure of the XML file is governed by the EditorPreferences-1_0.dtd.

In order to convert your old settings initializer to the new XML file you will have to do several things. First of all determine the mime type that you want to supply settings for. In the settings initializer this was controlled by kitClass parameter and typically your code only supplied settings for a particular kit class - your kit class. These settings should then be placed in the XML file for the mime type returned from your kit's getContentType method.

In some cases the settings initializer might have supplied settings for BaseKit.class or even for all kit classes (ie. no check on the kitClass parameter). These settings should be registered in an XML file for all editors and placed in Editors/Preferences folder.

Before converting each particular setting you should determine if it actually is neccessary to supply it. Especially when you want to supply it for all editors. There is a chance that the setting is already supplied by the editor infrastructure itself and there is no point in supplying it again (see editor/src/org/netbeans/modules/editor/resources/NetBeans-preferences.xml). Also some settings have been deprecated and are generally not in use anymore (ie. all settings that supply colors).

If you are sure about the mime type and the settings that it really makes sense to supply, you should create an XML file in the appropriate subfolder under Editors folder in your module's XML layer. An example of such a file is here:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Don't forget the license here! -->
<!DOCTYPE editor-preferences PUBLIC "-//NetBeans//DTD Editor Preferences 1.0//EN" "http://www.netbeans.org/dtds/EditorPreferences-1_0.dtd">

<editor-preferences>
    <entry name="code-folding-enable" value="true" javaType="java.lang.Boolean" />
    <!-- Add more entries here ... -->
</editor-preferences>

For those few that have complex type and there is no other way of supplying them you will have to use a settings factory. Creating settings factories is pretty simple too. They are classes with static methods that have their signature shown below.

// Generic settings factory that supplies values for different setting
class YourSettingsFactory {
    public static Object getSetting(MimePath mimePath, String settingName);
}
// Simple settings factory returning value for an 'identifier-acceptor' setting
class YourSettingsFactory {
    public static Acceptor getIdentifierAcceptor();
}

// The factory registration in preferences XML
<entry name="identifier-acceptor" value="o.n.xyz.YourSettingsFactory.getIdentifierAcceptor" javaType="methodvalue" />

The sections below show in details how to deal with particular types of settings.


Primitive type settings

  • Registration in preferences XML:
    <entry name="code-folding-collapse-comment" javaType="java.lang.Boolean" value="false" />
  • Access from java code:
    Preferences prefs = MimeLookup.getLookup(mimeType).lookup(Preferences.class);
    boolean value = prefs.getBoolean(SimpleValueNames.CODE_FOLDING_COLLAPSE_COMMENT, false);
    prefs.putBoolean(SimpleValueNames.CODE_FOLDING_COLLAPSE_COMMENT, true);


SettingsNames.RENDERING_HINTS

  • Registration in preferences XML:

Not needed. Modules were never meant to supply this setting. If your settings initializer is supplying\ this setting, please delete this code.

  • Access from java code:
    FontColorSettings fcs = MimeLookup.getLookup(mimeType).lookup(FontColorSettings.class);
    Map<?, ?> hints = fcs.getFontColors(FontColorNames.DEFAULT_COLORING).getAttribute(EditorStyleConstants.RenderingHints);

You can't modify this setting directly, but you can turn on/off text antialiasing in the editor. Normally you should not need to do this either, but if you do then here is an example.

    Preferences prefs = MimeLookup.getLookup(mimeType).lookup(Preferences.class);
    prefs.putBoolean("textAntialiasing", false);


SettingsNames.CUSTOM_ACTION_LIST

Please register your actions in the Editors/<mime-type>/Actions folder.


BaseOptions.getDefaultIndentEngineClass()

Ideally you should rewrite your subclasses of o.o.text.IndentEngine and o.n.editor.Formatter and use the new Editor Indentation API. If that were to much work you could still supply your indentation engine from a settings factory as shown in the example below.

  • Registration in preferences XML:
    <entry name="indentEngine" value="o.n.xyz.YourSettingsFactory.getIndentEngine" javaType="methodvalue" />

    // Settings factory method in YourSettingsFactory class
    public static IndentEngine getIndentEngine() {
        return new YourIndentEngine();
    }
  • Access from java code:

You should not need to access this setting at all.

Acceptor related settings

  • Registration in preferences XML:
    <entry name="abbrev-reset-acceptor" value="o.n.xyz.YourSettingsFactory.getAbbrevResetAcceptor" javaType="methodvalue" />
    <entry name="identifier-acceptor" value="o.n.xyz.YourSettingsFactory.getIdentifierAcceptor" javaType="methodvalue" />
    <entry name="indent-hot-chars-acceptor" value="o.n.xyz.YourSettingsFactory.getIndentHotCharsAcceptor" javaType="methodvalue" />
    <entry name="whitespace-acceptor" value="o.n.xyz.YourSettingsFactory.getWhitespaceAcceptor" javaType="methodvalue" />

    // Settings factory method for 'identifier-acceptor' setting in YourSettingsFactory class
    private static final Acceptor identifierAcceptor = new Acceptor() { ... };
    public static List getIdentifierAcceptor() {
        return identifierAcceptor;
    }
  • Access from java code:

You should not need to access this setting at all.


SettingsNames.TOKEN_CONTEXT_LIST

  • Registration in preferences XML:

Ideally you should get rid of the old Syntax and use new Lexer API. The new lexing infrastructure is vastly superior to the old Syntax. If for some reason you can't migrate your code please use settings factory to supply this setting.

    <entry name="token-context-list" value="o.n.xyz.YourSettingsFactory.getTokenContextList" javaType="methodvalue" />

    // Settings factory method in YourSettingsFactory class
    public static List getTokenContextList() {
        return Collections.singletonList(YourLanguageTokenContext.context);
    }
  • Access from java code:

You should not need to access this setting at all.


SettingsNames.KEY_BINDING_LIST

Register your shortcuts in Editors/<mime-type>/Keybindings


SettingsNames.*_COLORING

Not used anymore. If you are still supplying these setting from your settings initializer, please delete this code.


Replacing BaseOptions subclasses

Besides of getDefaultIndentEngineClass method there shouldn't be much in your BaseOptions subclass and you should just delete it. If you added some extra stuff to your options class please migrate it the same way as you migrated your settings initializer.

When deleting your options class do not forget to delete its *BeanInfo class and Editors/<mime-type>/Settings.settings file which registers your options class in the XML layer.

You don't have to be worried about ClassNotFoundExceptions, because the options classes were not serialized to userdirs. Even if some of them accidentally had been serialized they will be filtered out by the o.n.upgrader when importing old userdirs.


What to do with publicly accessible classes?

If you have your settings classes in a public package you will have to think about backward compatibility and decide what's best for your API. If the API is not stable you can probably just delete the classes and fix clients that are using them.

If your API is stable you will have to preserve the classes somehow. There are several tricks that you could use, but the easiest way is to simply move them to editor.deprecated.pre61settings module. The downside of this is that the package where these classes reside will be duplicated in two modules. However, editor.deprecated.pre61settings is a deprecated autoload and our ultimate goal is not to load it at all and if it's not loaded then there will be no duplicate packages.

Netbeans classloaders seem to handle duplicate packages transparently in 6.1 and there is no need for marking them as a special resource as in previous versions.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo