bibliothek.gui.dock.common.perspective

Class CControlPerspective

java.lang.Object

bibliothek.gui.dock.common.perspective.CControlPerspective

@ClientOnly
public class CControlPerspective
extends Object

A CControlPerspective is a wrapper around a CControl allowing access to various CPerspectives.

Author:

Benjamin Sigg

Constructor Summary

Constructors

Constructor and Description
CControlPerspective(CControlAccess control) Creates a new wrapper

Method Summary

Modifier and Type	Method and Description
DockFrontendPerspective	conversion(CPerspective perspective, boolean includeWorkingAreas) Creates a new DockFrontendPerspective which uses the settings from perspective to read and write layouts.
CPerspective	createEmptyPerspective() Creates a new CPerspective that is set up with all the stations of the CControl.
CControl	getControl() Gets the CControl in whose realm this CControlPerspective operates.
String[]	getNames() Gets the names of all the perspectives that are available.
CPerspective	getPerspective(boolean includeWorkingAreas) Gets a perspective that matches the current layout of the application.
CPerspective	getPerspective(String name) Gets the perspective which represents a layout that was stored using CControl.save(String).
CPerspective	getPerspective(String name, boolean includeWorkingAreas) Gets the perspective which represents a layout that was stored using CControl.save(String).
CPerspective	read(CSetting setting, boolean includeWorkingAreas) Creates a new CPerspective and fills it using the information from setting.
CPerspective	read(DataInputStream in) Creates a new CPerspective using the information stored in in.
CPerspective	read(DataInputStream in, boolean includeWorkingAreas) Creates a new CPerspective using the information stored in in.
CControlPerspectiveBlop	readAll(DataInputStream in) Emulates a call to CControl.read(DataInputStream) and returns all the layouts that are stored in the stream in.
CControlPerspectiveBlop	readAllXML(XElement root) Emulates a call to CControl.readXML(XElement) and returns all the layouts that are stored within root.
CPerspective	readXML(XElement root) Creates a new CPerspective using the information stored in root.
CPerspective	readXML(XElement root, boolean includeWorkingAreas) Creates a new CPerspective using the information stored in root.
void	removePerspective(String name) Deletes the perspective with name name.
void	renamePerspective(String source, String destination) Renames the perspective source to destination.
void	setPerspective(CPerspective perspective, boolean includeWorkingAreas) Changes the layout of the associated CControl such that it matches perspective.
void	setPerspective(String name, CPerspective perspective) Stores perspective as a layout that can be selected by the user by calling CControl.load(String).
void	setPerspective(String name, CPerspective perspective, boolean includeWorkingAreas) Stores perspective as a layout that can be selected by the user by calling CControl.load(String).
CSetting	write(CPerspective perspective, boolean includeWorkingAreas) Converts perspective into a CSetting.
void	write(DataOutputStream out, CPerspective perspective) Writes the contents of perspective into out using the factories provided by this CControlPerspective.
void	write(DataOutputStream out, CPerspective perspective, boolean includeWorkingAreas) Writes the contents of perspective into out using the factories provided by this CControlPerspective.
void	writeXML(XElement root, CPerspective perspective) Writes the contents of perspective into root using the factories provided by this CControlPerspective.
void	writeXML(XElement root, CPerspective perspective, boolean includeWorkingAreas) Writes the contents of perspective into root using the factories provided by this CControlPerspective.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CControlPerspective

public CControlPerspective(CControlAccess control)

Creates a new wrapper

Parameters:

control - the control whose perspectives are modified

Method Detail

getControl

public CControl getControl()

Gets the CControl in whose realm this CControlPerspective operates.

Returns:

the owner of this perspective

createEmptyPerspective

public CPerspective createEmptyPerspective()

Creates a new CPerspective that is set up with all the stations of the CControl. There are no Dockables stored in the new perspective.

Returns:

the new perspective

getPerspective

public CPerspective getPerspective(boolean includeWorkingAreas)

Gets a perspective that matches the current layout of the application.

Parameters:

includeWorkingAreas - whether Dockables that are managed by a working-area should be included in the layout or not

Returns:

the current perspective

getNames

public String[] getNames()

Gets the names of all the perspectives that are available.

Returns:

all the names

getPerspective

public CPerspective getPerspective(String name)

Gets the perspective which represents a layout that was stored using CControl.save(String).

Parameters:

name - the name of the stored layout

Returns:

the perspective or null if name was not found

getPerspective

public CPerspective getPerspective(String name,
                                   boolean includeWorkingAreas)

Gets the perspective which represents a layout that was stored using CControl.save(String).

Parameters:

name - the name of the stored layout

includeWorkingAreas - whether the content of working areas should be included (requires that the layout was saved in the first place)

Returns:

the perspective or null if name was not found

setPerspective

public void setPerspective(CPerspective perspective,
                           boolean includeWorkingAreas)

Changes the layout of the associated CControl such that it matches perspective.

Parameters:

perspective - the perspective to apply, not null

includeWorkingAreas - whether Dockables that are managed by a working-area should be included in the layout or not

setPerspective

public void setPerspective(String name,
                           CPerspective perspective)

Stores perspective as a layout that can be selected by the user by calling CControl.load(String).
The contents of working areas are ignored by this method.

Parameters:

name - the name of the layout

perspective - the new layout, not null

setPerspective

public void setPerspective(String name,
                           CPerspective perspective,
                           boolean includeWorkingAreas)

Stores perspective as a layout that can be selected by the user by calling CControl.load(String).

Parameters:

name - the name of the layout

perspective - the new layout, not null

includeWorkingAreas - whether the contents of working areas should be stored as well

removePerspective

public void removePerspective(String name)

Deletes the perspective with name name.

Parameters:

name - the name of the perspective

renamePerspective

public void renamePerspective(String source,
                              String destination)

Renames the perspective source to destination. If there is already a layout with name destination it will be overridden. This operation works directly on the CControl, already existing CPerspectives will not be affected by invoking this method.

Parameters:

source - the name of the source

destination - the name of the destination

Throws:

IllegalArgumentException - if source does not point to an existing layout

IllegalArgumentException - if either source or destination are null

writeXML

public void writeXML(XElement root,
                     CPerspective perspective)

Writes the contents of perspective into root using the factories provided by this CControlPerspective.

Parameters:

root - the element to write into, not null

perspective - the perspective to write, not null

writeXML

public void writeXML(XElement root,
                     CPerspective perspective,
                     boolean includeWorkingAreas)

Writes the contents of perspective into root using the factories provided by this CControlPerspective.

Parameters:

root - the element to write into, not null

perspective - the perspective to write, not null

includeWorkingAreas - whether the output contains information about children of working areas (includeWorkingAreas = true) or not (includeWorkingAreas = false)

write

public void write(DataOutputStream out,
                  CPerspective perspective)
           throws IOException

Writes the contents of perspective into out using the factories provided by this CControlPerspective.

Parameters:

out - the stream to write into, not null

perspective - the perspective to write, not null

Throws:

IOException - if out is not writeable

write

public void write(DataOutputStream out,
                  CPerspective perspective,
                  boolean includeWorkingAreas)
           throws IOException

Writes the contents of perspective into out using the factories provided by this CControlPerspective.

Parameters:

out - the stream to write into, not null

perspective - the perspective to write, not null

includeWorkingAreas - whether the output contains information about children of working areas (includeWorkingAreas = true) or not (includeWorkingAreas = false)

Throws:

IOException - if out is not writeable

write

public CSetting write(CPerspective perspective,
                      boolean includeWorkingAreas)

Converts perspective into a CSetting.

Parameters:

perspective - the perspective to convert

includeWorkingAreas - whether the children of CWorkingAreas should be stored as well

Returns:

the converted perspective

readAllXML

public CControlPerspectiveBlop readAllXML(XElement root)
                                   throws XException

Emulates a call to CControl.readXML(XElement) and returns all the layouts that are stored within root.

Parameters:

root - the root xml element of a file

Returns:

all the layouts and settings stored in root

Throws:

XException - if root is not well formed

readXML

public CPerspective readXML(XElement root)
                     throws XException

Creates a new CPerspective using the information stored in root. While this method uses the factories provided by this CControlPerspective, the new CPerspective is not registered anywhere. It is the clients responsibility to call setPerspective(String, CPerspective) or setPerspective(CPerspective, boolean) to actually use the result of this method.

Parameters:

root - the element which contains information about a perspective

Returns:

the new perspective

Throws:

XException - if the structure of root is not as expected

readXML

public CPerspective readXML(XElement root,
                            boolean includeWorkingAreas)
                     throws XException

Creates a new CPerspective using the information stored in root. While this method uses the factories provided by this CControlPerspective, the new CPerspective is not registered anywhere. It is the clients responsibility to call setPerspective(String, CPerspective) or setPerspective(CPerspective, boolean) to actually use the result of this method.

Parameters:

root - the element which contains information about a perspective

includeWorkingAreas - whether the perspective contains information about children of working areas (includeWorkingAreas = true) or not (includeWorkingAreas = false). This parameter should have the same value as was used when calling write(DataOutputStream, CPerspective, boolean).

Returns:

the new perspective

Throws:

XException - if the structure of root is not as expected

readAll

public CControlPerspectiveBlop readAll(DataInputStream in)
                                throws IOException

Emulates a call to CControl.read(DataInputStream) and returns all the layouts that are stored in the stream in.

Parameters:

in - the bytes of some layout file

Returns:

all the layouts and settings that can be read from in

Throws:

IOException - if there is a problem reading in or if in is not well formed

read

public CPerspective read(DataInputStream in)
                  throws IOException

Creates a new CPerspective using the information stored in in. While this method uses the factories provided by this CControlPerspective, the new CPerspective is not registered anywhere. It is the clients responsibility to call setPerspective(String, CPerspective) or setPerspective(CPerspective, boolean) to actually use the result of this method.

Parameters:

in - the stream to read data from

Returns:

the new perspective

Throws:

IOException - if in is not readable or in the wrong format

read

public CPerspective read(DataInputStream in,
                         boolean includeWorkingAreas)
                  throws IOException

Creates a new CPerspective using the information stored in in. While this method uses the factories provided by this CControlPerspective, the new CPerspective is not registered anywhere. It is the clients responsibility to call setPerspective(String, CPerspective) or setPerspective(CPerspective, boolean) to actually use the result of this method.

Parameters:

in - the stream to read data from

includeWorkingAreas - whether the perspective contains information about children of working areas (includeWorkingAreas = true) or not (includeWorkingAreas = false). This parameter should have the same value as was used when calling write(DataOutputStream, CPerspective, boolean).

Returns:

the new perspective

Throws:

IOException - if in is not readable or in the wrong format

read

public CPerspective read(CSetting setting,
                         boolean includeWorkingAreas)

Creates a new CPerspective and fills it using the information from setting.

Parameters:

setting - the layout to convert

includeWorkingAreas - whether the layout contains information about children of CWorkingAreas

Returns:

the layout of setting

conversion

@FrameworkOnly
public DockFrontendPerspective conversion(CPerspective perspective,
                                                         boolean includeWorkingAreas)

Creates a new DockFrontendPerspective which uses the settings from perspective to read and write layouts. This method adds CommonSingleDockableFactory, CommonMultipleDockableFactory and CommonDockStationFactory to the perspective.
Clients usually have no need to call this method.

Parameters:

perspective - the perspective whose settings should be used for reading or writing a layout

includeWorkingAreas - whether the contents of working areas should be included in the layout or not

Returns:

the new builder