What are the various window system file formats like
.wstcref and how do I use them?
Note: These pages are being reviewed.
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
.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.