Geertjan is a DZone Zone Leader and has posted 468 posts at DZone. You can read more from them at their website. View Full User Profile

Secrets of the NetBeans Window System

  • submit to reddit

Today I learned about some hidden options of the NetBeans Window System. These can't be set via user interface elements in the NetBeans IDE's GUI support for the NetBeans Platform, though maybe they should be. That would aid their discoverability a great deal. These are settings that have been around for years, as far as I know, so are not specific to 6.5. I've tried everything below successfully with NetBeans IDE 6.1.

  1. Animation effects for minimizing/maximizing windows. Either because you like the way windows close/open on the Mac, or because you like cosmetic effects that improve the 'cool factor' of your application, or because you've found that your users minimize their windows and then don't know where they've minimized to... minimize/maximize animations might be useful to you.

    Try this: put the following in the 'netbeans.conf' file (or the xxx.conf file, where xxx is the applicable name for your application) as one of the 'netbeans_default_options':


    Then restart the application and when you minimize/maximize a window, you'll see a small Mac-like effect. It doesn't work perfectly, and is only the start, apparently there is a bit of API code that has already been added to but that hasn't been implemented yet. If you find the above switch unsatisfactory and/or if you want further similar Mac-like effects, you can vote for this new issue that I created around all this today.

  2. Dock any TopComponent into any mode. A mode is a position where a TopComponent can be docked. Modes come in three "kinds" (i.e., "types"): "editor", "view", and "sliding". TopComponents that dock into an "editor" mode are, for example, the editor documents in the IDE. They can't be minimized into a "sliding" mode and then can't be dragged/dropped into a "view" mode. Try it. For example, try and open a Java source file and then drag the editor document that represents the source file into the Projects window. When you drop it, the editor document will return to the "editor" mode. However, if you drag the Properties window into the Projects window, it will stay there because both are TopComponents that have been assigned to a "view" mode. (The reverse is true too: try drag/drop the Properties window into an editor document and you'll see that on the drop the editor document will return from whence it came instead of being dropped into the editor document's mode.) That's because the Projects window and the Properties window are "view" TopComponents, while the editor document is an "editor" TopComponent.

    However, if you add this to a TopComponent's constructor, the user will be able to drag that particular TopComponent into any mode, regardless of what kind of TopComponent it is and regardless of the mode the user is dragging it into. Be careful if you set this and make sure that you really want the user to be able to do that. I.e., if your application is some kind of editor, do you really want the user to drag an editor document into the Output window, for example? So, just make sure you don't end up with unintended effects. Nevertheless, if this is something you really want, here's what you need to add to the TopComponent's constructor:

    putClientProperty("TopComponentAllowDockAnywhere", Boolean.TRUE);

    Again, if you set the above property in the TopComponent's constructor, then that particular TopComponent will not discriminate as to where the user will be able to drop it.

  3. Open a TopComponent undocked by default. Let's say you have a TopComponent that should be undocked by default. How do you achieve that? Well, for this we need to look at modes again. All the default modes have their state type set to 'joined', as can be seen here in line 6 of the editor mode (you can see the 'kind type', which I referred to in the previous item, in line 5 below):
    <?xml version="1.0" encoding="UTF-8"?>

    <mode version="2.3">
      <name unique="editor" />
      <kind type="editor" />
      <state type="joined" />
      <bounds x="0" y="0" width="0" height="0" />
      <frame state="0"/>
      <active-tc  prev-id="MultiView-java#007Cform#007C_2" />
      <empty-behavior permanent="true"/>

    What you need, if you want a TopComponent to be undocked by default, is for the "state type" of the mode into which it docks to be set to "separated", instead of "joined". In addition, you need to set, in the ".wstcref" file of the TopComponent in question, the mode where the TopComponent will be docked, assuming that the user docks the TopComponent instead of closing it. For that purpose, you have the "previousMode" element in the TopComponent's ".wstcref" file, which is not defined at all by default, but only when the TopComponent is undocked, in order to remember where it should go when it is docked again:

    <tc-ref version="2.2">
        <tc-id id="DemoWindow6TopComponent">
        <state opened="true">
        <previousmode name="leftSlidingSide" index="0"></previousmode>
    So, in the above case, thanks to the "previousmode" element, when the TopComponent is docked, it will dock into the "leftSlidingSide" mode, which is one of the several existing modes that the NetBeans Platform provides by default.

    So, the question is, what must you physically do to create a new mode (one that is "separated", i.e., one that supports undocking), assign that mode to a TopComponent, and then ensure that the above "previousMode" element is set? Doing this XML configuration stuff is a lot less tricky than it might at first seem. First, run your application and then undock the TopComponent which you'd like to have undocked by default. Second, close the application. The correct mode and wstcref file are now created automatically in the application's build/testuserdir/config/Windows2Local folder (open the Files window to see these). The 'anonymous' folders and files are the ones that the NetBeans Platform created on shutdown, signifying that these folders and files are not the standard modes in the application. The content of these files is what you need to include in your application. So, third, in the Projects window, expand the "this layer" node of the layer.xml file and there look in the Windows2 folder. That's where the 'anonymous' content should go. Finally, replace the content in the application with the relevant content in the application's 'build' folder. Then clean, build, and run the application.

    <?xml version="1.0" encoding="UTF-8"?>
    <mode version="2.3">
        <name unique="undockedEditor" />
        <kind type="editor" />
        <state type="separated" />
        <bounds x="50" y="50" width="536" height="436" />
        <frame state="0"/>
        <active-tc  id="DemoWindowTopComponent" />
        <empty-behavior permanent="false"/>

    For example, above you see the definition of a mode called 'undockedEditor'. It's 'state type' is set to 'separated' so that the mode is a 'floating mode', which allows its TopComponents to be undocked by default. Notice also that the 'bounds' element is useful to set the initial size and location of the floating mode. The TopComponents that will dock in this mode will use the initial bounds specified above. In the above case, you can see that the mode will be quite small. And how is the mode assigned to a TopComponent? In the TopComponent's layer file. When you use the 'Window Component wizard' to create the TopComponent, the requisite entries will be created there. Make sure that, if you create your own mode, you check the layer file to make sure that the correct mode (and other supporting files) are being referred to. You can do many other things, such as for example letting a TopComponent be minimized by default and then making it dock into a specific mode by default when the user decides to dock it.

The above are some of the many ways you can give the user more freedom when using your application's window system. You can also limit that freedom, which is one of the main areas where the NetBeans Platform's window system has changed for the upcoming 6.5 release, as explained in detail here. That's it for today! Thanks to Stan Aubrecht, the NetBeans engineer responsible for creating many parts of the window system, for telling me about the above today. And now have fun with the NetBeans window system.

Published at DZone with permission of its author, Geertjan Wielenga.


Tom Wheeler replied on Mon, 2008/09/22 - 1:19pm

Hey, that's pretty clever.  I never considered having a TC undocked by default but it would be quite handy for 3D visualization windows.

Michael Bien replied on Tue, 2008/09/23 - 3:56am

what i really miss is full featured docking for undocked windows (currently you only can "merge" them as tabs). This is esp. interesting for dual head systems, having two windows instead of one main + x floating is far more comfortable.

thank you for the great tips geertjan

Geertjan Wielenga replied on Tue, 2008/09/23 - 8:20am in response to: Tom Wheeler

[quote=twheeler]Hey, that's pretty clever.  I never considered having a TC undocked by default but it would be quite handy for 3D visualization windows.[/quote]

Another context is a welcome screen. The application starts, showing the main window, but in front of the main window a TopComponent appears providing the welcome information, in a 'separated' mode (i.e., one that support undocking) for 'view' components (i.e., so the TopComponent will behave like a modal dialog, unlike the 'editor' components which are non-modal).

By the way, an interesting point to be aware of -- whether a TopComponent is a 'view' (i.e., modal) or 'editor' component (i.e., non-modal) is determined by the mode in which the TopComponent is docked, not by the TopComponent itself.

Andrew Gilmartin replied on Fri, 2009/11/06 - 2:56pm in response to: Michael Bien

I second the request to allow all NetBean windows to be freed so as to better support multiple screens and just liking the way things where before MDI.

Matt Coleman replied on Tue, 2012/04/03 - 4:01am


 thank your for sharing the secrets!!

graphic designer buffalo

Mateo Gomez replied on Wed, 2012/04/04 - 8:04am

i am s doing this in my program from now on

mexican dessert

Jaffa Wify replied on Tue, 2012/04/10 - 7:29am

The graphic elements may be applied to a design, the graphic elements must be originated by means of visual art skills. These graphics are often developed by a graphic designer. Visual arts include works which are primarily visual in nature using anything from traditional media, to photography or computer generated art. Thanks a lot. Regards, website marketing company

Bryan Low replied on Thu, 2013/03/07 - 10:14pm

I have not been visiting this site lately. Was here the last few days and didnt left a comment. I check back again and found more great insights both from you and the guest comments as well. Excellent Post. Keep up the good work! I have bookmarked this site :)

Hillview Peak

Bryan Low replied on Tue, 2013/06/04 - 1:00am

A wonderful and unique lifestyle awaits you. Please see DUO Residences project details and units available for more information. DUO - Click Here

Bryan Low replied on Mon, 2013/06/17 - 1:14am

Great Post. I have not been visiting the site recently. Took a visit again and there were some great comments on the site. Excellent post. Keep up the good work. Fernvale Link EC

Bryan Skyvue replied on Wed, 2013/09/25 - 6:53am

Jurong West EC is also a short drive to Pan Island Expressway(PIE) The development  is also near to Chinese Garden, Japanese Garden and many shopping centres and entertainment outlets at Jurong East such as Superbowl Jurong and Snowcity. Jurong West EC

Uchenna Ani-Okoye replied on Tue, 2014/09/02 - 7:06am

I studied visualization at university before shifting to web architecture, which is a combination of designing websites, like Compuchenna and film production. This does interest me a great deal, I think it's something I may want to move back into.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.