Geertjan's Blog

  • October 16, 2006

New Banner Mode for NetBeans IDE

Geertjan Wielenga
Product Manager
In NetBeans terminology, a "mode" is a position in a NetBeans platform application. (NetBeans IDE is one example of a NetBeans Platform application.) When you use the Window Component wizard to create a new TopComponent, the very first thing you're asked is the position where the TopComponent should be displayed. For example, there's an "editor" mode, which is where the Source Editor is found, there's an "explorer" mode, where the Projects window and Files window are found, and so on. But what if the position that you want isn't available? Someone on dev@openide.netbeans.org asked this question yesterday—they wanted to put a TopComponent right across the application, from the left side to the right side, at the top of the main window, right below the toolbar. Kind of a "banner" position. Such a "mode" does not exist, but it seemed like an interesting thing to investigate. At the end of it all, I managed to create this new "banner" mode. Here's the result:

The screenshot is at least slightly misleading—the Google part (i.e., the TopComponent in the "banner" mode) is nothing more than a screenshot attached to a JLabel. :-)

I did little more than adapt the sample that you can get from this location in the NetBeans sources:


There are other samples you can find in platform/samples, also other ones that relate to the window system.

A couple of small tips and tricks for when you're working on this part of your application:

  1. Use the Window Component wizard to create your TopComponent. Then run the application. Then move all the windows around, including your new one, until you have everything exactly where you want it. At this point, you're designing the layout of your application.

  2. Next, close the application. A lot of files are now generated (i.e., when you close the application) in the application's user directory (in config/Windows2Local). Go to your user directory and do two different things:

    • For your own new TopComponent, copy the contents of the settings, wsmode, and wstcref files into files of the same name in the same folder structure in your application as you find in the user directory:

      This folder and file structure should be reflected in your XML layer. In the above case, my XML layer looks as follows:

      <folder name="Windows2">
      <folder name="Components">
      <file name="test02tc00.settings" url="components/test02tc00.settings"/>
      <folder name="Modes">
      <file name="testmode.wsmode" url="modes/testmode.wsmode"/>
      <folder name="testmode">
      <file name="test02tc00.wstcref" url="modes/testmode/test02tc00.wstcref"/>

      Because I set the above folder and files in my XML layer, the various files were generated in the user directory when the application was closed. Then I created files in my module and copied the content from the user directory. Because the files in the user directory reflected the position of the windows when the application closed, they were optimized for my desired layout. In effect, when you're performing this task, you're treating the IDE as a layout designer for your application.

      Also make sure that your TopComponent has a matching preferredID() return value:

      private static final String TC_ID = "test02tc00";
      protected String preferredID () {
      return TC_ID;

      The files that the application generated in the user directory reflect the status of the windows at the time the application closed. Assuming that's how you want them to be when the application starts up, you need to copy the content of abovementioned files for your new TopComponent into the files in your own module. Note that I'm not using XML files, but that would be the preferable approach (makes it possible to validate and gives you syntax highlighting).

    • For other TopComponents (i.e., windows in other modes), find the relevant file in the Important Files > XML Layer > <this layer in context> node. Then copy the content of the generated file into that file that you found. For example, the Favorites window is closed by default. If you want it to be open by default, go to Windows2/Modes/explorer/favorites.wstcref and change the state-opened element from false to true. Similarly, find the other windows and switch false to true (or the other way round) until all those that you want open are open and those that should be closed are closed. In this way, you can set the initial positions of windows that come from other modules. Any module can be handled this way, so you have a lot of influence over other people's contributions to your application. Also see the NetBeans IDE 5.x HTML Editor Tutorial, where the Favorites window is switched from hidden to shown on start up.

There's a lot more that could be said on this subject, but this is all you need to get started. And this is one reason why "banner" mode might be interesting:

In other news. Interested in Grails? Check out the Grails community's IDE Integration Wish List. Anyone out there interested in checking off some of these items by creating support for Grails?

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.