com.vlsolutions.swing.docking.ws

Class WSDesktop


public class WSDesktop
extends java.lang.Object

A desktop part of a workpace.

Use this object to define the layout of a DockingDesktop. This layout can be applied later to that desktop through the Workspace.apply(DockingContext ctx) method.

The API is a subset of the one of DockingDesktop : limited to layout building. you can addDockable(), split(), createTab(), addHiddenDockable(), addFloatingDockable(), see these method description for further information.

Node : WSDesktop doens't support layout updates : you should use it to build a layout, but not to move dockables around. (if you add a dockable somewhere, don't add it elsewhere later as removal isn't fully implemented).

In a WSDesktop, dockables are identified by a WSDockKey (a limited version of DockKey) : this is to allow you to create workspaces with dockables that haven't been constructed yet (lazy loading).

Example :

  Workspace w = new Workspace();
  WSDesktop desk = w.getDesktop(0); // gets the default (single) desktop
 // define some dockable keys
  WSDockKey editorKey = new WSDockKey("editor");
  WSDockKey treeKey, tableKey, imgToolKey // other dockable keys

 // now define a workspace layout
  desk.addDockable(editorKey); // initial dockable
  desk.split(editorKey, treeKey, DockingConstants.SPLIT_LEFT, 0.5);  // splitted
  desk.split(treeKey, tableKey, DockingConstants.SPLIT_TOP, 0.7);  // tree is also splitted

  desk.createTab(tableKey, imgToolsKey, 0);  // tableKey is transformed into a tabbed container
 // and that's it
 // ...
 // later
 //
 DockingContext ctx = ... // your real desktop
 w.apply(ctx); // applies the workspace to this desktop
 // now the dektops are loaded as specified in the 'w' workspace
Since:
2.1.2

Field Summary

protected HashMap
tabbedGroups
groups of tabs (used to re-tab autohidden dockable)

Constructor Summary

WSDesktop()
Constructs a WSDesktop with "default" as name
WSDesktop(String desktopName)
Constructs a WSDesktop with a given name

Method Summary

void
addDockable(WSDockKey key)
Adds the first dockable to this desktop.
void
addDockable(WSDockKey compoundDockable, WSDockKey childDockable)
Adds a dockable into a compound dockable
void
addHiddenDockable(WSDockKey dockable, RelativeDockablePosition dockedPosition)
Adds a new dockable (and stores its return-to-docked position)
void
addToTabbedGroup(WSDockKey base, WSDockKey newTab)
Registers a dockable as belonging to a tab group.
void
clear()
removes all information stored into this desktop, which becomes ready to be reused.
void
createTab(WSDockKey baseTab, WSDockKey newTab, int order)
Creates a tab containing baseTab and newTab (if baseTab is already into a Tab, then newTab will just be added at the "order" position.
String
getDesktopName()
Returns the name of this desktop (which must match the name of a real desktop if more than one desktops are used )
void
setDesktopName(String name)
Updates the name of this workspace desktop
void
setFloating(WSDockKey dockable, Rectangle windowRect, RelativeDockablePosition returnPosition)
Adds a new floating dockable
void
setMaximizedDockable(WSDockKey max)
Sets the maximized dockable of this desktop, (or null if no dockable maximized).
void
split(WSDockKey base, WSDockKey newDockable, DockingConstants.Split split, double splitLocation)
Splits a dockable (with a given split location)

Field Details

tabbedGroups

protected HashMap tabbedGroups
groups of tabs (used to re-tab autohidden dockable)

Constructor Details

WSDesktop

public WSDesktop()
Constructs a WSDesktop with "default" as name

WSDesktop

public WSDesktop(String desktopName)
Constructs a WSDesktop with a given name

Method Details

addDockable

public void addDockable(WSDockKey key)
Adds the first dockable to this desktop. This method will fail if called more than once

addDockable

public void addDockable(WSDockKey compoundDockable,
                        WSDockKey childDockable)
Adds a dockable into a compound dockable

addHiddenDockable

public void addHiddenDockable(WSDockKey dockable,
                              RelativeDockablePosition dockedPosition)
Adds a new dockable (and stores its return-to-docked position)

addToTabbedGroup

public void addToTabbedGroup(WSDockKey base,
                             WSDockKey newTab)
Registers a dockable as belonging to a tab group.

It is used to have a memory of grouped (tabbed) dockables in order to keep the group together when dockable are restored from auto-hide mode.

This method is generally called by the tabbed container management, and not directly by the developper.

However, there is a case where calling this method can be usefull : when, at startup, a desktop is built with multiple hidden dockables, and the developper wants them to be grouped in a tab container when they are restored to the desktop.

Parameters:
base - an already tabbed dockable
newTab - a dockable to add to the tab group
Since:
1.1.2

clear

public void clear()
removes all information stored into this desktop, which becomes ready to be reused.

createTab

public void createTab(WSDockKey baseTab,
                      WSDockKey newTab,
                      int order)
Creates a tab containing baseTab and newTab (if baseTab is already into a Tab, then newTab will just be added at the "order" position.

getDesktopName

public String getDesktopName()
Returns the name of this desktop (which must match the name of a real desktop if more than one desktops are used )

setDesktopName

public void setDesktopName(String name)
Updates the name of this workspace desktop

setFloating

public void setFloating(WSDockKey dockable,
                        Rectangle windowRect,
                        RelativeDockablePosition returnPosition)
Adds a new floating dockable
Parameters:
dockable - the dockable to add as floating
windowRect - rectangle defining the window (relative to screen) of the floating dockable
returnPosition - where to put the dockable when returning to the desktop

setMaximizedDockable

public void setMaximizedDockable(WSDockKey max)
Sets the maximized dockable of this desktop, (or null if no dockable maximized).

Don't forget that this dockable MUST ALSO BE in the DOCKED state (added to the desktop in a split, tab or compound node) otherwise the missing restore information will cause unwanted behaviour, or exceptions.


split

public void split(WSDockKey base,
                  WSDockKey newDockable,
                  DockingConstants.Split split,
                  double splitLocation)
Splits a dockable (with a given split location)
Parameters:
base - the dockable to be splitted
newDockable - the new dockable
split - the orientation of split
splitLocation - where the split divisor is (always relative from the top/left dockable, so split(a, b, SPLIT_TOP, 0.1f) and split(a, b, SPLIT_BOTTOM, 0.1f) have the same dividor location (somewhere near the top of the split).

© Copyright 2004-2006 VLSolutions. All Rights Reserved.
www.vlsolutions.com : Java Components - Smart Client Applications