bibliothek.gui.dock.common.CGrid Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of docking-frames-common Show documentation
Show all versions of docking-frames-common Show documentation
DockingFrames is an open source Java Swing docking framework, licenced under LGPL 2.1.
This is the same distribution as the original distribution (http://www.docking-frames.org/), only reinstalled in maven
/*
* 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.dock.common;
import bibliothek.gui.Dockable;
import bibliothek.gui.dock.SplitDockStation;
import bibliothek.gui.dock.common.intern.CDockable;
import bibliothek.gui.dock.common.intern.CPlaceholderStrategy;
import bibliothek.gui.dock.common.intern.CommonDockable;
import bibliothek.gui.dock.common.perspective.CControlPerspective;
import bibliothek.gui.dock.station.split.DockableSplitDockTree;
import bibliothek.gui.dock.station.split.SplitDockGrid;
import bibliothek.util.Path;
/**
* A {@link CGrid} is a mechanism to layout a set of {@link CDockable} on
* a {@link SplitDockStation} like the one used in the center of the
* {@link CContentArea} or on the {@link CWorkingArea}. CGrids
* also can register new {@link CDockable}s to a {@link CControl}.
*
* Usage:
* A CGrid consists of a set of entries where each
* entry consists of a set of {@link CDockable}s and a rectangle
* (position= x/y, size=width/height). The rectangle
* tells where the CDockables and how big they are compared to the
* other entries.
* A client first fills a CGrid with such entries. Then the client calls
* {@link CGridArea#deploy(CGrid)}, {@link CWorkingArea#deploy(CGrid)} or
* {@link #toTree()}. This triggers the CGrid to convert its entries
* into a tree of Dockables. This tree can then be given to a
* {@link SplitDockStation}. The CGrid can be trashed after it created
* the tree - changes to the grid will not be forwarded to the tree.
*
* If the CGrid was created using the constructor {@link #CGrid(CControl)},
* then the method {@link CControl#addDockable(SingleCDockable)} or {@link CControl#addDockable(MultipleCDockable)}
* is called for any new {@link CDockable}.
* @author Benjamin Sigg
*
*/
public class CGrid {
/** the internal representation of this grid */
private SplitDockGrid grid = new SplitDockGrid();
/** the control for which this grid is used */
private CControl control;
/**
* Creates a new grid.
* @deprecated Use {@link #CGrid(CControl)} with an argument of null instead. This
* method may be removed in a future release.
*/
@Deprecated
public CGrid(){
// do nothing
}
/**
* Creates a new grid. If {@link CDockable}s is not null, then new {@link CDockable}s
* will be registered at control. While a value of null is valid,
* for most clients a non-null value will be the better choice. Please note that
* some methods will not work if control is null.
* @param control the control where this grid should register new {@link CDockable}s,
* should not be null for most clients
*/
public CGrid( CControl control ){
this.control = control;
}
/**
* Creates and returns a tree which contains the {@link CommonDockable}s
* of this {@link CGrid}. The branches of the tree are put in a way, that
* the boundaries of the {@link CommonDockable}s are respected as good
* as possible.
* @return the contents of this grid as tree
*/
public DockableSplitDockTree toTree(){
return grid.toTree();
}
/**
* Adds a new set of {@link CDockable}s to this grid. The {@link CDockable}s
* are also added to the {@link CControl} of this CGrid.
* @param x the x-coordinate of the dockables
* @param y the y-coordinate of the dockables
* @param width the width of the dockables
* @param height the height of the dockables
* @param dockables a list of {@link SingleCDockable}s and {@link MultipleCDockable}s.
*/
public void add( double x, double y, double width, double height, CDockable... dockables ){
Dockable[] intern = new Dockable[ dockables.length ];
for( int i = 0; i < intern.length; i++ ){
CDockable dockable = dockables[i];
if( control != null ){
if( dockable instanceof SingleCDockable ){
control.addDockable( (SingleCDockable)dockable );
}
else if( dockable instanceof MultipleCDockable ){
if( dockable.getControl() == null ){
control.addDockable( (MultipleCDockable)dockable );
}
}
}
intern[i] = dockable.intern();
}
grid.addDockable( x, y, width, height, intern );
}
/**
* Adds some placeholders for {@link SingleCDockable}s to this {@link CGrid}. This method does not make any checks concerning
* the validity of the placeholders, the placeholders will however be checked once the {@link CGrid} is deployed.
* This method will assume that the {@link CPlaceholderStrategy} is installed and use the method {@link CPlaceholderStrategy#getSingleDockablePlaceholder(String)}
* Please note that placeholders are always placed after the real existing {@link CDockable}s, if
* order is important then clients must use a {@link CControlPerspective} to create the layout.
* to convert the identifiers into placeholders.
* @param x the x-coordinate of the dockables
* @param y the y-coordinate of the dockables
* @param width the width of the dockables
* @param height the height of the dockables
* @param identifiers the identifiers that would be returned by {@link SingleCDockable#getUniqueId()}
* @throws IllegalStateException if this {@link CGrid} does not have access to the a {@link CControl}
*/
public void addSingle( double x, double y, double width, double height, String... identifiers ){
if( control == null ){
throw new IllegalStateException( "This method is only available if the CGrid was constructed with a CControl" );
}
Path[] placeholders = new Path[ identifiers.length ];
for( int i = 0; i < placeholders.length; i++ ){
placeholders[i] = CPlaceholderStrategy.getSingleDockablePlaceholder( control.getRegister().toSingleId( identifiers[i] ) );
}
}
/**
* Adds some placeholders for {@link MultipleCDockable}s to this {@link CGrid}. This method does not make any checks concerning
* the validity of the placeholders, the placeholders will however be checked once the {@link CGrid} is deployed.
* This method will assume that the {@link CPlaceholderStrategy} is installed and use the method {@link CPlaceholderStrategy#getMultipleDockablePlaceholder(String)}
* to convert the identifiers into placeholders.
* Please note that placeholders are always placed after the real existing {@link CDockable}s, if
* order is important then clients must use a {@link CControlPerspective} to create the layout.
* @param x the x-coordinate of the dockables
* @param y the y-coordinate of the dockables
* @param width the width of the dockables
* @param height the height of the dockables
* @param identifiers the identifiers that are used when calling {@link CControl#addDockable(String, MultipleCDockable)}
* @throws IllegalStateException if this {@link CGrid} does not have access to the a {@link CControl}
*/
public void addMulti( double x, double y, double width, double height, String... identifiers ){
if( control == null ){
throw new IllegalStateException( "This method is only available if the CGrid was constructed with a CControl" );
}
Path[] placeholders = new Path[ identifiers.length ];
for( int i = 0; i < placeholders.length; i++ ){
placeholders[i] = CPlaceholderStrategy.getMultipleDockablePlaceholder( control.getRegister().toMultiId( identifiers[i] ) );
}
}
/**
* Adds some placeholders to this {@link CGrid}. This method does not make any checks concerning
* the validity of the placeholders, the placeholders will however be checked once the {@link CGrid}
* is deployed.
* Please note that placeholders are always placed after the real existing {@link CDockable}s, if
* order is important then clients must use a {@link CControlPerspective} to create the layout.
* @param x the x-coordinate of the dockables
* @param y the y-coordinate of the dockables
* @param width the width of the dockables
* @param height the height of the dockables
* @param placeholders the list of new placeholders
*/
public void addPlaceholders( double x, double y, double width, double height, Path... placeholders ){
grid.addPlaceholders( x, y, width, height, placeholders );
}
/**
* Marks dockable as being selected in the stack that
* has the boundaries of x, y, width, height.
* @param x the x coordinate of the stack
* @param y the y coordinate of the stack
* @param width the width of the stack
* @param height the height of the stack
* @param dockable the element to select, not null
* @throws IllegalArgumentException if dockable is not registered at location x/y/width/height
*/
public void select( double x, double y, double width, double height, CDockable dockable ){
grid.setSelected( x, y, width, height, dockable.intern() );
}
/**
* Informs this grid about a horizontal divider that should be inserted
* into the layout. There are no guarantees that the divider really is inserted.
* @param x1 the first x coordinate of the divider
* @param x2 the second x coordinate of the divider
* @param y the y coordinate of the divider
*/
public void addHorizontalDivider( double x1, double x2, double y ){
grid.addHorizontalDivider( x1, x2, y );
}
/**
* Informs this grid about a vertical divider that should be inserted
* into the layout. There are no guarantees that the divider really is inserted.
* @param x the x coordinate of the divider
* @param y1 the first y coordinate of the divider
* @param y2 the second y coordinate of the divider
*/
public void addVerticalDivider( double x, double y1, double y2 ){
grid.addVerticalDivider( x, y1, y2 );
}
}