(For more resources on NetBeans, see here.)

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 application.
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:

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE mode PUBLIC
   "-//NetBeans//DTD Mode Properties 2.3//EN"
   "http://www.netbeans.org/dtds/mode-properties2_3.dtd">
   <mode version="2.3">
   <name unique="mode1" />
   <kind type="view" />
   <state type="joined" />
   <constraints>
   <path orientation="vertical" number="20" weight="0.2"/>
   <path orientation="horizontal" number="20" weight="0.5"/>
   </constraints>
   </mode>

   
   

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

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE mode PUBLIC
   "-//NetBeans//DTD Mode Properties 2.3//EN"
   "http://www.netbeans.org/dtds/mode-properties2_3.dtd">
   <mode version="2.3">
   <name unique="mode2" />
   <kind type="view" />
   <state type="joined" />
   <constraints>
   <path orientation="vertical" number="20" weight="0.2"/>
   <path orientation="horizontal" number="40" weight="0.5"/>
   </constraints>
   </mode>

   
   

   Unlock access to the largest independent learning library in Tech for FREE!

   Get unlimited access to 7500+ expert-authored eBooks and video courses covering every tech area you can think of.

   Renews at $15.99/month. Cancel anytime

   START FREE TRIAL

Via the 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.

   What should I set 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.

2. 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.
3. Edit the layer.xml of CustomModes module, registering the two .wsmode files and ensuring that the two new TopComponents open in the new modes:

   <folder name="Windows2">
   <folder name="Components">
   <file name="BlueTopComponent.settings"
   url="BlueTopComponentSettings.xml"/>
   <file name="RedTopComponent.settings"
   url="RedTopComponentSettings.xml"/>
   </folder>
   <folder name="Modes">
   <file name="mode1.wsmode" url="mode1.wsmode"/>
   <file name="mode2.wsmode" url="mode2.wsmode"/>
   <folder name="mode1">
   <file name="RedTopComponent.wstcref"
   url="RedTopComponentWstcref.xml"/>
   </folder>
   <folder name="mode2">
   <file name="BlueTopComponent.wstcref"
   url="BlueTopComponentWstcref.xml"/>
   </folder>
   </folder>
   </folder>

   
   

4. 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 application with new modes.