bibliothek.gui.dock.control
Interface RemoteRelocator

public interface RemoteRelocator

A remote relocator can be used to perform a drag & drop operation of a Dockable without the need to know more than the Dockable.
The methods of this interface correspond to methods which are used in MouseListener and MouseMotionListener:

init(int, int, int, int, int)	MouseListener.mousePressed(MouseEvent)
drag(int, int, int)	MouseMotionListener.mouseDragged(MouseEvent)
drop(int, int, int)	MouseListener.mouseReleased(MouseEvent)

The names of these three methods correspond to their normal reaction, when only the left mouse button is pressed (or released). When other buttons are pressed, then the behavior of this relocator may change heavily. The relocator might even cancel a drag & drop operation.

The described three methods return a RemoteRelocator.Reaction. A result that is CONTINUE or CONTINUE_CONSUMED means, that the relocator is not yet finished with the operation. Further events have to be sent to the relocator.
If the result is BREAK or BREAK_CONSUMED, then the relocator has finished the operation.
If the result is BREAK_CONSUMED or CONTINUE_CONSUMED, then the relocator has "used up" the event. If the client uses existing MouseEvents to call the methods, then InputEvent.consume() should be invoked.

The described three methods need the (simulated) location of the mouse in relation to the screen (arguments x and y). The methods need also information which buttons are currently pressed (argument modifiers). Have a look at InputEvent.getModifiersEx() to find out, how modifiers has to be encoded.

Clients can safely assume, that the relocator is not interested in events performed after the last button of the mouse is released.
Clients might implement a MouseListener and a MouseMotionListener which are both added to the same Component. The events received by these listeners can be safely and unchecked forwarded to the relocator, as long as the Component represents only one Dockable.
If the Component represents more than one Dockable, then each event should be delivered only to one RemoteRelocator. If that relocator is interested in the event, all other events have to be forwarded to the same relocator, until the relocator is no longer interested in the events. That includes events which would normally be sent to another relocator.
If two relocators are assigned to the same Dockable, then they can substitute each other at any time.
Mixing events with different sources or using different, not substitutable relocators while one relocator is interested in the events, will lead to unspecified behavior.
A drag & drop operation can be canceled in any state by calling cancel(). Afterwards no events have to be sent to the relocator any more (it is not forbidden to send more events).

New RemoveRelocators can be delivered by DockRelocator.createRemote(Dockable).

Author:

Benjamin Sigg

Nested Class Summary

static class

RemoteRelocator.Reaction Tells a caller of a method whether the RemoteRelocator has finished the drag & drop operation or not.

Method Summary

void	cancel() Cancels the current drag & drop operation.
RemoteRelocator.Reaction	drag(int x, int y, int modifiers) This method works on the drag-part of a drag & drop operation.
RemoteRelocator.Reaction	drop(int x, int y, int modifiers) This method works on the drop-part of a drag & drop operation.
RemoteRelocator.Reaction	init(int x, int y, int dx, int dy, int modifiers) This method starts or cancels a drag & drop operation.

Method Detail

init

RemoteRelocator.Reaction init(int x,
                              int y,
                              int dx,
                              int dy,
                              int modifiers)

This method starts or cancels a drag & drop operation. This method simulates a mouse-pressed event.

Parameters:

x - the x-coordinate on the screen, where the (simulated) event occurred

y - the y-coordinate on the screen, where the (simulated) event occurred

dx - the x-coordinate of the mouse on the simulated Component which sent the event, 0 is a good default-value.

dy - the y-coordinate of the mouse on the simulated Component which sent the event, 0 is a good default-value.

modifiers - the state of the mouse, see InputEvent.getModifiersEx().

Returns:

how this remote reacts on the call, see RemoteRelocator.Reaction

drag

RemoteRelocator.Reaction drag(int x,
                              int y,
                              int modifiers)

This method works on the drag-part of a drag & drop operation. This method simulates a mouse-dragged event.

Parameters:

x - the x-coordinate on the screen, where the (simulated) event occurred

y - the y-coordinate on the screen, where the (simulated) event occurred

modifiers - the state of the mouse, see InputEvent.getModifiersEx().

Returns:

how this remote reacts on the call, see RemoteRelocator.Reaction

drop

RemoteRelocator.Reaction drop(int x,
                              int y,
                              int modifiers)

This method works on the drop-part of a drag & drop operation. This method simulates a mouse-released event.
The drag & drop operation may not be finished after an invocation of this method, clients should carefully analyze the resulting RemoteRelocator.Reaction

Parameters:

x - the x-coordinate on the screen, where the (simulated) event occurred

y - the y-coordinate on the screen, where the (simulated) event occurred

modifiers - the state of the mouse, see InputEvent.getModifiersEx().

Returns:

how this remote reacts on the call, see RemoteRelocator.Reaction

cancel

void cancel()

Cancels the current drag & drop operation. No events have to be delivered any more to this relocator.