Window System in NetBeans Platform 6.9

Creating window groups

Some windows should always open and close together with other windows.
For example, in NetBeans IDE, the Matisse GUiBuilder’s Design mode always
opens together with the Inspector, the Palette, and the Properties window. That
combination of windows constitutes a workspace to use when laying out an
application’s user interface. To achieve this yourself in your own application,
you need to define a TopComponentGroup.

In the following example, you group the two TopComponents you have created in the
previous sections and open and close them together as a single unit.

  1. To get started, within the CustomModes module, create a new empty file
    named colorgroup.wsgrp, with the following content:

  2. <?xml version=”1.0″ encoding=”UTF-8″?>
    <!DOCTYPE group PUBLIC
    “-//NetBeans//DTD Group Properties 2.0//EN”
    <group version=”2.0″>
    <name unique=”colorgroup” />
    <state opened=”false” />

    You have now defined a group named colorgoup and you have specified that
    initially the TopComponents within the group are closed.

  3. Let us now specify which TopComponents belong to the group.
    Create two new files called RedTopComponentWstcgrp.xml and
    BlueTopComponentWstcgrp.xml, with the content shown in the
    following code snippets:

  4. <?xml version=”1.0″ encoding=”UTF-8″ ?>
    <!DOCTYPE tc-group PUBLIC “-//NetBeans//DTD Top Component in Group
    Properties 2.0//EN” “”>
    <tc-group version=”2.0″>
    <module name=”com.netbeansrcp.custommodes” spec=”1.0″/>
    <tc-id id=”RedTopComponent” />
    <open-close-behavior open=”true” close=”true” />
    <?xml version=”1.0″ encoding=”UTF-8″?>
    <!DOCTYPE tc-ref PUBLIC “-//NetBeans//DTD Top Component in Mode
    Properties 2.0//EN” “”>
    <tc-ref version=”2.0″ >
    <module name=”com.netbeansrcp.custommodes” spec=”1.0″/>
    <tc-id id=”BlueTopComponent”/>
    <open-close-behavior open=”true” close=”true” />

    You now have a file per TopComponent, providing the TopComponent’s
    unique ID, while declaring the state of the TopComponent when the group
    to which it belongs is opened or closed.

  5. Now modify the layer.xml to register the two files created in the previous
    step, within the Windows2 | Groups folder:

  6. <folder name=”Groups”>
    <file name=”colorgroup.wsgrp” url=”colorgroup.wsgrp”/>
    <folder name=”colorgroup”>
    <file name=”RedTopComponent.wstcgrp”
    <file name=”BlueTopComponent.wstcgrp”

    The file colorgroup.wsgrp declares the group to the Window System and
    refers to the group definition file of the same name. The subfolder colorgroup
    describes the contents of the group and adds references to the file for
    each TopComponent, so that they now belong to the group.

  7. Use the New Action wizard to create two new Always Enabled actions,
    OpenRedBlueAction and CloseRedBlueAction, with display names
    OpenRedBlue and CloseRedBlue, for opening/closing the group. Within
    the ActionListener classes generated by the New Action wizard, define the
    code to be invoked as follows:

  8. public void actionPerformed(ActionEvent evt) {
    TopComponentGroup myGroup
    if (myGroup != null) {;
    public void actionPerformed(ActionEvent evt) {
    TopComponentGroup myGroup = WindowManager.getDefault()
    if (myGroup != null) {

  9. Modify the files BlueTopComponentWstcref.xml and
    RedTopComponentWstcref.xml, to ensure that their individual
    default states are set to closed:

  10. <state opened=”false”/>

  11. Choose Clean and Build on the application to remove the build folder
    that contains the user settings persisted from the last deployment of the
    application. Start the application again. Select Window | OpenRedBlue and
    notice that both TopComponents open. Then select Window | CloseRedBlue
    and notice that both TopComponents close.

In the summary, you have learned how to define a group of TopComponents that
open and close together as a unit.

Extending the default TopComponent persistence

You’ve probably noticed that when you restart the application, its layout is not reset
to its default state. Instead, the layout settings from the last deployment are reused
whenever you restart the application. That is what the user typically expects, though
this may be inconvenient during development. During development, if you’d like
the default layout to be used when you run the application, you need to select Clean
and Build
on the application node. This menu item deletes the application’s build
folder, which contains the testuserdir folder, where the settings from the previous
deployment are stored.

It is this feature, that of automatic persistence, that we now look at more closely. In
this section, we extend the persistence of our application, as the NetBeans Platform 6.9
allows us to access the persistence feature and to save additional data when the
application is closed.

In the next example, we create a simple form with content that is restored when the
application restarts.

  1. Create a new NetBeans Platform 6.9 application, containing a new module, with
    a TopComponent created via the New Window wizard. The TopComponent
    should have PersistenceDemo as its Class Name Prefix, it should be
    positioned within the editor mode, and it should open when the
    application starts. Design the content of the new TopComponent
    as shown the following screenshot:

  2. The Window System APiprovides special support for serialization of confi
    guration data. To store configuration data, and to reload them at restart,
    we need to override the methods writeProperties and readProperties,
    which are generated by the New Window wizard when you created the Top-
    Component. These methods are required so that the @ConvertAsProperties
    annotation, declared at the top of the TopComponent class, is able to generate
    the code at compile time, persisting the specified settings.

    To fine-tune the TopComponent persistence outlined above, you have two additional
    values that need to be set, but which are set by default when you use
    the New Window wizard to create your TopComponent:

    • The value returned by the preferredID() method. T he returned
      value uniquely identifies the TopComponent to the Window System.

    • The value returned by the getPersistenceType method. This
      value determines the conditions under which the TopComponent is
      persisted. The value TopComponent.PERSISTENCE_ALWAYS specifies
      that the content of the TopComponent will be persisted, in so far as
      you have specified settings for persistence. PERSISTENCE_NEVER
      specifies that when the application closes, nothing set in the
      TopComponent will be persisted. Finally, PERSISTENCE_ONLY_OPENED
      specifies that a TopComponent is only persisted if it is open when
      the application shuts down. The latter is useful if the TopComponent
      is some kind of editor, for example, as in the cases of the editor
      windows in NetBeans IDE, which reopen on startup if they had
      been closed when the application shut down.

  3. Specify that the PersistenceDemoTopComponent should persist if it was
    open when the application shut down. Next, define the writeProperties
    and readProperties methods as follows:

  4. void writeProperties(java.util.Properties p) {
    // better to version settings since initial version as advocated
    // at
    p.setProperty(“version”, “1.0”);
    p.setProperty(“element1”, jTextField1.getText());
    if (jRadioButton1.isSelected()) {
    p.setProperty(“element2”, “1”);
    if (jRadioButton2.isSelected()) {
    p.setProperty(“element2”, “2”);
    if (jRadioButton3.isSelected()) {
    p.setProperty(“element2”, “3”);
    p.setProperty(“element3”, String.valueOf(jCheckBox1.isSelected()));
    p.setProperty(“element4”, String.valueOf(jSlider1.getValue()));
    Object readProperties(java.util.Properties p) {
    if (instance == null) {
    instance = this;
    return instance;
    private void readPropertiesImpl(java.util.Properties p) {
    String version = p.getProperty(“version”);
    if (p.getProperty(“element2”).equals(“1”)) {
    if (p.getProperty(“element2”).equals(“2”)) {
    if (p.getProperty(“element2”).equals(“3”)) {
    if (p.getProperty(“element3”).equals(“true”)) {
    } else {

  5. Restart the application. Enter some values into the TopComponent and then
    close the application. When you restart the application, notice that the values
    you specified are restored as shown in the following screenshot:

When you close the application, do a Clean and Build on the TaskManager
project node. Then, now that the application user directory is removed, restart
the application and notice that all the values are set back to their defaults.

In summary, you have extended the persistence of the TopComponent, so that the
values specified in the TopComponent at the time the application shuts down are
restored when the application is restarted.


You have been introduced to all of the most important topics relating to working
with the NetBeans Window System. Not only did you learn how to create new
windows, that is, TopComponents, but you also learned how to position them,
group them, and extend their persistence.

In the next chapter, you focus on one of the key topics of modular architectures, that
is, how a module can communicate with another module, without even the need to
know that it exists! This is a key requirement for modular architectures ensuring that
modules are loosely coupled from each other.

NetBeans Articles

Pages: 1 2 3 4

Leave a Reply

Your email address will not be published. Required fields are marked *

Pin It on Pinterest

Share This

Share this post with your friends!