org.flexdock.docking.floating.policy

## Class FloatPolicyManager

- java.lang.Object
- - org.flexdock.docking.event.DockingListener.Stub
  - - org.flexdock.docking.floating.policy.FloatPolicyManager

- All Implemented Interfaces:
    java.util.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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `FLOATING_ALLOWED` Key constant used within the drag context `Map` to indicate whether floating is allowed for a given drag operation.
    `static java.lang.String` | `GLOBAL_FLOATING_ENABLED` System property key used during framework initialization to determine the default setting for global floating support.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 java.lang.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 java.lang.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()`