Window System in NetBeans Platform 6.9

Programmatically managing the Window lifecycle

You can manage the lifecycle of a TopComponent programmatically. For this purpose,
the TopComponent provides the following methods:

  • open(): Opens the TopComponent

  • requestVisible(): Requests to select to TopComponent

  • requestActive(): Requests to transfer the input focus to the TopComponent

Let’s now modify the LifeCycleDemoTopComponent for demonstration purposes.

  1. Add a JButton to the TopComponent, as follows:

  2. Implement an ActionEventListener as follows:

  3. private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {
    RequestProcessor.getDefault().post(new java.lang.Runnable() {
    public void run() {
    java.awt.EventQueue.invokeLater(new java.lang.Runnable() {
    public void run() {;
    }, 3000);
    RequestProcessor.getDefault().post(new java.lang.Runnable() {
    public void run() {
    java.awt.EventQueue.invokeLater(new java.lang.Runnable() {
    public void run() {
    }, 6000);

  4. Restart the application. When you click the button, the
    LifecycleDemoTopComponent is closed via the close()
    method, called above in the first line of the code you entered.

The RequestProcessor provides a thread pool. The default instance of this pool lets
you execute a Runnable after a short delay, thanks to the post() method. As the
TopComponent’s lifecycle method should be called from the AWT event thread, you
do not call them directly in the run() method, but by posting a new Runnable to the
EventQueue, which in the end calls the Window System APimethods.

The argument 3000 ensures that the execution of the Runnable is delayed for
3000 ms so that the TopComponent is opened again after 3s.

After six seconds the second Runnable posted to the EventQueue is executed
and requestActive() is called for your LifecycleDemoTopComponent. Your
TopComponent is now shown in the foreground, if it had been behind other
windows previously.

You have learned how to manage the lifecycle of a TopComponent. Via the example
you have seen how to open a TopComponent and make it focusable.

Positioning of windows

The NetBeans Window System divides the available space in the main window
into areas that are called “modes”. Each mode represents a specific area of the main
window, providing a container for windows in a predefined position in the frame.
You can add windows, that is, TopComponents, to a mode, either declaratively or

A standard layout is provided by the NetBeans Window System, corresponding to
the layout of NetBeans IDE. For example, the predefined modes correspond to the
names used in the corresponding positions in NetBeans IDE, such as “editor” and
“explorer”. If needed, you can define your own modes, too. No wizard is provided
for this purpose in NetBeans IDE, so you need to create the mode definition files
yourself manually.

In the previous section you learned about the layer.xml file. To create a default
layout for an application, each TopComponent needs to be declaratively registered
within the Windows2 | Modes folder, within a subfolder named after the mode in
which the TopComponent should be docked.

To demonstrate declarative registration of TopComponents, edit the layer.xml in
the LifeCycle module, changing the folder name Windows2 | Modes | editor to
Windows | Modes | rightSlidingSide, as shown in the following code snippet:

<folder name=”Windows2″>
<folder name=”Components”>
<file name=”LifecycleDemoTopComponent.settings”
<folder name=”Modes”>
<folder name=”rightSlidingSide”>
<file name=”LifecycleDemoTopComponent.wstcref”

Select Clean and Build on the application node in the Projects window, to remove
the build folder containing the last used window layout, and start the application
again. When the application starts up, notice that the LifecycleDemoTopComponent
is not opened in the editor mode. Instead, it is represented by a button on the
right sidebar of the application (as shown in the screenshot below). That is the
rightSlidingSide mode, providing a container for minimized windows.

As you have seen, providing a default layout via declarative registrations of
TopComponents is rather easy. You only need to create an entry in the layer.xml
for the TopComponent, in a folder with the name of the desired mode, within the
Windows2 | Modes folder.

Sometimes declarative registration alone is too static for your business needs.
Fortunately, positioning of TopComponents can also be done programmatically. In
the next example, you create a TopComponent that moves to new modes via a click
of a button.

  1. Add to the WindowSystemExamples application a new module named
    Modes, with the Code Name Base com.netbeansrcp.modes.

  2. Within the module, create a TopComponent called ModesDemo, which is
    opened when the application starts into the “editor” mode.

Add two JButtons to the TopComponent with the texts Back and Forward, as well as
a JLabel with an empty initial text. The TopComponent should look as shown in the
following screenshot:

In the Source view, add the following code:

private static final String[] MODES = new String[] {
“properties”, “commonpalette”, “rightSlidingSide”,
“bottomSlidingSide”, “output”, “debugger”, “navigator”,
“explorer”, “leftSlidingSide”, “editor”
private void changeMode(boolean next) {
Mode currentMode = WindowManager.getDefault().findMode(this);
String currentModeName = currentMode.getName();
String nextModeName = “editor”;
for (int i= 0; i< MODES.length; i++) { String modeName = MODES[i]; if (modeName.equals(currentModeName)) { if (next) { nextModeName = (i+ 1 < MODES.length) ? MODES[i+ 1] : MODES[0]; } else { nextModeName = (i- 1 >= 0) ? MODES[i- 1] :
MODES[MODES.length – 1];
Mode nextMode = WindowManager.getDefault().findMode(nextModeName);
if (nextMode != null) {
private void jButton2ActionPerformed(java.awt.event.ActionEvent evt) {
private void jButton1ActionPerformed(java.awt.event.ActionEvent evt) {

The static string array contains the names of the most important modes. These modes
can also be identified dynamically, by calling WindowManager.getDefault().

The ActionListener delegates the call to the method changeMode() and gives
the desired back/forward direction. This method determines via WindowManager.
getDefault ().findMode (this) the mode in which the TopComponent is
displayed, as well as the name of the current mode.

The string array is then searched and dockInto(this) is called to dock the
TopComponent into a different mode.

How to revert to the default layout?
As the layout of the NetBeans Platform 6.9 is persisted when the application
shuts down, first perform a Clean and Build on the application project.
With the removal of the build folder, the layout settings are also deleted,
so that the default layout is used when the application starts again.

Using the two buttons, you can let the TopComponent be docked in some of the most
commonly used modes (as shown in the screenshot below).

You have programmatically docked a TopComponent into various places within
the available modes in the application. In the process, you have learned how
TopComponents can be docked dynamically, that is, at runtime, into desired
positions. Both the declarative and the programmatic approaches to docking
should now be familiar to you.

Creating custom modes

You can get quite far with the standard modes provided by the NetBeans
Platform. Still, sometimes you may need to provide a custom mode, to provide
a new position for the TopComponents within the application. A custom mode is
created declaratively in XML files, rather than programmatically in Java code.

In the following example, you create two new modes that are positioned side by side
in the lower part of the application using a specific location relative to each other.

  1. Create a new module named CustomModes, with Code Name Base com.
    netbeansrcp.custommodes, within the existing WindowSystemExamples

  2. Right-click the module project and choose New | Other to open the
    New File dialog. Then choose Other | Empty File, as shown in the
    following screenshot:

  3. Type mode1.wsmode as the new filename and file extension, as shown in the
    following screenshot. Click Finish.

  4. Define the content of the new mode1.wsmode as follows:

  5. <?xml version=”1.0″ encoding=”UTF-8″?>
    “-//NetBeans//DTD Mode Properties 2.3//EN”
    <mode version=”2.3″>
    <name unique=”mode1″ />
    <kind type=”view” />
    <state type=”joined” />
    <path orientation=”vertical” number=”20″ weight=”0.2″/>
    <path orientation=”horizontal” number=”20″ weight=”0.5″/>

  6. Create another file to define the second mode and name it mode2.wsmode.
    Add this content to the new file:

  7. <?xml version=”1.0″ encoding=”UTF-8″?>
    “-//NetBeans//DTD Mode Properties 2.3//EN”
    <mode version=”2.3″>
    <name unique=”mode2″ />
    <kind type=”view” />
    <state type=”joined” />
    <path orientation=”vertical” number=”20″ weight=”0.2″/>
    <path orientation=”horizontal” number=”40″ weight=”0.5″/>

Via th e two wsmode files described above, you have defined two custom modes.
The first mode has the unique name mode1, with the second named mode2. Both
are created for normal TopComponents (view instead of editor) that are integrated
into the main window, rather than being undocked by default (joined instead
of separated).

The constraints elements in the files are comparable to GridBagLayout, with a
relative horizontal and vertical position, as well as a relative horizontal and vertical
weight. You place mode1 in position 20/20 with a weighting of 0,5/0,2, while
mode2 is placed in position 20/40 with the same weighting.

If all the other defined modes have TopComponents opened within them, the
TopComponents in the two new modes should lie side by side, right above the status
bar, taking up 20% of the available vertical space, with the horizontal space shared
between them.

  1. Let us now create two new TopComponents and register them in the
    layer.xml file so that they will be displayed in your new modes. Do this
    by using the New Window wizard twice in the CustomModes module, first
    creating a window called Class Name Prefix Red and then a window with
    Class Name Prefix Blue.

  2. What should iset the window position to?
    In the wizard, in both cases, it does not matter what you
    set to be the window position, as you are going to change
    that setting manually afterwards. Let both of them open
    automatically when the application starts.

  3. In the Design mode of both TopComponents, add a JPanel to each of the
    TopComponents. Change the background property of the panel in the
    RedTopComponent to red and in the BlueTopComponent to blue.

  4. Edit the layer.xml of CustomModes module, registering the two
    .wsmode files and ensuring that the two new TopComponents open
    in the new modes:

  5. <folder name=”Windows2″>
    <folder name=”Components”>
    <file name=”BlueTopComponent.settings”
    <file name=”RedTopComponent.settings”
    <folder name=”Modes”>
    <file name=”mode1.wsmode” url=”mode1.wsmode”/>
    <file name=”mode2.wsmode” url=”mode2.wsmode”/>
    <folder name=”mode1″>
    <file name=”RedTopComponent.wstcref”
    <folder name=”mode2″>
    <file name=”BlueTopComponent.wstcref”

  6. As before, perform a Clean and Build on the application project node
    and then start the application again. It should look as shown in the
    following screenshot:

In the summary, you defined two new modes in XML files and registered them in
the module’s layer.xml file. To confirm that the modes work correctly, you use the
layer.xml file to register two new TopComponents so that they open by default into
the new modes. As a result, you now know how to extend the default layout of a
NetBeans Platform 6.9 application with new modes.

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!