NetBeans Options Window Module Tutorial

Installing the NetBeans Module

In the Projects window, right-click the CoolOptions project and choose Run.

The module is built and installed in a new instance of the target NetBeans Platform. The target NetBeans Platform opens so that you can try out your new module.

Using the NetBeans Module

In this section, we take on the role of the user. After a user installs our module, they would typically take the steps outlined below to specify a setting in the Options window.

1. Choose Tools > Options from the main menu. The Options window opens.

2. Select the Miscellaneous panel and notice that your new "Cool Options" panel has been integrated there:

   

3. Close the Options window. Press Ctrl-I and then type the keyword you defined earlier:

   

   You should then be able to click on the returned item to open the Options window. In addition, the specific category that you created should be opened.

In the next section, we add a text field and button to the panel and we learn how to store the user's setting when the Options window closes. Then we learn how to load the setting and use it, when appropriate, in the module's code.

Designing the Panel

First, let's add some Swing components to the panel, to give the user a means of setting a preference.

1. Make the panel in the Design view of CoolPanel.java larger, so that you have room to manoeuvre.

2. Drag and drop a JPanel, a JTextField, and a JLabel onto the panel. Add a titled border, containing the text "Details", to the JPanel. Change the text of the JLabel to "Name". You should now see the following:

   

3. Install the module again. In the Options window, you should now see the following:

   

You have now designed the new Options panel. In the next section, we'll add logic to the panel so that the text in the text field will be stored when the Options window closes.

Storing Preferences

In this section, we add code that will store the preference after the user clicks OK in the Options window.

1. Look in the source of the CoolPanel class. You should see the store() method defined as follows:

   void store() {
       // TODO store modified settings
       // Example:
       // Preferences.userNodeForPackage(CoolPanel.class).putBoolean("someFlag", someCheckBox.isSelected());
       // or for org.openide.util with API spec. version >= 7.4:
       // NbPreferences.forModule(CoolPanel.class).putBoolean("someFlag", someCheckBox.isSelected());
       // or:
       // SomeSystemOption.getDefault().setSomeStringProperty(someTextField.getText());
    }

   The comments in the code present the three ways in which preferences can be stored. The first uses the JDK's Preferences API. The second uses the NetBeans IDE 6.x+ NetBeans NbPreferences class. The third uses the pre-6.0 System Option class. The third approach is deprecated, while the first does not store preferences in the application's user directory. The second approach, the NetBeans NbPreferences class, is the recommended approach. The NetBeans NbPreferences class is based on the JDK's Preferences API, but is tailored towards NetBeans applications, in that it stores preferences in the application's user directory, which is a convenient place to store them since all other user customizations for your application are stored there too.

2. In the store() method, delete all the comments and add this line:

   NbPreferences.forModule(CoolPanel.class).put("namePreference", jTextField1.getText());

   Press Alt-Enter in the line. Let the IDE specify an import statement for the NetBeans API package called org.openide.util.NbPreferences.

3. Install the module again. Type a name in your Options window extension panel:

   

4. Click OK. Look in the application's user directory, within the config folder. In the config folder, you should find a folder called Preferences, containing a properties file for your Options window. Open the folder and notice that the preference has been stored there:

   

Loading Preferences

In this section, we add code that will load the preference. We want the preference, in this case "Harry Potter", to be loaded into at least two places. First, we want the preference to be loaded into the Options window when the application restarts. Secondly, we want to be able to use the preference somewhere in our module. After all, the reason why a preference is set is so that it can be used somewhere else in the code. Finally, we also need to handle the situation where the preference changes. In that case, we need to add a preference listener and use the new value in our code, once the value changes.

1. Look in the source of the CoolPanel class. You should see the load() method, defined with comments, similar to those discussed in the previous section.

2. In the load() method, delete all the comments and replace them with the following:

   jTextField1.setText(NbPreferences.forModule(CoolPanel.class).get("namePreference", ""));

   Now, when you restart the application, the preference is loaded into the Options window.

   Next, we will create a new TopComponent. We will only do so to demonstrate how a preference is used. Instead of a TopComponent, you could use any other Java class to use your preference. In other words, this is just an example of using a user's preference in the context of a module.

3. Right-click the module project and choose New Window Component. Call the Window Component whatever you like and position it anywhere you want it to be. When you have created it, add a JTextField to the TopComponent. This is where we will display the user's preference.

4. Switch to the TopComponent's Source view and add the following lines to the end of the constructor:

   Preferences pref = NbPreferences.forModule(CoolPanel.class);
   String name = pref.get("namePreference", "");
   
   pref.addPreferenceChangeListener(new PreferenceChangeListener() {
       public void preferenceChange(PreferenceChangeEvent evt) {
           if (evt.getKey().equals("namePreference")) {
               jTextField1.setText(evt.getNewValue());
           }
       }
   });
   
   jTextField1.setText(name);

5. Install the module again.

   Whenever the application restarts, the current preference in the Options window is shown in the TopComponent. And whenever you change the preference in the Options window, the TopComponent immediately reflects the new value, as soon as OK is clicked in the Options window.

Congratulations! You have successfully completed the Options Window Module Tutorial. You now know how to provide the functionality needed for users to set your module's options.