org.flexdock.docking.floating.policy
Class FloatPolicyManager

java.lang.Object
  extended by org.flexdock.docking.event.DockingListener.Stub
      extended by org.flexdock.docking.floating.policy.FloatPolicyManager
All Implemented Interfaces:
EventListener, DockingListener

public class FloatPolicyManager
extends DockingListener.Stub

This class provides centralized control over the framework's floating behavior. This includes global behavior and behavior local to each individual docking operation.

This class contains a method isGlobalFloatingEnabled() that indicates whether global floating support is enabled. If global floating support is disabled, then the setting governs all docking operations and blocks floating in a global sense. If global floating support is enabled, then floating is allowed or disallowed on an individual operation-by-operation basis through a set of FloatPolicy implementations.

The default setting for global floating support is false. This, however, may be controlled by the system property FLOATING_ALLOWED. If the framework starts up with a case-sensitive String value of "true" for this system property, then global floating support will be turned on by default. Otherwise, global floating support may be modified via setGlobalFloatingEnabled(boolean globalFloatingEnabled).

This class provides methods addPolicy(FloatPolicy policy) and removePolicy(FloatPolicy policy), allowing the user to implement custom behavior to control floating support for individual docking operations on an event-by-event basis. By default, the FloatPolicyManager has a single FloatPolicy installed of type DefaultFloatPolicy.

Author:
Christopher Butler

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.flexdock.docking.event.DockingListener
DockingListener.Stub
 
Field Summary
static String FLOATING_ALLOWED
          Key constant used within the drag context Map to indicate whether floating is allowed for a given drag operation.
static String GLOBAL_FLOATING_ENABLED
          System property key used during framework initialization to determine the default setting for global floating support.
 
Method Summary
 void addPolicy(FloatPolicy policy)
          Adds the specified FloatPolicy to the internal policy collection.
 void dragStarted(DockingEvent evt)
          This method catches DockingEvents per the DockingListener interface at the start of a drag operation and initializes floating support within the the context Map of the drag operation.
 void dropStarted(DockingEvent evt)
          This method catches DockingEvents per the DockingListener interface at the end of a drag operation and determines whether or not to block attempts to float within the docking operation.
static FloatPolicyManager getInstance()
          Returns a singleton instance of the FloatPolicyManager class.
static boolean isFloatingAllowed(Dockable dockable)
          Indicates whether floating is allowed for the specified Dockable.
static boolean isGlobalFloatingEnabled()
          Returns a global setting used to control default framework floating behavior.
 boolean isPolicyFloatingSupported(Dockable dockable)
          Indicates whether floating is allowed for the specified Dockable strictly by checking the installed FloatPolicies.
 void removePolicy(FloatPolicy policy)
          Removes the specified FloatPolicy from the internal policy collection.
static void setGlobalFloatingEnabled(boolean globalFloatingEnabled)
          Sets the global setting used to control default framework floating behavior.
 
Methods inherited from class org.flexdock.docking.event.DockingListener.Stub
dockingCanceled, dockingComplete, undockingComplete, undockingStarted
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FLOATING_ALLOWED

public static final String FLOATING_ALLOWED
Key constant used within the drag context Map to indicate whether floating is allowed for a given drag operation.

See Also:
DragManager.getDragContext(Dockable), Constant Field Values

GLOBAL_FLOATING_ENABLED

public static final String GLOBAL_FLOATING_ENABLED
System property key used during framework initialization to determine the default setting for global floating support.

See Also:
Constant Field Values
Method Detail

getInstance

public static FloatPolicyManager getInstance()
Returns a singleton instance of the FloatPolicyManager class.

Returns:
a singleton instance of the FloatPolicyManager class.

dragStarted

public void dragStarted(DockingEvent evt)
This method catches DockingEvents per the DockingListener interface at the start of a drag operation and initializes floating support within the the context Map of the drag operation. This method retrieves the Dockable for the event via its getDockable() method. It also retrieves the drag context Map for the DockingEvent by invoking its getDragContext() method. This map is the same Map returned by DragManager.getDragContext(Dockable dockable). It then calls isPolicyFloatingSupported(Dockable dockable) for the Dockable and places either Boolean.TRUE or Boolean.FALSE within the drag context Map, caching the value for use throughout the drag operation to avoid successive iterations through the entire installed FloatPolicy collection. The Map-key used is FLOATING_ALLOWED.

Specified by:
dragStarted in interface DockingListener
Overrides:
dragStarted in class DockingListener.Stub
Parameters:
evt - the DockingEvent whose drag context is to be initialized for floating support
See Also:
DockingEvent.getDragContext(), DockingEvent.getDockable(), isPolicyFloatingSupported(Dockable), FLOATING_ALLOWED

dropStarted

public void dropStarted(DockingEvent evt)
This method catches DockingEvents per the DockingListener interface at the end of a drag operation and determines whether or not to block attempts to float within the docking operation.

If evt.isOverWindow() returns true, then the drop operation is over an existing window and will be interpreted as an attempt to dock within the window, not an attempt to float into a new dialog. In this case, this method returns immediately with no action taken.

This method calls isFloatingAllowed(Dockable dockable) using the DockingEvent's Dockable, retrieved from getDockable(). If this method returns false, then the DockingEvent is consumed and this method returns.

If isFloatingAllowed(Dockable dockable) returns true, then the internal FloatPolicy collection is iterated through, allowing each installed FloatPolicy to confirm the drop operation via isFloatDropAllowed(DockingEvent evt). If any of the installed FloatPolicies returns false for isFloatDropAllowed(DockingEvent evt), then the DockingEvent is consumed and the method exits.

If this method completes without the DockingEvent being consumed, then the docking operation will proceed and attempts to float will be allowed.

Specified by:
dropStarted in interface DockingListener
Overrides:
dropStarted in class DockingListener.Stub
Parameters:
evt - the DockingEvent to be examined for floating support
See Also:
DockingEvent.isOverWindow(), DockingEvent.getDockable(), DockingEvent.consume(), isFloatingAllowed(Dockable), FloatPolicy.isFloatDropAllowed(DockingEvent)

isFloatingAllowed

public static boolean isFloatingAllowed(Dockable dockable)
Indicates whether floating is allowed for the specified Dockable. If dockable is null, this method returns false.

This method first calls DragManager.getDragContext(Dockable dockable) to see if a drag operation is in progress. If so, it returns the boolean value contained within the drag context map using the key FLOATING_ALLOWED. If no mapping exists for the specified key, this method returns false.

If no drag operation is currently in progress and no drag context can be found, this method dispatches to isPolicyFloatingSupported(Dockable dockable), which iterates through all installed FloatPolicies to determine whether floating support is allowed.

Parameters:
dockable - the Dockable whose floating support is to be checked
Returns:
true if floating is allowed for the specified Dockable; false otherwise.
See Also:
DragManager.getDragContext(Dockable), getInstance(), isPolicyFloatingSupported(Dockable), FLOATING_ALLOWED

isPolicyFloatingSupported

public boolean isPolicyFloatingSupported(Dockable dockable)
Indicates whether floating is allowed for the specified Dockable strictly by checking the installed FloatPolicies. If dockable is null, this method returns false immediately without checking through the installed FloatPolicies.

This method iterates through all installed FloatPolicies to determine whether floating support is allowed. If any FloatPolicy within the internal collection returns false from its isFloatingAllowed(Dockable dockable) method, this method returns false. Otherwise, this method returns true.

Parameters:
dockable - the Dockable whose floating support is to be checked
Returns:
true if floating is allowed for the specified Dockable; false otherwise.
See Also:
FloatPolicy.isFloatingAllowed(Dockable)

addPolicy

public void addPolicy(FloatPolicy policy)
Adds the specified FloatPolicy to the internal policy collection. This FloatPolicy will now take part in framework determinations as to whether floating should be supported during docking operations. If policy is null, no action is taken.

Parameters:
policy - the FloatPolicy to add to the system
See Also:
removePolicy(FloatPolicy)

removePolicy

public void removePolicy(FloatPolicy policy)
Removes the specified FloatPolicy from the internal policy collection. FloatPolicy will no longer take part in framework determinations as to whether floating should be supported during docking operations. If policy is null or was not previously installed, no action is taken.

Parameters:
policy - the FloatPolicy to remove from the system
See Also:
addPolicy(FloatPolicy)

isGlobalFloatingEnabled

public static boolean isGlobalFloatingEnabled()
Returns a global setting used to control default framework floating behavior. If this method returns false, all floating support for the entire framework is turned off. If this method returns true, then floating support for individual docking operations is deferred to the installed FloatPolicies.

Returns:
true if global floating support is enabled; false otherwise.
See Also:
setGlobalFloatingEnabled(boolean)

setGlobalFloatingEnabled

public static void setGlobalFloatingEnabled(boolean globalFloatingEnabled)
Sets the global setting used to control default framework floating behavior. If globalFloatingEnabled is false, all floating support for the entire framework is turned off. If globalFloatingEnabled is true, then floating support for individual docking operations is deferred to the installed FloatPolicies.

Parameters:
globalFloatingEnabled - true if global floating support is to be enabled; false otherwise.
See Also:
isGlobalFloatingEnabled()