# Events Package of the VLDocking Framework.

This package contains event and listeners classes of the docking framework.

There are two types of events :

- Drag and Drop events, used for docking processing.
- State-change event, used for notifications.

## Drag and Drop events

Those events are used by the docking framework to process Docking operations.

They shoud not be used by User Applications, only by API extenders.

This category contains :

- DockEvent : the ancestor
- DockDragEvent : an event transmitted to DockDropReceivers in order to know if Drag is allowed and which shape should be drawn.
- DockDropEvent : when a DockDragEvent is accepted, and mouse button released, a DockDropEvent is transmitted to a DockDropReceiver. It is its responsibility to call the appropriate methods of DockingDesktop in order to change the docking position of the dragged component.

## DockableState events

Those events are used for notification purpose, in order to allow the User Application to track configuration changes on the docking desktop.

Note : there are 3 states :

- docked : component is visible on the docking desktop
- hidden : iconified in an auto-hide border of the docking desktop
- closed : not visible

A state change is triggered only when a Dockable changes of state.
Keep in mind that multiple changes of docking position do not trigger multiple state change events (only the initial docking triggers the event).

This category contains :

- DockableStateWillChangeEvent : a vetoable state change is triggered before state change (for example before a docked component is closed).
  The User application can cancel the event to veto the change.
- DockableStateChangeEvent : a non-vetoable state change is triggered after the state change (for example, after a hidden component is closed), in order to let the user application know about the state change.

The workflow of event delivering is the following

      Dockable in state S1 (docked/hidden/closed)

       "stateChange" requested
          event manager : triggers DockableStateWillChangeEvents
          if (event.isAccepted()){
            process state change
            ...
            Dockable in state S2 != S1 (docked/hidden/closed)
            event manager : triggers DockableStateChangeEvents

          } // else don't change state