netbeans.apache.org/src/content/wiki/DevFaqCustomizeWindowSystem.asciidoc

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

= DevFaqCustomizeWindowSystem
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqCustomizeWindowSystem
:description: Apache NetBeans wiki DevFaqCustomizeWindowSystem
:toc: left
:toc-title:
:syntax: true

When developing an application based on NetBeans platform there's sometimes need to tweak the Window System for your target users. Here's a couple of tips how to use various switches and options.

==== Use own JFrame instance as the main window

It is possible to use any JFrame instance as the main window. Simply create the instance when your module is being loaded (link:http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/ModuleInstall.html#restored()[ModuleInstall.restored()]) and set its name to _NbMainWindow_. When the window system loads it will pick this instance and initialize it with menu bar, status bar, toolbars, inner desktop hierarchy etc.

==== Mixing document and non-document windows

As of NetBeans 7.1 it is possible to mix document and non-document windows. It means it is possible for example to drag Projects window and drop it next to Java source editor. It is also possible to drag any editor window and dock it next to Project or Output windows.
If you want to turn this feature off and revert to NetBeans 7.0 behavior use _Mix.Editors.And.Views.Enabled_ branding property in _org/netbeans/core/windows/Bundle.properties_ bundle.

==== Paint custom background

Boolean property _NbMainWindow.showCustomBackground_ set to true in link:http://docs.oracle.com/javase/6/docs/api/javax/swing/UIManager.html#getBoolean(java.lang.Object)[UIManager] will make most of main window components transparent. So anything painted to main window root pane will be showing through its toolbars, menu bar, status bar and window borders. Use this property together with custom JFrame instance (see above) to paint custom images on main window background.

==== Turn some features on/off on TopComponent level

When creating a new TopComponent using NetBeans New File wizard you are presented a couple of option to modify window behavior. If you need to customize the behavior of an existing TopComponent or behavior of a TopComponent you don't have sources to just use any of client properties listed below. For example:

[source,java]
----

WindowManager.getDefault().findTopComponent("output").putClientProperty("netbeans.winsys.tc.closing_disabled", Boolean.TRUE);
//nobody can close Output window now!
----

* _netbeans.winsys.tc.closing_disabled_ - user cannot close the window - there is no close button and Close actions in the main menu is disabled. Closing the window by calling link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html#close()[TopComponent.close()] naturally still works.

* _netbeans.winsys.tc.sliding_disabled_ - user cannot minimize the window.

* _netbeans.winsys.tc.undocking_disabled_ - user cannot float the window.

* _netbeans.winsys.tc.dragging_disabled_ - user cannot drag and drop the window to a different location.

* _netbeans.winsys.tc.maximization_disabled_ - user cannot maximize window.

* _netbeans.winsys.tc.keep_preferred_size_when_slided_in_ - by default minimized windows take the whole main window height or width when being shown from minimize bar. Setting this client property to true will force the window system to use TopComponent's preferred size when it is being slided in from the minimize bar.

* _netbeans.winsys.tc.draganddrop_copy_disabled_ - by default it is possible to link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/CloneableTopComponent.html#clone()[clone] a link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/CloneableTopComponent.html[CloneableTopComponent] by dragging its header while holding down CTRL key. To disable such cloning set this client property to true.

==== Turn some features on/off on window system level

If you want to customize features of all windows you can use the following branding properties. (See for example link:DevFaqRenamingMenuItem.asciidoc[here] how NetBeans branding works.)

* _TopComponent.DragAndDrop.Enabled_ - it is not possible to drag and drop any window when set to false.

* _TopComponent.Undocking.Enabled_ - it is not possible to float any window when set to false.

* _TopComponent.Sliding.Enabled_ - it is not possible to minimize any window when set to false.

* _TopComponent.Resizing.Enabled_ - it is not possible to resize any window using the splitter bars when set to false.

* _View.TopComponent.Closing.Enabled_ - it is not possible to close any non-document window when set to false.

* _Editor.TopComponent.Closing.Enabled_ - it is not possible to close any document window when set to false.

* _TopComponent.Maximization.Enabled_ - it is not possible to maximize any window when set to false.

* _Splitter.Respect.MinimumSize.Enabled_ - it is not possible to make any window smaller than its minimum size by dragging its splitter bars  when set to true.

* _WinSys.Open.New.Editors.Docked_ - by default new document windows open next to the last active document window. If the last active document is floating then a new document will open tabbed next to that floating document. When this property is set to true then new documents will always open in the main window even if the last active document was floating.

* _WinSys.DragAndDrop.Sliding.Enabled_ - it is not possible to drag any window and drop it to a minimize bar to minimize it when set to false.

NetBeans version 7.1 introduced a concept of *tab groups*. All windows in the same docking spot form a tab group. For example Projects, Files and Services windows in the top-left corner of the main window belong into the same tab group. User can close/minimize/float the whole tab group with a single mouse gesture or keyboard shortcut. The following branding properties define which tab group actions are (not) enabled.

* _Mode.Closing.Enabled_ - set to false to disable tab group closing.

* _Mode.Sliding.Enabled_ - set false to disable tab group minimization.

* _Mode.View.Undocking.Enabled_ - set to false to disable floating of non-document tab group.

* _Mode.Editor.Undocking.Enabled_ - set to false to disable floating of document tab group.

* _Mode.View.DragAndDrop.Enabled_ - set to false to disable drag and drop of non-document tab group.

* _Mode.Editor.DragAndDrop.Enabled_ - set to false to disable drag and drop of document tab group.

* _TopComponent.Auto.Slide.In.Minimized.Mode.Enabled_ - when set to true then windows that belong to a minimized tab group will open as minimized. When set to false then windows that belong to a minimized tab group will open as docked (unminimized).

==== Customize non-document tabs layout

As of NetBeans 7.1 non-document windows in the same docking spot are organized into a tab group (see also above).

image:71_and_newer.png[title="Tabs in NetBeans 7.1 and newer"]

If you want to revert the tab layout back to the old behavior in NetBeans 7.0 then you must set system property _winsys.stretching_view_tabs_ to true. Window tabs will then stretch to fill the whole width of the docking spot:

image:70_and_older.png[title="Tabs in NetBeans 7.0 and older"]

Please note that tab group actions (close group, float group, move group etc) will still be present in the main menu and in window's context menu. Use the branding propeties above to remove those actions.

== External Link

Up to date list of all Window System related properties and brading options should be available at link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/architecture-summary.html[architecture summary] page.

=== 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/DevFaqCustomizeWindowSystem[http://wiki.netbeans.org/DevFaqCustomizeWindowSystem] , 
that was last modified by NetBeans user Jtulach 
on 2012-01-10T11:22:58Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.