#Window Undocking

This feature allows you to undock (or pop-out) a Swing window outside the current document and open it in a new browser window. You can also dock the window back to its original browser window.

For a more detailed example, please see our demo application SwingSet3 and the Windows demo.

#Setup

To be able to use this feature you need to enable the Compositing Window Manager feature first (CWM). You can change the Docking Mode settings in the application configuration:

• ALL - all windows can be undocked
• MARKED - only windows (JFrame, JWindow, JDialog, ..) that implement Dockable interface can be undocked (see below)
• NONE - disable undocking

#WebswingApi

There are 2 methods in WebswingApi to support undocking:

/**
 * Is docking enabled for window?
 * Compositing window manager and docking mode in config must be enabled.
 */
public boolean isDockingEnabled(Window window);
    
/**
 * Toggle the dock state of a window.
 * Compositing window manager must be enabled in config. Window must be allowed to change the dock state according to config.
 * @throws IllegalArgumentException if isCompositingWindowManager() or isDockingEnabled(window) returns false
 */
public void toggleWindowDock(Window window);

• isDockingEnabled - check whether the window is able to change the dock state

• toggleWindowDock - toggles the window dock state, note that it is not possible to tell if the window is docked or undocked using this API

#Dockable interface

The new Dockable interface provided by webswing-api library allows you to mark a window class that should allow undocking. In addition you can force the instances of the class to auto-undock when opened.

See example below:

public class DockableFrame extends JFrame implements Dockable {        
    public DockableFrame(String title) {
        super(title);
    }
    
    @Override
    public boolean isAutoUndock() {
        return true;
    }    
};

#Javascript API

To use the javascript API please refer to CWM documentation to see how you setup CWM window listeners. Using the listeners and/or Webswing instance variable you can access the window objects.

If a window supports docking you can use these javascript functions on the window object to change its dock state:

• undock() - undocks the window, in case it is docked and undock is supported
• dock() - docks the window back to its original document, in case it is undocked
• toggleDock() - toggles the dock state of window, in case undock is supported

To check the dock state use these functions:

• getDockState() - returns the current dock state of the window - docked, undocked
• getDockMode() - returns the current dock mode of the window - none (not possible to undock), dockable (possible to undock/dock), autoUndock (possible to undock/dock and undocks on open)

#Window decoration button

If a window supports docking/undocking, you will see a new button in the window decoration.

You can change the button visual in your xfwm theme by overriding shade button. If you are missing the shade button in your theme you have to create 2 button files - shade-active.xpm and shade-inactive.xpm.

#Changing dock state

There are multiple ways to change the dock state of a window:

• using WebswingApi.toggleWindowDock() method in your application code
• by implementing the Dockable interface, window will undock on first open
• using javascript API - win.dock(), win.undock(), win.toggleDock()
• clicking the dock/undock toggle button in window decoration

#Usage

There are a few caveats to this feature.

If you undock a window, you cannot minimize its original browser window. If you do so, you will see a warning overlay which restricts you from further interaction.

If there is a modal window that blocks other windows and there are any undocked windows, you will also see a warning overlay which tells you to pay attention to the modal window.

If you close the undocked window with browser close button, it will do the same action as if you clicked the close button on the swing window. It will close and not dock to its original location. When you exit your application, it will close any undocked browser windows too.

It is not possible to use this feature in touch mode, i.e. on touch devices.

This feature is not available in Internet Explorer.