bibliothek.gui.dock.layout.DockConverter Maven / Gradle / Ivy
Show all versions of docking-frames-core Show documentation
/*
* 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) 2008 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.layout;
import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.util.Map;
import bibliothek.gui.DockStation;
import bibliothek.gui.Dockable;
import bibliothek.gui.dock.DockElement;
import bibliothek.gui.dock.DockFactory;
import bibliothek.gui.dock.perspective.PerspectiveDockable;
import bibliothek.gui.dock.perspective.PerspectiveElement;
import bibliothek.gui.dock.station.support.PlaceholderStrategy;
import bibliothek.util.xml.XElement;
/**
* A {@link DockConverter} can store or load content which is related
* to a certain kind of {@link DockElement}.
* The content of an element is first converted in a special intermediate form
* represented by some object of type L. This intermediate object
* can then be written as byte-stream or in xml.
* @author Benjamin Sigg
* @param the kind of {@link DockElement} this converter handles
* @param the kind of {@link PerspectiveElement} that represents D
* @param the kind of data this converter uses as intermediate format
*/
public interface DockConverter {
/**
* Gets the unique name of this converter. Please note that unique identifiers
* starting with "dock." should not be used by clients.
* @return the id
*/
public String getID();
/**
* Gets the layout of element. This method should create
* a new instance of the layout object, that new object should not be
* tied to element in any way. A layout can be living for
* a long period of time and might be used on another dockable
* object.
* @param element the element for which a new layout should be created
* @param children a map containing unique identifiers for the children
* of the element. Children which are not in this map should not be
* stored in the layout.
* The identifiers are in the range from 0 (incl.) to children.size() (excl.). The
* same identifiers will be used as indices by a {@link LocationEstimationMap}. See
* also {@link DockFactory#estimateLocations(Object, LocationEstimationMap)}.
* @return the newly created, independent layout object.
*/
public L getLayout( D element, Map children );
/**
* Gets the layout information that is associated with element.
* The layout information can be any {@link Object}. The only restriction
* of the object is, that the associated {@link DockFactory} understands
* how to read that object.
* @param element the element whose layout information is asked.
* @param children a map providing identifiers for the children of this element. The
* identifiers are in the range from 0 (incl.) to children.size() (excl.),
* the exact same identifiers would be given to {@link DockConverter#getLayout(bibliothek.gui.dock.DockElement, Map)}.
* Is null if the children of this station should be ignored.
* @return the layout information, may be null if this converter does not support perspectives
*/
public L getPerspectiveLayout( P element, Map children );
/**
* Reads the contents of layout and changes the layout of
* element accordingly. This method should remove all
* children from element and add new children.
* @param element the element whose content and children will be rearranged.
* @param layout the new layout of element
* @param children some children, note that the map may not contain all elements
* which were present when the layout was created.
* @param placeholders a strategy to detect invalid placeholders, can be null.
* Factories loading only {@link Dockable}s but no {@link DockStation}s can safely ignore this argument.
*/
public void setLayout( D element, L layout, Map children, PlaceholderStrategy placeholders );
/**
* Reads the contents of layout and changes the layout of
* element accordingly. This method should not add or remove
* children to or from element.
* @param element the element whose properties will be changed
* @param layout the new set of properties
* @param placeholders a strategy to detect invalid placeholders, can be null.
* Factories loading only {@link Dockable}s but no {@link DockStation}s can safely ignore this argument.
*/
public void setLayout( D element, L layout, PlaceholderStrategy placeholders );
/**
* Writes the contents of layout into out.
* @param layout the layout to store
* @param out the stream to write into
* @throws IOException if an I/O-error occurs
*/
public void write( L layout, DataOutputStream out ) throws IOException;
/**
* Writes the contents of layout into element.
* @param layout the layout to store
* @param element an xml-element into which this method should write, the
* attributes of element should not be changed.
*/
public void write( L layout, XElement element );
/**
* Reads a layout from a stream.
* @param in the stream to read from
* @return the new layout, can be null if the layout
* should be discarded
* @param placeholders a strategy to detect invalid placeholders, can be null.
* Factories loading only {@link Dockable}s but no {@link DockStation}s can safely ignore this argument.
* @throws IOException if an I/O-error occurs
*/
public L read( DataInputStream in, PlaceholderStrategy placeholders ) throws IOException;
/**
* Reads a layout from an xml-element.
* @param element the element to read, should not be changed by this
* method.
* @param placeholders a strategy to detect invalid placeholders, can be null.
* Factories loading only {@link Dockable}s but no {@link DockStation}s can safely ignore this argument.
* @return the new layout, can be null if the layout
* should be discarded
*/
public L read( XElement element, PlaceholderStrategy placeholders );
}