netbeans.apache.org/src/content/wiki/DevFaqWindowsWstcrefAndFriends.asciidoc - netbeans-website - Git at Google

 //
 //     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.
	//
	// 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.