dockable.java

定要上载质量高而定要上载质量高而定要上载质量高而定要上载质量高而定要上载质量高而

/*
 * Copyright (c) 2004 Christopher M Butler
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
package org.flexdock.docking;

import java.awt.Component;
import java.beans.PropertyChangeListener;
import java.util.List;
import java.util.Set;

import org.flexdock.docking.event.DockingListener;
import org.flexdock.docking.event.DockingMonitor;
import org.flexdock.docking.props.DockablePropertySet;

/**
 * This interface is designed to specify the API's required by
 * {@code DockingManager} and {@code DockingPort} for dealing with dockable
 * components in a drag-n-drop fashion. A {@code Dockable} is the child
 * component that is docked into a {@code DockingPort}.
 * 
 * @author Christopher Butler
 */
public interface Dockable extends DockingListener, DockingMonitor {

    /**
     * A constant property key to signify that a component is dockable. 
     */
    String DOCKABLE_INDICATOR = "Dockable.DOCKABLE_INDICATOR";

    /**
     * Returns the value of the property with the specified key. Only properties
     * added with {@code putClientProperty} will return a non-{@code null}
     * value.
     * 
     * @param key
     *            the key that is being queried
     * @return the value of this property or {@code null}
     * @see javax.swing.JComponent#getClientProperty(java.lang.Object)
     */
    Object getClientProperty(Object key);

    /**
     * Returns the Component that is to be dragged and docked. This may or may
     * not be included in the list returned by {@code getDragSources()}.
     * <p>
     * The framework performs indexing on the underlying {@code Component}.
     * Consequently, this method may <b>not</b> return a {@code null}
     * reference.
     * 
     * @return the component wrapped by this dockable.
     */
    Component getComponent();

    /**
     * Returns the DockingPort within which this Dockable is currently docked.
     * If not currently docked, this method will return null.
     * 
     * @return the docking port this dockable resides in, or {@code null} if the
     *         dockable is not currently docked (i.e. in the middle of a drag
     *         operation).
     */
    DockingPort getDockingPort();

    /**
     * Returns a {@code List} of the {@code Components} that are event sources
     * for drag operations. The list may or may not include the Component
     * returned by {@code getComponent()}.
     * 
     * @return a list containing the components that may be used to drag this
     *         dockable.
     */
    List getDragSources();

    /**
     * Returns a {@code Set} of the {@code Components} that are used as frame
     * drag sources. When a {@code Dockable} is floated into an external frame,
     * that frame may or may not have a titlebar for repositioning. The
     * Components returned by this method will be setup with appropriate event
     * listeners such that dragging them will serve to reposition the containing
     * frame as if they were the frame titlebar. If a Component exists in both
     * the Set returned by this method and the List returned by
     * {@code getDragSources()}, the "frame reposition" behavior will supercede
     * any "drag-to-dock" behavior while the Dockable is in a floating state.
     * 
     * @return a set containing the components that may be used to drag the
     *         frame this dockable resides in, if the dockable is floating.
     */
    Set getFrameDragSources();

    /**
     * Returns a {@code String} identifier that is unique within a JVM instance,
     * but persistent across JVM instances. This is used for configuration
     * mangement, allowing the JVM to recognize a {@code Dockable} instance
     * within an application instance, persist the ID, and recall it in later
     * application instances. The ID should be unique within an appliation
     * instance so that there are no collisions with other {@code Dockable}
     * instances, but it should also be consistent from JVM to JVM so that the
     * association between a {@code Dockable} instance and its ID can be
     * remembered from session to session.
     * <p>
     * The framework performs indexing on the persistent ID. Consequently, this
     * method may <b>not</b> return a {@code null} reference.
     * 
     * @return the persistence id for this dockable. This id ensures that only
     *         one copy of a given dockable will exist.
     */
    String getPersistentId();

    /**
     * Adds an arbitrary key/value "client property" to this {@code Dockable}.
     * {@code null} values are allowed.
     * 
     * @param key
     *            the new client property key.
     * @param value
     *            the new client property value; if <code>null</code> this
     *            method will remove the property.
     * @see javax.swing.JComponent#putClientProperty(java.lang.Object,
     *      java.lang.Object)
     */
    void putClientProperty(Object key, Object value);

    /**
     * Returns a {@code DockablePropertySet} instance associated with this
     * {@code Dockable}. Developers implementing the {@code Dockable} interface
     * may or may not choose to provide their own {@code DockablePropertySet}
     * implementation for use with this method. A default implementation is
     * supplied by the framework and most {@code Dockable} implementations,
     * including all implementations provided by the framework, will return the
     * default {@code DockablePropertySet} via a call to
     * {@code org.flexdock.docking.props.PropertyManager}. Developers are
     * encouraged to take advantage of this by calling
     * {@code PropertyManager.getDockablePropertySet(this)}.
     * 
     * @return the {@code DockablePropertySet} associated with this
     *         {@code Dockable} This method may not return a {@code null}
     *         reference.
     * @see org.flexdock.docking.props.DockablePropertySet
     * @see org.flexdock.docking.props.PropertyManager#getDockablePropertySet(Dockable)
     */
    DockablePropertySet getDockingProperties();

    /**
     * Implements the semantics for docking an external {@code Dockable} to this
     * {@code Dockable} and returns a {@code boolean} indicating whether or not
     * the docking operation was successful. <p> The framework already
     * provides a default implementation for this method through
     * {@code DockingManager.dock(Dockable dockable, Dockable parent)}. While
     * users are free to provide their own implementation for this method, the
     * recommended approach is to use the default implementation with the
     * following line: <p> {@code return DockingManager.dock(dockable, this);}
     * 
     * @param dockable
     *            the {@code Dockable} to dock relative to this {@code Dockable}
     * @return {@code true} if the docking operation was successful;
     *         {@code false} otherwise.
     * @see #dock(Dockable, String)
     * @see #dock(Dockable, String, float)
     * @see DockingManager#dock(Dockable, Dockable)
     */
    boolean dock(Dockable dockable);

    /**
     * Implements the semantics for docking an external {@code Dockable} to the
     * specified region of this {@code Dockable} and returns a {@code boolean}
     * indicating whether or not the docking operation was successful. If the
     * docking operation results in a split layout, this method should determine
     * an appropriate ratio of available space to allot to the new sibling
     * {@code Dockable}. <p> The framework already provides a default
     * implementation for this method through
     * {@code DockingManager.dock(Dockable dockable, Dockable parent, String region)}.
     * While users are free to provide their own implementation for this method,
     * the recommended approach is to use the default implementation with the
     * following line: <p>
     * {@code return DockingManager.dock(dockable, this, relativeRegion);}
     * 
     * @param dockable
     *            the {@code Dockable} to dock relative to this {@code Dockable}
     * @param relativeRegion
     *            the docking region into which to dock the specified
     *            {@code Dockable}
     * @return {@code true} if the docking operation was successful;
     *         {@code false} otherwise.
     * @see #dock(Dockable, String, float)
     * @see DockingManager#dock(Dockable, Dockable, String)
     */
    boolean dock(Dockable dockable, String relativeRegion);

    /**
     * Implements the semantics for docking an external {@code Dockable} to the
     * specified region of this {@code Dockable} with the specified layout
     * ratio, returning a {@code boolean} indicating whether or not the docking
     * operation was successful. If the docking operation results in a split
     * layout, this method should use the specified {@code ratio} to determine
     * the amount of available space to allot to the new sibling
     * {@code Dockable}.
     * <p>
     * The framework already provides a default implementation for this method
     * through
     * {@code DockingManager.dock(Dockable dockable, Dockable parent, String region, float proportion)}.
     * While users are free to provide their own implementation for this method,
     * the recommended approach is to use the default implementation with the
     * following line:
     * <p>
     * {@code return DockingManager.dock(dockable, this, relativeRegion, ratio);}
     * 
     * @param dockable
     *            the {@code Dockable} to dock relative to this {@code Dockable}
     * @param relativeRegion
     *            the docking region into which to dock the specified
     *            {@code Dockable}
     * @param ratio
     *            the proportion of available space in the resulting layout to
     *            allot to the new sibling {@code Dockable}.
     * @return {@code true} if the docking operation was successful;
     *         {@code false} otherwise.
     * @see DockingManager#dock(Dockable, Dockable, String, float)
     */
    boolean dock(Dockable dockable, String relativeRegion, float ratio);

    /**
     * Adds a PropertyChangeListener to the listener list. The listener is
     * registered for all bound properties of this class. Note that if this
     * Dockable is inheriting a bound property, then no event will be fired in
     * response to a change in the inherited property.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     * 
     * @param listener
     *            the PropertyChangeListener to be added
     * 
     * @see #removePropertyChangeListener(PropertyChangeListener)
     */
    void addPropertyChangeListener(PropertyChangeListener listener);

    /**
     * Removes a PropertyChangeListener from the listener list. This method
     * should be used to remove PropertyChangeListeners that were registered for
     * all bound properties of this class.
     * <p>
     * If listener is null, no exception is thrown and no action is performed.
     * 
     * @param listener
     *            the PropertyChangeListener to be removed
     * 
     * @see #addPropertyChangeListener
     */
    void removePropertyChangeListener(PropertyChangeListener listener);
}