bibliothek.gui.dock.common.perspective
Class CControlPerspective

java.lang.Object
  extended by 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
CControlPerspective(CControlAccess control)
          Creates a new wrapper
 
Method Summary
 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).
The contents of working areas are ignored by this method.
 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 overriden. 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