<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
<html xmlns="http://www.w3.org/1999/xhtml"> | |
<head> | |
<!-- -*- xhtml -*- --> | |
<title>NetBeans Options Window Module Tutorial for NetBeans Platform 6.0</title> | |
<link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"> | |
<meta name="AUDIENCE" content="NBUSER"> | |
<meta name="TYPE" content="ARTICLE"> | |
<meta name="EXPIRES" content="N"> | |
<meta name="developer" content="gwielenga@netbeans.org"> | |
<meta name="indexed" content="y"> | |
<meta name="description" | |
content="A short guide to extending the Options Window."> | |
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. --> | |
<!-- Use is subject to license terms.--> | |
</head> | |
<body> | |
<h1>NetBeans Options Window Module Tutorial</h1> | |
<p>This tutorial demonstrates how to extend the Options window. | |
<p><strong class="notes">Note: </strong>This is not the latest version of this | |
document. It applies to NetBeans IDE 6.0/6.1 only. | |
<a href="../nbm-options.html">Click here</a> to | |
see the most up to date version. | |
<p><b>Contents</b></p> | |
<img src="../../images/articles/60/netbeans-stamp60-61.gif" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 6.1" title="Content on this page applies to NetBeans IDE 6.1"> </p> | |
<ul class="toc"> | |
<li><a href="#intro">Introduction to Options Window Extensions</a></li> | |
<li><a href="#creatingthemoduleproject">Creating the Module Project</a></li> | |
<li><a href="#creatingandgettingtoknowthemainfiles">Extending the Options Window</a> | |
<li><a href="#creatingandgettingtoknowthemainfiles">Building and Installing the Module</a> | |
<li><a href="#creatingandgettingtoknowthemainfiles">Storing and Loading Preferences</a> | |
</ul> | |
<p><b>To follow this tutorial, you need the software and resources listed in the following | |
table.</b></p> | |
<table> | |
<tbody> | |
<tr> | |
<th class="tblheader" scope="col">Software or Resource</th> | |
<th class="tblheader" scope="col">Version Required</th> | |
</tr> | |
<tr> | |
<td class="tbltd1">NetBeans IDE</td> | |
<td class="tbltd1">version | |
<a href="http://download.netbeans.org/netbeans/6.1/final/">version 6.1</a> or<br> | |
version 6.0</td> | |
</tr> | |
<tr> | |
<td class="tbltd1">Java Developer Kit (JDK)</td> | |
<td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">version 6</a> or<br> | |
version 5</td> | |
</tr> | |
</tbody> | |
</table> | |
<h2 class="tutorial"><a name="intro"></a>Introduction to Options Window Extensions</h2> | |
<p>Whether you | |
are creating a plugin for NetBeans IDE or for another application, there | |
is a good chance that you want the user to be able to specify settings, | |
such as the location of an external file. The Options window offers a | |
centralized location for all such settings. In the IDE, the Options window | |
is found under the Tools menu and looks as follows: | |
<p><img border="1" src="../../images/tutorials/options/options-general.png" alt="Primary Panel"> | |
<p>The NetBeans APIs give you access to the Options window in two different ways. In the | |
first case, you can add a new panel to the Options window. Using this approach, your | |
module will add a new 'primary' panel to the Options window, similar to the 'General' panel | |
or 'Editor' panel shown in the screenshot above. Your panel will, just like these panels, | |
have a name and an image in the top of the Options window, together with its settings in | |
the body of the panel. In the second case, the NetBeans APIs allow you to add a new panel | |
within the Miscellaneous panel, shown below: | |
<p><img border="1" src="../../images/tutorials/options/options-miscellaneous.png" alt="Misc Panel"> | |
<p>In this case, your new panel will have its own tab, just like "Ant" or "Diff" above, together | |
with the settings within a panel in the body of the Options window extension. | |
Whether you add your user settings within a new primary panel or within a tab in the | |
Miscellaneous panel is completely up to you. Factors that might influence your | |
decision are purely personal and a question of your own taste. | |
<p>At the end of this tutorial, the Options window will be extended with a new panel. | |
In addition, you will be shown how to use the <tt>NbPreferences API</tt> to store and | |
use the settings that the user specifies in your Options window extension. | |
<h2 class="tutorial"><a name="creatingthemoduleproject"></a>Creating the Module Project</h2> | |
<p>We begin by working through the New Module Project | |
wizard. At the end of it, we will have a basic | |
source structure, with some default files, that | |
every NetBeans module requires. | |
<ol> | |
<li><p>Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under Projects, | |
select Module Project and click Next.</p></li> | |
<li><p>In the Name and Location panel, type <tt>CoolOptions</tt> in Project Name. | |
Change the | |
Project Location to any directory on your computer. Leave the Standalone Module radiobutton | |
and the Set as Main Project checkbox selected. The panel should now look as follows:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-new-module-1.png" alt="Step 1 of wizard."></p> | |
<p>Click Next.</p></li> | |
<li><p>In the Basic Module Configuration panel, replace <tt>yourorghere</tt> in Code Name Base with <tt>netbeans.modules</tt>, | |
so that the whole code name base is <tt>org.netbeans.modules.cooloptions</tt>. | |
Add a space to the default Module Display Name, so that it is changed to <tt>Cool Options</tt>. | |
Leave the location of the localizing bundle and XML layer, so that they will be stored in a | |
package with the name <tt>org/netbeans/modules/cooloptions</tt>. The panel should now look as follows:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-new-module-2.png" alt="Step 2 of wizard."></p> | |
<p>Click Finish.</p></li> | |
</ol> | |
<p> The IDE creates the <tt>Cool Options</tt> | |
project. The project contains all of your sources and | |
project metadata, such as the project's Ant build script. The project | |
opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its | |
file structure in the Files window (Ctrl-2). For example, the Projects window should now look as follows:</p> | |
<p align="left"><img border="1" src="../../images/tutorials/options/options-initial-projects-window.png" alt="Initial Projects window."></p> | |
<!-- =================================== ================================================== --> | |
<h2><a name="creatingandgettingtoknowthemainfiles"></a>Extending the Options Window</h2> | |
<p>Now that we have a module project, which gives us our source structure, | |
we simply run through another wizard that will create the NetBeans API implementation | |
of an Options window extension. In the wizard, you simply | |
need to specify the type of panel you want to have generated, either a primary | |
panel or a miscellaneous panel, and then the wizard will | |
generate all the required classes and <tt>layer.xml</tt> registration | |
details for you. | |
<ol> | |
<li><p>Right-click the "Cool Options" project node and | |
choose New > Other. Under Categories, select Module Development. Under File Types, | |
select Options Panel. You should now see the following:</p> | |
<p align="left"><img border="1" src="../../images/tutorials/options/options-file-template.png" alt="Options template."> | |
<p>Click Next.</li> | |
<p><li>In the next panel, specify the type of panel that you want to create and fill | |
in the information required. Initially, this panel looks as follows:</p> | |
<p align="left"><img border="1" src="../../images/tutorials/options/options-choose-panel-type.png" alt="Options template."> | |
<p>In this tutorial, we assume that we are creating a Miscellaneous Panel, with the following details: | |
<ul> | |
<li><b>Title.</b> Cool Options | |
<li><b>Tool Tip.</b> Select Cool Options! | |
</ul> | |
<p>Click Next. | |
<p><li>In the Name and Location panel, you can set the prefix of the classes that will | |
be generated and the package where they will be placed by default. Change the Class Name | |
Prefix to "Cool" and leave the package name unchanged.</p> | |
<p>Click Finish.</ol> | |
<p>The Projects window should now look as follows:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-final-projects-window.png" alt="Initial Projects window."> | |
<!-- ======================================================================================= --> | |
<h2><a name="building"></a>Building and Installing the Module</h2> | |
<p>We have done no coding whatsoever, but we can already try out our module. When we do so | |
we will simply see our new panel, integrated with the other panels in the Options window. In subsequent | |
sections, we will add settings for the user to make use of.</p> | |
<div class="indent"> | |
<h3 class="tutorial"><a name="installing-the-nbm"></a>Installing the NetBeans Module</h3> | |
<p>In the Projects window, right-click the <tt>Cool Options</tt> project and choose Install/Reload | |
in Target Platform.</p> | |
<p>The module is built and installed in the target IDE or Platform. The target IDE or Platform opens so that you | |
can try out your new module. The default target IDE or Platform is the | |
installation used by the current instance of the development IDE. Note that when you run your module, you will be using | |
a temporary test user directory, not the development IDE's user directory.</p> | |
<h3 class="tutorial"><a name="using-the-nbm"></a>Using the NetBeans Module</h3> | |
<p>In this section, we take on the role of the user. After a user | |
installs our module, they typically take the steps outlined below to | |
specify a setting in the Options window. | |
<ol> | |
<li><p>Choose Tools > Options from the main menu.</p> | |
<p>The Options window opens. | |
<p><li>Select the Miscellaneous panel | |
and notice that your new "Cool Options" panel has been | |
integrated there:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-installed-1.png" alt="Options window installed 1."> | |
</ol> | |
<p>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. | |
</div> | |
<!-- ======================================================================================= --> | |
<h2><a name="tweaking"></a>Storing and Loading Preferences</h2> | |
<p>In this section, we begin by designing the Options window extension. | |
Using the GUI Builder, we add a <tt>JPanel</tt>, a <tt>JTextField</tt>, | |
and a <tt>JLabel</tt>. Then we install the module again and we see | |
the result. Next, we begin coding. Using the <tt>NbPreferences API</tt>, | |
we store the value entered by the user. Storage of preferences is done | |
in the user directory. Then we load the preference into an appropriate place | |
in our code.</p> | |
<div class="indent"> | |
<h3 class="tutorial"><a name="icon"></a>Designing the Panel</h3> | |
<p>First, let's add some Swing components to the panel, to give | |
the user a means of setting a preference. | |
<ol> | |
<li><p>Drag and drop a <tt>JPanel</tt>, <tt>JTextField</tt>, and a <tt>JLabel</tt> | |
onto the panel. Add a border to the <tt>JPanel</tt> and set the panel's background color | |
to the same color as the <tt>JPanel</tt>. Change the text of the <tt>JLabel</tt> to "Name". | |
You should now see the following:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-design.png" alt="Options design"> | |
<p><li>Install the module again. In the Options window, you should now see the following:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-installed-2.png" alt="Options design"> | |
</ol> | |
<h3 class="tutorial"><a name="sources"></a>Storing Preferences</h3> | |
<p>In this section, we add code that will store the preference after the user clicks OK in the Options window.</p> | |
<ol> | |
<li>Look in the source of the <tt>CoolPanel</tt> class. You should see the <tt>store()</tt> method defined as follows: | |
<pre class=examplecode>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()); | |
}</pre> | |
<p>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.0 NbPreferences API. 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 NbPreferences API, | |
is the recommended approach. The NbPreferences API 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. | |
<p><li>In the <tt>store()</tt> method, delete all the comments and add this line: | |
<pre class=examplecode>NbPreferences.forModule(CoolPanel.class).put("namePreference", jTextField1.getText());</pre> | |
<p>Press Alt-Enter in the line. Let the IDE specify an import statement for the | |
NetBeans API package called <tt>org.openide.util.NbPreferences</tt>. | |
<p><li>Install the module again. Type a name in your Options window extension panel:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-installed-3.png" alt="Typing a name"> | |
<p><li>Click OK. Look in the application's user directory, within the <tt>config</tt> folder. | |
In the <tt>config</tt> folder, you should find a folder called <tt>Preferences</tt>, containing | |
a properties file for your Options window, as shown below:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-preferences-folder.png" alt="Preferences folder"> | |
<p><li>Open the folder and notice that the preference has been stored there:</p> | |
<p><img border="1" src="../../images/tutorials/options/options-preferences-folder-2.png" alt="Preferences folder 2"> | |
</ol> | |
<h3 class="tutorial"><a name="sources"></a>Loading Preferences</h3> | |
<p>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.</p> | |
<ol> | |
<li>Look in the source of the <tt>CoolPanel</tt> class. You should see the <tt>load()</tt> method, | |
defined with comments, similar to those discussed in the previous section. | |
<p><li>In the <tt>load()</tt> method, delete all the comments and replace them with the following: | |
<pre class=examplecode>jTextField1.setText(NbPreferences.forModule(CoolPanel.class).get("namePreference", ""));</pre> | |
<p>Now, when you restart the application, the preference is loaded into the Options window. | |
<p>Next, we will create a new <tt>TopComponent</tt>. We will only do so to demonstrate | |
how a preference is used. Instead of a <tt>TopComponent</tt>, 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. | |
<p><li>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 <tt>JTextField</tt> to the <tt>TopComponent</tt>. This is where we will display the user's | |
preference. | |
<p><li>Switch to the <tt>TopComponent's</tt> Source view and add the following lines | |
to the end of the constructor: | |
<pre class=examplecode>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);</pre> | |
<p><li>Install the module again.</p> | |
<p>Whenever the application restarts, the current preference in the Options window | |
is shown in the <tt>TopComponent</tt>. And whenever you change the preference in | |
the Options window, the <tt>TopComponent</tt> immediately reflects the new value, | |
as soon as OK is clicked in the Options window. | |
</ol> | |
<p>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. | |
</div> | |
<br> | |
<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Options%20Window%20Module%20Tutorial">Send Us Your Feedback</a></div> | |
<br style="clear:both;" /> | |
<!-- ======================================================================================== --> | |
<h2><a name="nextsteps"></a>Next Steps</h2> | |
<p>For more information about creating NetBeans modules, see the following resources: | |
<ul> | |
<p><li><a href="https://netbeans.org/kb/trails/platform.html">Other Related Tutorials</a></li> | |
<p><li><a href="https://netbeans.org/download/dev/javadoc/">NetBeans API Javadoc</a></li> | |
</ul> | |
<!-- ======================================================================================== --> | |
</body> | |
</html> |