bibliothek.gui.DockStation Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of docking-frames-core Show documentation
Show all versions of docking-frames-core Show documentation
${project.name} is base or core library
The newest version!
/*
* Bibliothek - DockingFrames
* Library built on Java/Swing, allows the user to "drag and drop"
* panels containing any Swing-Component the developer likes to add.
*
* Copyright (C) 2007 Benjamin Sigg
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
* Benjamin Sigg
* [email protected]
* CH - Switzerland
*/
package bibliothek.gui;
import java.awt.Component;
import javax.swing.JFrame;
import bibliothek.gui.dock.DockElement;
import bibliothek.gui.dock.DockElementRepresentative;
import bibliothek.gui.dock.DockFactory;
import bibliothek.gui.dock.accept.DockAcceptance;
import bibliothek.gui.dock.action.DockActionSource;
import bibliothek.gui.dock.displayer.DisplayerRequest;
import bibliothek.gui.dock.event.DockStationListener;
import bibliothek.gui.dock.layout.DockableProperty;
import bibliothek.gui.dock.layout.location.AsideRequest;
import bibliothek.gui.dock.station.Combiner;
import bibliothek.gui.dock.station.DockableDisplayer;
import bibliothek.gui.dock.station.StationDragOperation;
import bibliothek.gui.dock.station.StationDropItem;
import bibliothek.gui.dock.station.StationDropOperation;
import bibliothek.gui.dock.station.layer.DockStationDropLayer;
import bibliothek.gui.dock.station.support.PlaceholderList;
import bibliothek.gui.dock.station.support.PlaceholderMap;
import bibliothek.gui.dock.station.support.PlaceholderStrategy;
import bibliothek.gui.dock.title.DockTitle;
import bibliothek.gui.dock.title.DockTitleFactory;
import bibliothek.gui.dock.title.DockTitleManager;
import bibliothek.gui.dock.title.DockTitleRequest;
import bibliothek.gui.dock.title.DockTitleVersion;
import bibliothek.util.Todo;
import bibliothek.util.Todo.Compatibility;
import bibliothek.util.Todo.Priority;
import bibliothek.util.Todo.Version;
/**
* A DockStation is some area (e.g. a {@link Component}) showing
* a set of {@link Dockable}s called "children". The station is free to decide how and if to
* show its children.
* Although a station can take any form, there are some (optional) practices to follow:
*
* - Each {@link Dockable} should be child of a {@link DockableDisplayer}. The displayer will
* paint border and title of the item.
* - This station should be aware of the current {@link DockTheme} and use its factories and delegates whenever possible.
* - Drag and drop is handled by the {@link DockController}. Methods like {@link #canDrag(Dockable)}, {@link #drag(Dockable)},
* {@link #prepareDrop(StationDropItem)} need to be implemented for this. Also {@link #accept(Dockable)}, {@link Dockable#accept(DockStation)},
* {@link Dockable#accept(DockStation, Dockable)} and the {@link DockAcceptance} of the current {@link DockController} should be checked before
* allowing a drag and drop operation.
* - For each child there should be at least one {@link DockTitle}. This station needs to derive a {@link DockTitleVersion} from
* its controller using the {@link DockController#getDockTitleManager() DockTitleManager} and its
* {@link DockTitleManager#registerDefault(String, DockTitleFactory) factory method}. With the {@link DockTitleVersion}-object one
* {@link DockTitleRequest} for each required {@link DockTitle} can be created.
* - One child can be focused. If this station changes the focus it should use {@link DockController#setAtLeastFocusedDockable(Dockable, Component)}.
* - This station should support placeholders. The current {@link PlaceholderStrategy} can be used to convert {@link Dockable}s to placeholders.
* A {@link PlaceholderList} is a good datastructure to store {@link Dockable}s and placeholders at the same time.
* - Additional points where the user can start drag and drop operations can be installed by implementing a {@link DockElementRepresentative}. It
* has to be installed using {@link DockController#addRepresentative(DockElementRepresentative)}.
* - And a new {@link DockFactory} will be required to persistently store the layout of this station.
*
* @author Benjamin Sigg
*/
public interface DockStation extends DockElement{
/**
* Sets the controller of this station. If the station wants to
* show any {@link DockTitle}, then the titles have to be replaced
* by new instances (assuming the controller is really new). The
* title has to get new {@link DockTitleVersion DockTitleVersions} through
* the {@link DockTitleManager} of controller.
* An argument of null means that this station is currently
* not shown.
* @param controller the owner of this station, can be null
*/
public void setController( DockController controller );
/**
* Gets the controller of this station.
* @return the controller or null if no controller is set
* @see #setController(DockController)
*/
public DockController getController();
/**
* Updates the {@link DockTheme} of this station. The new theme
* has to be read from the {@link #getController() controller} of
* this station. If the controller is null, this method
* should return immediately.
* You may use {@link DockUI#updateTheme(DockStation, DockFactory)}
* to implement this method.
*/
public void updateTheme();
/**
* Gets the current theme of this station. The theme can be null,
* but that means that the station is not fully initialized, and might not
* work correct.
* @return the theme of this station or null.
*/
public DockTheme getTheme();
/**
* Gets a list of actions which should be available for the user and
* affect the child dockable.
* @param dockable a child of this station
* @return actions for dockable, can be null
*/
public DockActionSource getDirectActionOffers( Dockable dockable );
/**
* Gets a list of actions which should be available for the user and
* affect dockable. The argument dockable
* can be a child of this station, or a child of any station which is
* below this station.
* @param dockable a child of this station or a child of another station
* which is below this station
* @return actions for dockable or null
*/
public DockActionSource getIndirectActionOffers( Dockable dockable );
/**
* Adds a listener to this station. The station has to invoke the
* methods of the listener such that its requirements are full filled.
* @param listener the listener to add
*/
public void addDockStationListener( DockStationListener listener );
/**
* Removes a listener from this station.
* @param listener the listener to remove
*/
public void removeDockStationListener( DockStationListener listener );
/**
* Tells whether the child dockable is visible or not. Visible
* means that the {@link Dockable#getComponent() component} of dockable
* can be seen by the user. The result must be false if
* this station is not visible.
* @param dockable the child whose visibility-state is questioned
* @return whether dockable is visible or not
* @see #isStationVisible()
* @deprecated use {@link #isChildShowing(Dockable)} instead, this method will be removed in a future release
*/
@Todo( compatibility=Compatibility.BREAK_MAJOR, priority=Priority.ENHANCEMENT, target=Version.VERSION_1_1_3, description="remove this method" )
@Deprecated
public boolean isVisible( Dockable dockable );
/**
* Tells whether the child dockable is visible or not. Visible
* means that the {@link Dockable#getComponent() component} of dockable
* can be seen by the user. The result must be false if
* this station is not visible.
* @param dockable the child whose visibility-state is questioned
* @return whether dockable is visible or not
* @see #isStationVisible()
*/
public boolean isChildShowing( Dockable dockable );
/**
* Tells whether this station is visible or not. For example a station on
* a {@link JFrame} is not visible if the frame is minimized.
* @return whether this station is visible
* @deprecated use {@link #isStationShowing()} instead, this method will be removed in a future release
*/
@Deprecated
@Todo( compatibility=Compatibility.BREAK_MAJOR, priority=Priority.ENHANCEMENT, target=Version.VERSION_1_1_3, description="remove this method" )
public boolean isStationVisible();
/**
* Tells whether this station is visible or not. For example a station on
* a {@link JFrame} is not visible if the frame is minimized.
* @return whether this station is visible
*/
public boolean isStationShowing();
/**
* Gets the number of children.
* @return the number of children on this station
*/
public int getDockableCount();
/**
* Gets the index'th child of this station.
* @param index a value between 0 (incl.) and {@link #getDockableCount()}
* (excl.).
* @return a child of this station
*/
public Dockable getDockable( int index );
/**
* Gets the favorite child of this station. The favorite child is the one
* child which is specially designated for the user. An example: if the
* station behaves like a stack, and only the top child is visible, then
* the favorite child could the the top.
* A result of null indicates that there are no children
* at all, or that there is no favorite child (all children are equal important).
* Stations should not change this property directly, they should call
* {@link DockController#setFocusedDockable(Dockable, boolean)}
* which will then call {@link #setFrontDockable(Dockable)}. Note that the
* DockController itself listens to the DockTitles, and maybe the station
* doesn't need a logic to decide which child is important.
* @return the most important child or null
*/
public Dockable getFrontDockable();
/**
* Sets the most important child. The station should ensure that this child
* is visible (assuming the station itself is visible). Read the
* comment on {@link #getFrontDockable()} how stations can change
* this property.
* @param dockable the new favorite child, can be null
* @see #getFrontDockable()
*/
public void setFrontDockable( Dockable dockable );
/**
* Gets a snapshot of all placeholders that are currently stored in this {@link DockStation}.
* A {@link DockStation} is free in the format it chooses to fill the map. The map is to be
* created with the assumptions that {@link #getDockableCount()} is 0, meaning
* any existing {@link Dockable} gets replaced by its placeholder. The current
* {@link PlaceholderStrategy} should be used to convert {@link Dockable}s to placeholders.
* @return the map of placeholders or null if this station does not support
* placeholders
*/
public PlaceholderMap getPlaceholders();
/**
* Sets an earlier snapshot of the placeholders of this station. This station can assume that
* it currently does not have any children (that {@link #getDockableCount()} is 0).
* This method does nothing if it cannot handle the format or the version of placeholders.
* @param placeholders some set of placeholders
* @throws IllegalStateException if {@link #getDockableCount()} is not equal to 0
*/
public void setPlaceholders( PlaceholderMap placeholders );
/**
* Called by the {@link DockController} of this station to indicate that
* the active-state of title has been changed. This station
* should call the method title.{@link DockTitle#changed(bibliothek.gui.dock.title.DockTitleEvent) changed}
* with an appropriate event. The station may add some additional information
* to this call.
* @param dockable the child whose title is changed
* @param title the changed title, may not be bound
* @param active the new state of the title
*/
public void changed( Dockable dockable, DockTitle title, boolean active );
/**
* Provides a {@link DockTitle} for a child of this station. This method
* must call {@link DockTitleRequest#answer(DockTitle)} to set the result.
* Most {@link DockStation}s won't have the need to implement this method,
* leaving it empty will advice the framework to use another source for
* new {@link DockTitle}s.
* @param request the request to answer, not null
*/
public void requestChildDockTitle( DockTitleRequest request );
/**
* Provides a {@link DockableDisplayer} for a child of this station. This method
* must call {@link DisplayerRequest#answer(DockableDisplayer)} to set the result.
* The usual implementation should be to do nothing.
* @param request the request to answer, not null
*/
public void requestChildDisplayer( DisplayerRequest request );
/**
* Tells whether this station accepts child as a new child,
* or refuses child. The user will not be able to drop
* a {@link Dockable} onto this station if this method returns
* false.
* @param child a {@link Dockable} which may become a child
* @return true if child is accepted
*/
public boolean accept( Dockable child );
/**
* Gets precise information about the location of a child of this station.
* The result of this method could later be used to invoke
* {@link #drop(Dockable, DockableProperty)}.
* @param child a child of this station, this childs location is asked
* @param target an optional hint telling for which dockable the location information
* will be used, can be null. This hint can be used to find a placeholder
* that should be part of the result.
* @return the location
* @see bibliothek.gui.dock.util.DockUtilities#getPropertyChain(DockStation, Dockable)
*/
public DockableProperty getDockableProperty( Dockable child, Dockable target );
/**
* Requests this {@link DockStation} to find a {@link DockableProperty} that is "aside" another
* property. What exactly the meaning of "aside" is, is left to the implementation. Usually
* "aside" means on the same "stack" but with the next higher index.
* The request object contains information about the location whose neighbor is
* searched, about a placeholder that should be used for the new location, and offers methods
* to forward the call to the next {@link DockStation} or {@link Combiner} if there is a
* {@link DockableProperty#getSuccessor() successor}.
* This method should call the answer methods of request with every
* kind of information it finds.
* If this method cannot handle request, then it just has to return without calling
* any of the answer methods.
* @param request information about a location and methods to create the neighbor location
* @see Combiner#aside(AsideRequest)
*/
public void aside( AsideRequest request );
/**
* Prepares this station to get the new child dockable or to move around the known child dockable.
* The station can refuse dockable, in this case this method just returns null.
* There are some constraints:
*
* - This method should use {@link #accept(Dockable)} and {@link Dockable#accept(DockStation)}
* or {@link Dockable#accept(DockStation, Dockable)} to ensure that the desired
* drop-location is valid.
* - The method should use the {@link DockAcceptance} of its controller
* (see {@link DockController#getAcceptance()}) to ensure that the drop/location is valid.
*
* @param dockable information about the dockable that is going to be dropped
* @return an object describing where the {@link Dockable} can be dropped or null if
* no drop operation is possible
*/
public StationDropOperation prepareDrop( StationDropItem dockable );
/**
* Informs this station that a drag and drop operation is in progress and that dockable might
* be removed from this station.
* @param dockable the child that might be removed in the near future
* @return a callback that will be informed when the dockable was removed or the operation canceleled, can be null
*/
public StationDragOperation prepareDrag( Dockable dockable );
/**
* Adds dockable to this station. The station can decide
* by its own where to put dockable.
* @param dockable a new child
*/
public void drop( Dockable dockable );
/**
* Tries to add dockable to this station such that the location
* given by property is matched. If property
* has a {@link DockableProperty#getSuccessor() successor} and points to
* another station, just call the drop-method of this
* child-station. Note that property can be of any type and
* contain invalid information.
* @param dockable the new child
* @param property the location of the child, may be invalid data
* @return true if property could be read
* and dockable was dropped, false
* otherwise.
*/
public boolean drop( Dockable dockable, DockableProperty property );
/**
* Tries to move the child dockable in such a way, that
* {@link DockStation#getDockableProperty(Dockable, Dockable)} would return a
* {@link DockableProperty} that equals property.
* There is no need to give a guarantee that the move successes, and clients
* should always be prepared for the possibility that this {@link DockStation}
* does nothing at all.
* @param dockable a child of this station
* @param property the preferred position of dockable
*/
public void move( Dockable dockable, DockableProperty property );
/**
* Gets a description of all the areas of the screen where this {@link DockStation} can handle a drop event.
* Everytime the mouse is moved or released during a drag & drop operation, this method is called for
* all {@link DockStation}s. The returned {@link DockStationDropLayer}s are then filtered and ordered, the resulting
* order defines the order in which the method {@link #prepareDrop(StationDropItem)} is called.
* @return all the layers of this station, must not be null, must not contain null,
* must not contain the same entry twice. The array or the {@link DockStationDropLayer}s may be modified,
* hence this method should always create new objects.
*/
public DockStationDropLayer[] getLayers();
/**
* Tells whether dockable can be removed from this station or not.
* This method assumes that dockable is a child of
* this station, if not, then the behavior of this method is unspecified.
* Note that the result of this method may not be respected every time,
* it's more a hint for the controller how to act.
* @param dockable a child of this station
* @return true if dockable can be dragged
*/
public boolean canDrag( Dockable dockable );
/**
* Removes a child from this station. This method may be called even
* if {@link #canDrag(Dockable)} returned false.
* Note: clients may need to invoke {@link DockController#freezeLayout()}
* and {@link DockController#meltLayout()} to ensure noone else adds or
* removes Dockables.
* @param dockable the child to remove
*/
public void drag( Dockable dockable );
/**
* Tells whether its possible to replace the child old
* with next where next is not a child of this station.
* @param old a child of this station
* @param next the replacement of next.
* @return true if the replacement is possible
* @throws IllegalArgumentException if next is a child
* of this station
*/
public boolean canReplace( Dockable old, Dockable next );
/**
* Replaces the child old by next which is
* not yet a child of this station. This method should not be
* called if {@link #canReplace(Dockable, Dockable) canReplace} returned
* false.
* @param old a child
* @param next the replacement of old
* @throws IllegalArgumentException if next is a child of
* this station or if old is not a child
*/
public void replace( Dockable old, Dockable next );
/**
* Replaces the child old by next which is
* not yet a child of this station. This method should not be
* called if {@link #canReplace(Dockable, Dockable) canReplace} returned
* false. This method can assume that next was
* a child of old but no longer is.
* @param old a dockable station that is a child of this station
* @param next the replacement of old
* @throws IllegalArgumentException if next is a child of
* this station, if old is not a child or if old
* is not a {@link Dockable}
*/
public void replace( DockStation old, Dockable next );
}