Adding a Preferences Dialog Walkthrough

Note: NetBeans has its own API to plug options/preferences panels. The walkthrough below leverages the INTViewer API. If you would rather use the NetBeans API, follow this tutorial instead: https://platform.netbeans.org/tutorials/74/nbm-options.html

A preference dialog is a form accessible from Tools -> Options. In this example, we will add a dialog to the "GUI Preferences" section. This walkthrough makes use of the panel component that was created in NetBeans/Swing Creating a Panel Walkthrough. If you did not follow this walkthrough, you can download this panel implementation in the attachments at the bottom of this page.

Reviewing Dependencies

The creation of a panel requires two modules that are part of the INTViewer platform:

  • IntviewerCore
  • Utilities API (provided with Netbeans)

See the list of INTViewer modules to load the INTViewer platform and for a description of each module.

Creating your module template using NetBeans wizard

  • Click File -> New Project
  • In the New Project wizard select NetBeans Modules from the Categories list and Module from the Projects list and click Next >
  • For Project Name, specify mydemopreferencesdialogmodule
  • Select option Standalone Module and make sure to specify the INTViewer platform in the NetBeans Platform field.
  • Click Next > and specify com.mycompany.myviewer.mydemopreferencesdialog for the Code Name Base and MyDemoPreferencesDialogModule for the Module Display Name.
  • Click on Finish

  • Right-click the package, and select New -> XML Layer...
  • Click Finish.
  • In the Projects tree view, you should see your project which includes a number of files that have been created for you

Configuring your Module

  • In the Projects tree, right click on the module MyDemoPreferencesDialogModule and select Properties from the list.
  • Under Categories, select Libraries.
  • Select Java plaform JDK1.7 . If you don't see this option, you will need to install jdk1.7 and load it into NetBeans using option Tools->Java Platforms
  • Click on the Add button next to Module Dependencies
  • In the list, select IntviewerCore, Utilities API and click OK.
  • Click OK in Project Properties Dialog

Creating an Object Editor class

    • In the Projects tree, right click on the module MyDemoPreferencesDialogModule and select New -> Java Class... from the list.
    • Enter DemoPreferencesEditor as Class Name and select com.mycompany.myviewer.mydemopreferencesdialog as Package.

  • Make this class implement IObjectEditor
  • Automatically add an import for IObjectEditor

    • Automatically create the skeleton of required methods for this class

  • Automatically add a constructor method by right-clicking Insert Code... -> Constructor...
    • Customize the class' implementation as follows:

This requires the import of java.awt.GridLayout, javax.swing.BorderFactory and javax.swing.JPanel.

You can download the DemoPreferencesEditor.java file from the attachments at the bottom this page.

Customizing the layer.xml file

Modify the layer.xml file as follow:

In this layer.xml file:

  • <folder name="PreferencePanels"> indicates the start of the list of preference panels available in the module (do not change this line)
  • <folder name="Gui Preferences"> indicates the section of preference panels the dialog is added to
  • <folder name="DemoPreferences"> indicates the name of the dialog box, as seen by the end-user
  • <file name="com.mycompany.myviewer.mydemopreferencesdialog.DemoPreferencesEditor"> indicates the fully qualified name of the associated object editor class
  • <attr name ="help" stringvalue = "preferences_tracking_cursor"/> indicates the cursor displayed for help items

You can download the layer.xml file from the attachments at the bottom this page.

Running your Preferences Dialog

    • Click the green arrow in the toolbar..
    • Open Tools -> Options
    • Click DemoPreferences

Creating a DemoPreferencesUtil class

This class makes use of the Java Preferences API.

  • In the Projects tree, right click on the module MyDemoPreferencesDialogModule and select New -> Java Class... from the list.
  • Enter DemoPreferencesUtil as Class Name.

You can download this class from the attachments at the bottom of this page. You can prefer to use the NetBeans module preferences mechanism and change:

Preferences root = Preferences.userRoot();

to

import org.openide.util.NbPreferences;

...

Preferences root = NbPreferences.forModule(DemoPreferencesUtil.class);

Create a DemoPreferencesPanel class

  • This class was created during the Creating a Panel Walkthrough. In the Projects tree, right click on the module MyDemoPreferencesDialogModule and select New -> Java Class... from the list.
  • Enter DemoPreferencesPanel as Class Name.

Only the relevant code is show in this screen snapshot. You can download the entire class from the attachments at the bottom of this page.

Edit the DemoPreferencesEditor class

  • Customize the class' implementation as follow:

You can download the final DemoPreferencesEditor.java from the attachments at the bottom of the page.

Running your Preferences Dialog

    • Click the green arrow in the toolbar..
    • Open Tools -> Options
    • Click DemoPreferences. The percentage will be saved to the preferences, and be restored each time you open the panel.

More information about Preferences Editors is available in the references.