Secrets of the NetBeans Window System

DZone 's Guide to

Secrets of the NetBeans Window System

· Java Zone ·
Free Resource

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 core.windows 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.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}