bibliothek.gui.dock.common
Class CControl

java.lang.Object
  extended by bibliothek.gui.dock.common.CControl

public class CControl
extends Object

Manages the interaction between SingleCDockable, MultipleCDockable and the CContentArea.
Clients should call read and write of the ApplicationResourceManager, accessible through getResources(), to store or load the configuration.
Clients which do no longer need a CControl can call destroy() to free resources.

Author:
Benjamin Sigg

Field Summary
static String CONTENT_AREA_STATIONS_ID
          the unique id of the default-CContentArea created by this control
static String EXTERNALIZED_STATION_ID
          the unique id of the station that handles the externalized dockables
static PropertyKey<KeyStroke> KEY_CLOSE
          KeyStroke used to close a CDockable.
static PropertyKey<KeyStroke> KEY_GOTO_EXTERNALIZED
          KeyStroke used to change a CDockable into externalized-state.
static PropertyKey<KeyStroke> KEY_GOTO_MAXIMIZED
          KeyStroke used to change a CDockable into maximized-state.
static PropertyKey<KeyStroke> KEY_GOTO_MINIMIZED
          KeyStroke used to change a CDockable into minimized-state.
static PropertyKey<KeyStroke> KEY_GOTO_NORMALIZED
          KeyStroke used to change a CDockable into normalized-state.
static PropertyKey<KeyStroke> KEY_MAXIMIZE_CHANGE
          KeyStroke used to change a CDockable into maximized-state, or to go out of maximized-state when needed.
 
Constructor Summary
CControl(JFrame frame)
          Creates a new control
CControl(JFrame frame, boolean restrictedEnvironment)
          Creates a new control
CControl(JFrame frame, CControlFactory factory)
          Creates a new control
 
Method Summary
<F extends MultipleCDockable>
F
add(F dockable)
          Adds a dockable to this control.
<F extends SingleCDockable>
F
add(F dockable)
          Adds a dockable to this control.
<F extends MultipleCDockable>
F
add(F dockable, String uniqueId)
          Adds a dockable to this control.
 void add(String id, MultipleCDockableFactory<?,?> factory)
          Adds a factory to this control.
 void addControlListener(CControlListener listener)
          Adds a listener to this control.
 void addDestroyHook(DestroyHook hook)
          Adds a destroy-hook.
 void addResizeRequestListener(ResizeRequestListener listener)
          Adds a ResizeRequestListener to this CControl.
 CContentArea createContentArea(String uniqueId)
          Creates and adds a new CContentArea.
 CWorkingArea createWorkingArea(String uniqueId)
          Creates and adds a new CWorkingArea to this control.
 void delete(String name)
          Deletes a layout that has been stored earlier.
 void destroy()
          Frees as much resources as possible.
 CDockable getCDockable(int index)
          Gets the index'th dockable that is registered in this control
 int getCDockableCount()
          Gets the number of CDockables that are registered in this CControl.
 CContentArea getContentArea()
          Gets the element that should be in the center of the mainframe.
 List<CContentArea> getContentAreas()
          Gets an unmodifiable list of all CContentAreas registered at this control
 CLocation getDefaultLocation()
          Gets the location where CDockables are opened when nothing else is specified.
 CControlFactory getFactory()
          Gets the factory which is mainly used to create new elements for this control.
 CMaximizeBehavior getMaximizeBehavior()
          Gets the currently used maximize-behavior.
<A> A
getProperty(PropertyKey<A> key)
          Gets the value of a property.
 ApplicationResourceManager getResources()
          Grants access to the manager that reads and stores configurations of the common-project.
Clients can add their own ApplicationResources to this manager, however clients are strongly discouraged from removing ApplicationResource which they did not add by themself.
 void handleResizeRequests()
          Informs all ResizeRequestListeners, that the resize request of all CDockables should be processed.
 DockFrontend intern()
          Gets the representation of the layer beneath the facile-layer.
 String[] layouts()
          Gets a list of all layouts that are currently known.
 void load(String name)
          Loads an earlier stored layout.
<A> void
putProperty(PropertyKey<A> key, A value)
          Changes the value of a property.
 void read(DataInputStream in)
          Reads the current and other known layouts from in.
This is the same as calling getResources().readStream( out ).
 void read(File file)
          Reads the current and other known layouts from file.
This is the same as calling getResources().readFile( file ).
 void remove(MultipleCDockable dockable)
          Removes a dockable from this control.
 void remove(SingleCDockable dockable)
          Removes a dockable from this control.
 void removeContentArea(CContentArea content)
          Removes content from the list of known contentareas.
 void removeControlListener(CControlListener listener)
          Removes a listener from this control.
 void removeDestroyHook(DestroyHook hook)
          Removes a destroy-hook from this CControl.
 void removeResizeRequestListener(ResizeRequestListener listener)
          Removes a ResizeRequestListener from this CControl.
 void save(String name)
          Stores the current layout with the given name.
 void setDefaultLocation(CLocation defaultLocation)
          Sets the location where CDockables are opened when there is nothing else specified for these CDockables.
 void setMaximizeBehavior(CMaximizeBehavior behavior)
          Sets the CMaximizeBehavior.
 void setTheme(DockTheme theme)
          Sets the theme of the elements in the realm of this control.
 void write(DataOutputStream out)
          Writes the current and all known layouts into out.
This is the same as calling getResources().writeStream( out ).
 void write(File file)
          Writes the current and all known layouts into file.
This is the same as calling getResources().writeFile( file ).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

KEY_MAXIMIZE_CHANGE

public static final PropertyKey<KeyStroke> KEY_MAXIMIZE_CHANGE
KeyStroke used to change a CDockable into maximized-state, or to go out of maximized-state when needed.


KEY_GOTO_MAXIMIZED

public static final PropertyKey<KeyStroke> KEY_GOTO_MAXIMIZED
KeyStroke used to change a CDockable into maximized-state.


KEY_GOTO_NORMALIZED

public static final PropertyKey<KeyStroke> KEY_GOTO_NORMALIZED
KeyStroke used to change a CDockable into normalized-state.


KEY_GOTO_MINIMIZED

public static final PropertyKey<KeyStroke> KEY_GOTO_MINIMIZED
KeyStroke used to change a CDockable into minimized-state.


KEY_GOTO_EXTERNALIZED

public static final PropertyKey<KeyStroke> KEY_GOTO_EXTERNALIZED
KeyStroke used to change a CDockable into externalized-state.


KEY_CLOSE

public static final PropertyKey<KeyStroke> KEY_CLOSE
KeyStroke used to close a CDockable.


EXTERNALIZED_STATION_ID

public static final String EXTERNALIZED_STATION_ID
the unique id of the station that handles the externalized dockables

See Also:
Constant Field Values

CONTENT_AREA_STATIONS_ID

public static final String CONTENT_AREA_STATIONS_ID
the unique id of the default-CContentArea created by this control

See Also:
Constant Field Values
Constructor Detail

CControl

public CControl(JFrame frame)
Creates a new control

Parameters:
frame - the main frame of the application, needed to create dialogs for externalized CDockables

CControl

public CControl(JFrame frame,
                boolean restrictedEnvironment)
Creates a new control

Parameters:
frame - the main frame of the application, needed to create dialogs for externalized CDockables
restrictedEnvironment - whether this application runs in a restricted environment and is not allowed to listen for global events.

CControl

public CControl(JFrame frame,
                CControlFactory factory)
Creates a new control

Parameters:
frame - the main frame of the application, needed to create dialogs for externalized CDockables
factory - a factory which is used to create new elements for this control.
Method Detail

addControlListener

public void addControlListener(CControlListener listener)
Adds a listener to this control.

Parameters:
listener - the new listener

removeControlListener

public void removeControlListener(CControlListener listener)
Removes a listener from this control.

Parameters:
listener - the listener to remove

destroy

public void destroy()
Frees as much resources as possible. This CControl will no longer work correctly after this method was called.


createWorkingArea

public CWorkingArea createWorkingArea(String uniqueId)
Creates and adds a new CWorkingArea to this control. The area is not made visible by this method.

Parameters:
uniqueId - the unique id of the area
Returns:
the new area

createContentArea

public CContentArea createContentArea(String uniqueId)
Creates and adds a new CContentArea.

Parameters:
uniqueId - the unique id of the new contentarea, the id must be unique in respect to all other contentareas which are registered at this control.
Returns:
the new contentarea
Throws:
IllegalArgumentException - if the id is not unique
NullPointerException - if the id is null

removeContentArea

public void removeContentArea(CContentArea content)
Removes content from the list of known contentareas. This also removes the stations of content from this control. Elements aboard the stations are made invisible, but not removed from this control.

Parameters:
content - the contentarea to remove
Throws:
IllegalArgumentException - if the default-contentarea equals content

getContentAreas

public List<CContentArea> getContentAreas()
Gets an unmodifiable list of all CContentAreas registered at this control

Returns:
the list of contentareas

getFactory

public CControlFactory getFactory()
Gets the factory which is mainly used to create new elements for this control.

Returns:
the factory

addDestroyHook

public void addDestroyHook(DestroyHook hook)
Adds a destroy-hook. The hook is called when this CControl is destroyed through destroy().

Parameters:
hook - the new hook

removeDestroyHook

public void removeDestroyHook(DestroyHook hook)
Removes a destroy-hook from this CControl.

Parameters:
hook - the hook to remove

getResources

public ApplicationResourceManager getResources()
Grants access to the manager that reads and stores configurations of the common-project.
Clients can add their own ApplicationResources to this manager, however clients are strongly discouraged from removing ApplicationResource which they did not add by themself.

Returns:
the persistent storage

putProperty

public <A> void putProperty(PropertyKey<A> key,
                            A value)
Changes the value of a property. Some properties are:

Type Parameters:
A - the type of the value
Parameters:
key - the name of the property
value - the new value, can be null

getProperty

public <A> A getProperty(PropertyKey<A> key)
Gets the value of a property.

Type Parameters:
A - the type of the property
Parameters:
key - the name of the property
Returns:
the value or null

getContentArea

public CContentArea getContentArea()
Gets the element that should be in the center of the mainframe.

Returns:
the center of the mainframe of the application

add

public <F extends SingleCDockable> F add(F dockable)
Adds a dockable to this control. The dockable can be made visible afterwards.

Type Parameters:
F - the type of the new element
Parameters:
dockable - the new element to show
Returns:
dockable

add

public <F extends MultipleCDockable> F add(F dockable)
Adds a dockable to this control. The dockable can be made visible afterwards.

Type Parameters:
F - the type of the new element
Parameters:
dockable - the new element to show
Returns:
dockable

add

public <F extends MultipleCDockable> F add(F dockable,
                                           String uniqueId)
Adds a dockable to this control. The dockable can be made visible afterwards. This method will throw an exception when the unique identifier is already in use. Clients better use add(MultipleCDockable).

Type Parameters:
F - the type of the new element
Parameters:
dockable - the new element to show
uniqueId - id the unique id of the new element
Returns:
dockable
Throws:
IllegalArgumentException - if the unique identifier is already in use, if dockable is already used elsewhere, if there is no factory for dockable
NullPointerException - if any argument is null

remove

public void remove(SingleCDockable dockable)
Removes a dockable from this control. The dockable is made invisible.

Parameters:
dockable - the element to remove

remove

public void remove(MultipleCDockable dockable)
Removes a dockable from this control. The dockable is made invisible.

Parameters:
dockable - the element to remove

getCDockableCount

public int getCDockableCount()
Gets the number of CDockables that are registered in this CControl.

Returns:
the number of dockables

getCDockable

public CDockable getCDockable(int index)
Gets the index'th dockable that is registered in this control

Parameters:
index - the index of the element
Returns:
the selected dockable

add

public void add(String id,
                MultipleCDockableFactory<?,?> factory)
Adds a factory to this control. The factory will create MultipleCDockables when a layout is loaded.

Parameters:
id - the unique id of the factory
factory - the new factory

setDefaultLocation

public void setDefaultLocation(CLocation defaultLocation)
Sets the location where CDockables are opened when there is nothing else specified for these CDockables.

Parameters:
defaultLocation - the location, can be null

getDefaultLocation

public CLocation getDefaultLocation()
Gets the location where CDockables are opened when nothing else is specified.

Returns:
the location, might be null
See Also:
setDefaultLocation(CLocation)

setMaximizeBehavior

public void setMaximizeBehavior(CMaximizeBehavior behavior)
Sets the CMaximizeBehavior. The behavior decides what happens when the user want's to maximize or to un-maximize a CDockable.

Parameters:
behavior - the new behavior, not null

getMaximizeBehavior

public CMaximizeBehavior getMaximizeBehavior()
Gets the currently used maximize-behavior.

Returns:
the behavior, not null
See Also:
setMaximizeBehavior(CMaximizeBehavior)

setTheme

public void setTheme(DockTheme theme)
Sets the theme of the elements in the realm of this control.

Parameters:
theme - the new theme

addResizeRequestListener

public void addResizeRequestListener(ResizeRequestListener listener)
Adds a ResizeRequestListener to this CControl. The listener will be informed when the resize requests of a CDockable should be processed.

Parameters:
listener - the new listener, not null

removeResizeRequestListener

public void removeResizeRequestListener(ResizeRequestListener listener)
Removes a ResizeRequestListener from this CControl.

Parameters:
listener - the listener to remove

handleResizeRequests

public void handleResizeRequests()
Informs all ResizeRequestListeners, that the resize request of all CDockables should be processed. There are no guarantees that a resize requests can be granted or even gets processed.
All requests, independent from whether they were processed, will be deleted by this method.
Note that a request might conflict with a "resize lock" CDockable.isResizeLocked(). The behavior of that case is not specified, but clients can assume that the locked components introduce additional resize requests.


intern

public DockFrontend intern()
Gets the representation of the layer beneath the facile-layer.

Returns:
the entry point to DockingFrames

write

public void write(File file)
           throws IOException
Writes the current and all known layouts into file.
This is the same as calling getResources().writeFile( file ).

Parameters:
file - the file to override
Throws:
IOException - if the file can't be written

write

public void write(DataOutputStream out)
           throws IOException
Writes the current and all known layouts into out.
This is the same as calling getResources().writeStream( out ).

Parameters:
out - the stream to write into
Throws:
IOException - if the stream is not writable

read

public void read(File file)
          throws IOException
Reads the current and other known layouts from file.
This is the same as calling getResources().readFile( file ).

Parameters:
file - the file to read from
Throws:
IOException - if the file can't be read

read

public void read(DataInputStream in)
          throws IOException
Reads the current and other known layouts from in.
This is the same as calling getResources().readStream( out ).

Parameters:
in - the stream to read from
Throws:
IOException - if the stream can't be read

save

public void save(String name)
Stores the current layout with the given name.

Parameters:
name - the name of the current layout.

load

public void load(String name)
Loads an earlier stored layout.

Parameters:
name - the name of the layout.

delete

public void delete(String name)
Deletes a layout that has been stored earlier.

Parameters:
name - the name of the layout to delete

layouts

public String[] layouts()
Gets a list of all layouts that are currently known.

Returns:
the list of layouts