com.javadocking.dock
Interface Dock

All Known Subinterfaces:

CompositeDock, DockableHider, ExternalizeDock, LeafDock

All Known Implementing Classes:

BorderDock, CompositeGridDock, CompositeLineDock, CompositeTabDock, FloatDock, GridDock, LineDock, SingleDock, SplitDock, TabDock

public interface Dock

A dock is where Dockables can be docked. How a dockable is docked in the dock, depends on the location where the dockable is added.

There are docks that have child docks (CompositeDocks) and there are docks that only contain dockables (LeafDocks). The UI of an application contains tree structures of docks. Every dock has a parent composite dock. The parent composite dock of the root dock is null.

Information on using docks is in How to Use Laef Docks and How to Use Composite Docks in The Sanaware Developer Guide.

A dock can be empty. This means that it doesn't have any dockables docked in it, or it doesn't have any child docks if it is a composite dock. If a dock becomes empty, it should inform the parent composite dock, that it is empty. A parent composite dock can then decide to remove the empty child dock.

A dock can also be full. This means that no dockables can be added. If a composite dock is full, no child docks can be added. This does not necessarily mean that all of its child docks are full!

When a dockable is dragged, depending on the location of the mouse, the dockable can be docked in different ways in the dock. For example, if the location is at the left side of a dock, the dockable can be docked left. if the location is in the center of a dock, the dockable can be docked in the center. Every mouse location has a priority for docking a dockable. The priority constants are defined in Priority.

Author:

Heidi Rakels.

Method Summary

boolean	addDockable(Dockable dockable, java.awt.Point relativeLocation, java.awt.Point dockableOffset) Adds a dockable to this dock.
void	addDockingListener(DockingListener listener) Adds a listener for DockingEvents of this dock.
int	getDockPriority(Dockable dockable, java.awt.Point relativeLocation) Determines if a dockable can be added to this dock at the specified location.
CompositeDock	getParentDock() Gets the parent dock of this dock.
boolean	isEmpty() Determines if this dock doesn't have any dockables docked in it, or doesn't have any child docks docked in it.
boolean	isFull() Determines if any more dockables can be added to this dock.
void	loadProperties(java.lang.String prefix, java.util.Properties properties, java.util.Map childDocks, java.util.Map dockablesMap, java.awt.Window owner) Loads the properties for this dock.
void	removeDockingListener(DockingListener listener) Removes a listener for docking events of this dock.
int	retrieveDockingRectangle(Dockable dockable, java.awt.Point relativeLocation, java.awt.Point dockableOffset, java.awt.Rectangle rectangle) Sets the given rectangle to the position and size of the graphical content component of the dockable, when it will be docked in this dock.
void	saveProperties(java.lang.String prefix, java.util.Properties properties, java.util.Map childDockKeys) Saves the properties of this dock in the given properties object.
void	setParentDock(CompositeDock parentDock) Sets the specified dock as new parent dock of this dock.

Method Detail

getDockPriority

int getDockPriority(Dockable dockable,
                    java.awt.Point relativeLocation)

Determines if a dockable can be added to this dock at the specified location.

The priority constants are defined in Priority.

If the dockable cannot be added, it returns Priority.CANNOT_DOCK. If a dockable cannot be added to this dock, it is still possible that it can be added to a child dock of this dock, if it is a composite dock.

The higher the integer that is returned, the more this dock wants this dockable to be docked here. Some predefined return values with ascending priority are:

• Priority.CAN_DOCK_AS_LAST
• Priority.CAN_DOCK
• Priority.CAN_DOCK_WITH_PRIORITY
• Priority.CAN_DOCK_WITH_HIGH_PRIORITY

Parameters:

dockable - The dockable that will be added.

relativeLocation - The location where the dockable will be added.

Returns:

The integer that determines the priority for adding the dockable. If the dockable cannot be added, CANNOT_DOCK is returned. The higher the integer, the higher the priority for docking the dockable in this dock.

retrieveDockingRectangle

int retrieveDockingRectangle(Dockable dockable,
                             java.awt.Point relativeLocation,
                             java.awt.Point dockableOffset,
                             java.awt.Rectangle rectangle)

Sets the given rectangle to the position and size of the graphical content component of the dockable, when it will be docked in this dock.

Determines if the dockable can be added to this dock. If the dockable cannot be added, it returns Priority.CANNOT_DOCK and the given rectangle is not changed.

Parameters:

dockable - The dockable that will be added.

relativeLocation - The location where the dockable will be added.

dockableOffset - The mouse location where the dragging started, relatively to the previous dock of the dockable.

rectangle - This rectangle will be set to the location and size of the graphical component of the dockable when it will be docked in this dock. The rectangle is relative to this dock.

Returns:

If the dockable cannot be added, Priority.CANNOT_DOCK is returned, otherwise a positive integer.

addDockable

boolean addDockable(Dockable dockable,
                    java.awt.Point relativeLocation,
                    java.awt.Point dockableOffset)

Adds a dockable to this dock.

First it determines if the dockable can be added with getDockPriority(Dockable, Point). If this method returns CANNOT_DOCK, the dockable is not added.

Parameters:

dockable - The dockable that will be added.

relativeLocation - The location where the dockable will be added.

dockableOffset - The mouse location where the dragging started, relatively to the previous dock of the dockable.

Returns:

True if the dockable was added to this dock, false otherwise.

isEmpty

boolean isEmpty()

Determines if this dock doesn't have any dockables docked in it, or doesn't have any child docks docked in it.

Returns:

True if this dock doesn't have any dockables docked in it, or doesn't have any child docks docked in it, false otherwise.

isFull

boolean isFull()

Determines if any more dockables can be added to this dock.

Returns:

True if any more dockables can be added to this dock, false otherwise.

getParentDock

CompositeDock getParentDock()

Gets the parent dock of this dock.

Returns:

The parent dock of this dock.

setParentDock

void setParentDock(CompositeDock parentDock)

Sets the specified dock as new parent dock of this dock.

Parameters:

parentDock - The parent dock of this dock.

saveProperties

void saveProperties(java.lang.String prefix,
                    java.util.Properties properties,
                    java.util.Map childDockKeys)

Saves the properties of this dock in the given properties object.

The property names for this dock should start with the given prefix.

Parameters:

prefix - The prefix for the property names.

properties - The properties object to which the properties should be added.

childDockKeys - A mapping between the child docks that are already saved and the keys that are used for the save.

• map key: a child dock that is already saved (Dock).
• map value: the key that is used for saving the dock (java.lang.String).

loadProperties

void loadProperties(java.lang.String prefix,
                    java.util.Properties properties,
                    java.util.Map childDocks,
                    java.util.Map dockablesMap,
                    java.awt.Window owner)
                    throws java.io.IOException

Loads the properties for this dock. The properties can be found in the given properties object. The property names for this dock start with the given prefix.

The dockables that should be docked in this dock are added to this dock. They can be found in the given dockables mapping. The docks that should be docked inside this dock are added to this dock. They can be found in the given childDocks mapping.

This method should be called after the empty constructor to create the content of the dock. Don't call this method for a dock that already has a content.

Parameters:

prefix - The prefix of the names of the properties that have been intended for this dock.

properties - The properties object that contains the properties for this dock. It can contain also properties for other objects, but they will have another prefix.

childDocks - A mapping between the dock keys of the child docks that are already loaded and the docks.

• map key: the key that is used for saving the dock (java.lang.String).
• map value: a child dock that is already loaded (Dock).

dockablesMap - A mapping that contains the available dockables.

• map key: the ID of the dockable (java.lang.String).
• map value: the dockable (Dockable).

owner - The owner window of the dock in the dock model (DockModel).

Throws:

java.io.IOException - If an error occures while decoding the properties.

addDockingListener

void addDockingListener(DockingListener listener)

Adds a listener for DockingEvents of this dock. The listener will be informed before and after adding, moving or removing dockables or child docks from this dock.

Parameters:

listener - A docking listener that will be notified when a dockable or child dock is added, moved, or removed.

removeDockingListener

void removeDockingListener(DockingListener listener)

Removes a listener for docking events of this dock.

Parameters:

listener - The docking listener to remove.