| // |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License. |
| // |
| |
| = DevFaqWindowsWstcrefAndFriends |
| :jbake-type: wiki |
| :jbake-tags: wiki, devfaq, needsreview |
| :jbake-status: published |
| :keywords: Apache NetBeans wiki DevFaqWindowsWstcrefAndFriends |
| :description: Apache NetBeans wiki DevFaqWindowsWstcrefAndFriends |
| :toc: left |
| :toc-title: |
| :syntax: true |
| |
| === What are the various window system file formats like `.wstcref` and how do I use them? |
| |
| 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 link:DevFaqSystemFilesystem.asciidoc[system filesystem], each Mode is represented by a folder. |
| |
| At least in theory, a link:DevFaqWindowsTopComponent.asciidoc[TopComponent] can exist in more than one link:DevFaqWindowsMode.asciidoc[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 link:DevFaqDotSettingsFiles.asciidoc[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 link:DevFaqDotSettingsFiles.asciidoc[.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 link:DevFaqUserDir.asciidoc[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 link:DevFaqSampleCode.asciidoc[samples] - there are example modules that use all of the declarative window system APIs and file formats. |
| |
| === Apache Migration Information |
| |
| The content in this page was kindly donated by Oracle Corp. to the |
| Apache Software Foundation. |
| |
| This page was exported from link:http://wiki.netbeans.org/DevFaqWindowsWstcrefAndFriends[http://wiki.netbeans.org/DevFaqWindowsWstcrefAndFriends] , |
| that was last modified by NetBeans user Admin |
| on 2009-11-06T16:06:37Z. |
| |
| |
| *NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed. |