The window system on screen is composed of tabbed areas called "modes" (originally this was intended as "docking mode" as in the way a component is docked into the main window - yes, it’s a lousy name). These correspond to the class org.openide.windows.Mode. In the system filesystem, each Mode is represented by a folder.

At least in theory, a TopComponent can exist in more than one Mode, so there is a one-to-many relationship. The pre-NetBeans 3.6 windowing system had a concept of "workspaces", and a Mode could be opened on multiple workspaces. So instead of putting TopComponents (as represented by the .settings files) into the folders directly, you put those settings files into the Windows2Local/Components folder. And you put a Window System Top Component Reference - or .wstcrf - lovely to pronounce - in the mode folder. It’s like a symbolic link, pointing to the .settings file in the Windows2Local/Components folder via its ID. That way, one TopComponent could be linked to by several `Mode`s.

Mode`s have configuration data too, such as the constraints for where in the main window they should appear - what side, what TopComponent should be selected etc. So for each `Mode defined in Windows2/Modes, there is also a .wsmode file that contains that information.

The system filesystem is read-write - so changed information (for example, the user dragged a tab to a different Mode or opened or closed it) is saved to the user’s settings directory, transparently. On a restart, the saved information will be read in and restored.

So what happens is, if the user changes the position of windows, the selected tab, the splitter positions, etc., then new versions of the .settings, .wsmode or .wstcref files will be saved in the userdir in order to restore the state on restart to how the user had configured it.

One handy way to generate all of those files, rather than doing it by hand, is to just create an action in your module that will open your TopComponent. Run it on a clean userdir, open your TopComponent, and put it where you want it to appear. Shut down. Go into your user dir, and copy the files the IDE persisted into your module. Edit to taste, add references in your module’s layer file (any module that opens a component is a good example - try core/navigation) and voila.

You may want to look at the samples - there are example modules that use all of the declarative window system APIs and file formats.