facets.core.app
Class ViewerContenter

java.lang.Object
  facets.util.Tracer
      facets.core.app.ViewerContenter

All Implemented Interfaces:

AppSurface.Contenter, SContenter, TargeterCore.TargetType, Titled

Direct Known Subclasses:

TreeAppContenter

public abstract class ViewerContenter
extends Tracer
implements SContenter, AppSurface.Contenter

SContenter that builds content roots containing viewers.

ViewerContenter extends its superclass to build one or more roots containing viewers exposing content created from a source passed to its constructor.

Its implementation of newContentRoot(boolean, boolean) defines template methods encapsulating two distinct approaches to the build process.

Since ViewerContenter primarily creates content for AppSurface, it provides a basic implementation of AppSurface.Contenter; it also defines methods for saving content back to a source such as a file than can also function as a sink.

Nested Class Summary

static interface

ViewerContenter.ContentSource Can create content.

Field Summary

static ViewableFrame

VIEWABLE_NONE

Constructor Summary

protected

ViewerContenter(java.lang.Object sourceOrSink) Unique constructor.

Method Summary

void	alignAddedRoot(SAreaTarget existing, SAreaTarget added) Allows the contenter to align two target trees, for instance when 'cloning' a window.
protected void	attachContentRootFacets(SAreaTarget rootArea) Attach viewer and area facets to the tree headed by rootArea using a suitable facet builder.
SFrameTarget	contentFrame() Returns the ViewableFrame framing content generated by the source of this ViewerContenter.
boolean	hasChanged() Implements interface method.
protected STarget[]	lazyContentRootElements(SAreaTarget root) Return elements for the content root.
protected AppSurface.ContentRoot	newAppContentRoot(java.lang.String title, FacetedTarget[] viewers) Creates a content root suitable for multi-content application.
SAreaTarget	newContentRoot(boolean faceted, boolean shareSelection) Implements abstract method.
protected java.lang.String	newContentRootTitle(ViewableFrame viewable) Return the title for a content root.
protected ViewableFrame	newContentViewable(java.lang.Object source) Create a ViewableFrame framing content.
protected FacetedTarget[]	newContentViewers(ViewableFrame viewable) Create a FacetedTarget[] defining an arrangement of viewers for viewable.
protected SAreaTarget	newViewableContentRoot(java.lang.Object sourceOrContent, boolean faceted) May create an area target tree complete with facets.
void	rootRetargeted(SContentRootTargeter t) Implements interface method.
void	saveToSink(java.lang.Object sink) Attempt to save to a sink.
boolean	setSink(java.lang.Object sink) Attempts to set a data sink for the content.
java.lang.Object	sink() Data sink to which the ViewerContenter can be persisted.
FileSpecifier[]	sinkFileSpecifiers() Specify file passed to saveToSink(Object).
java.lang.String	title() Implements abstract method.
void	wasAdded() Called when the content has been added to the surface.
void	wasRemoved() Called when the content has been removed from the surface.

Methods inherited from class facets.util.Tracer

trace, trace, trace, trace, trace, traceDebug, traceDebug, traceObjectText, traceOutput, traceOutputWithClass

Methods inherited from class java.lang.Object

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

Methods inherited from interface facets.core.app.AppSurface.Contenter

newContentLayout

Field Detail

VIEWABLE_NONE

public static final ViewableFrame VIEWABLE_NONE

Constructor Detail

ViewerContenter

protected ViewerContenter(java.lang.Object sourceOrSink)

Unique constructor.

Parameters:

sourceOrSink - passed by newContentRoot(boolean, boolean) to newContentViewable(Object)

Method Detail

newContentRoot

public final SAreaTarget newContentRoot(boolean faceted,
                                        boolean shareSelection)

Implements abstract method.

Calls template methods as follows:

1. newViewableContentRoot(Object, boolean) which can be implemented to create a content root complete with attached facet; such a root is then returned without the remaining methods being called.
2. newContentViewable(Object) to create content from the source passed to the constructor and wrap it in a ViewableFrame.
3. newContentViewers(ViewableFrame)to define one or more ViewerTargets for incorporation in a content area root, with multiple viewers contained in SAreaTargets so as to meet the contract of SAreaTarget.
4. newContentRootTitle(ViewableFrame) and lazyContentRootElements(SAreaTarget) to specify the remaining features of an SAreaTarget to be returned as the root of the viewers area tree, followed by newAppContentRoot(String, FacetedTarget[]) to create the root
5. (if faceted is true) attachContentRootFacets(SAreaTarget) to create and attach facet to the area tree.

Specified by:

newContentRoot in interface SContenter

Parameters:

faceted - if false can signal a fresh invocation that requires return of an unfaceted root wrapping the existing viewable

shareSelection - should the new tree frame the existing viewable

Returns:

the SAreaTarget root of an area tree containing either the content or viewers for the content; the root should in turn return with SAreaTarget.newTargeter() a SContentRootTargeter for the content wrapped by the SContenter.

newViewableContentRoot

protected SAreaTarget newViewableContentRoot(java.lang.Object sourceOrContent,
                                             boolean faceted)

May create an area target tree complete with facets.

Called by newContentRoot(boolean, boolean) with the object passed to the constructor; should return an SAreaTarget to meet the same contract.

Default returns null, requiring valid implementations of subsequent methods.

Parameters:

sourceOrContent - may be either a content source such as a file, or the content itself.

faceted - if true, the root returned should have a facet attached

newContentViewable

protected ViewableFrame newContentViewable(java.lang.Object source)

Create a ViewableFrame framing content.

Called by the first invocation of newContentRoot(boolean, boolean), with the content or source passed to the constructor.

A valid implementation of this method should create default content and/or content from a file or database connection, possibly using an implementation of ViewerContenter.ContentSource passed to the constructor.

The ViewableFrame returned will be passed to newContentViewers(ViewableFrame).

Default implementation is an invalid stub.

Parameters:

source - must be capable either of defining or of creating content; it should not generally be the content itself

newContentViewers

protected FacetedTarget[] newContentViewers(ViewableFrame viewable)

Create a FacetedTarget[] defining an arrangement of viewers for viewable.

Called by newContentRoot(boolean, boolean) with the ViewableFrame returned by newContentViewable(Object).

The FacetedTargets returned must comprise either

• a single ViewerTarget, or
• any number of SAreaTargets defining an arrangement of ViewerTargets.

Default implementation is an invalid stub; ActionViewerTarget.newViewerAreas(ViewableFrame, SFrameTarget[]) can be used for implementations where viewers share the same ViewableAction[].

Parameters:

viewable - was returned by newContentViewable(Object) and should be returned as the viewable of all ViewerTargets constructed in this method.

attachContentRootFacets

protected void attachContentRootFacets(SAreaTarget rootArea)

Attach viewer and area facets to the tree headed by rootArea using a suitable facet builder.

Called by the first invocation of newContentRoot(boolean, boolean), with the SAreaTarget returned by newAppContentRoot(String, FacetedTarget[])

Default implementation is an invalid stub.

Parameters:

rootArea - was returned by newContentRoot(boolean, boolean)

newContentRootTitle

protected java.lang.String newContentRootTitle(ViewableFrame viewable)

Return the title for a content root.

The default implementation returns the title of viewable.

Parameters:

viewable - was constructed in newContentViewable(Object)

newAppContentRoot

protected final AppSurface.ContentRoot newAppContentRoot(java.lang.String title,
                                                         FacetedTarget[] viewers)

Creates a content root suitable for multi-content application.

Creates a subclass of AppSurface.ContentRoot returning elements defined in lazyContentRootElements(SAreaTarget), with viewers as its children.

Called by newContentRoot(boolean, boolean), should also be called from implementations of newViewableContentRoot(Object, boolean)

Parameters:

title - was returned by newContentRootTitle(ViewableFrame)

viewers - were created in newContentViewers(ViewableFrame)

lazyContentRootElements

protected STarget[] lazyContentRootElements(SAreaTarget root)

Return elements for the content root.

The default implementation returns an empty Target[] to meet the contract of TargetCore.lazyElements.

Parameters:

root - contains the viewers returned by newContentViewers(ViewableFrame).

alignAddedRoot

public void alignAddedRoot(SAreaTarget existing,
                           SAreaTarget added)

Description copied from interface: AppSurface.Contenter

Allows the contenter to align two target trees, for instance when 'cloning' a window.

Specified by:

alignAddedRoot in interface AppSurface.Contenter

Parameters:

existing - containing values to copy

added - new root to be aligned with existing

rootRetargeted

public void rootRetargeted(SContentRootTargeter t)

Implements interface method.

Empty implementation.

Specified by:

rootRetargeted in interface SContenter

Parameters:

t - will be retargeted on a content root created by this SContenter type (not generally by this instance).

contentFrame

public final SFrameTarget contentFrame()

Returns the ViewableFrame framing content generated by the source of this ViewerContenter.

The ViewableFrame is unique to this instance.

Specified by:

contentFrame in interface SContenter

hasChanged

public boolean hasChanged()

Implements interface method.

Default returns true.

Specified by:

hasChanged in interface AppSurface.Contenter

wasAdded

public void wasAdded()

Description copied from interface: AppSurface.Contenter

Called when the content has been added to the surface.

Specified by:

wasAdded in interface AppSurface.Contenter

wasRemoved

public void wasRemoved()

Description copied from interface: AppSurface.Contenter

Called when the content has been removed from the surface.

Specified by:

wasRemoved in interface AppSurface.Contenter

title

public java.lang.String title()

Implements abstract method.

Returns the title of contentFrame().

Specified by:

title in interface SContenter

Specified by:

title in interface Titled

Returns:

non-null, non-empty string with no structural whitespace

sink

public final java.lang.Object sink()

Data sink to which the ViewerContenter can be persisted.

Set during construction to the source.

setSink

public boolean setSink(java.lang.Object sink)

Attempts to set a data sink for the content.

Parameters:

sink - becomes the new sink()

Returns:

true by default; return false to signal unacceptable sink

saveToSink

public void saveToSink(java.lang.Object sink)
                throws java.io.IOException

Attempt to save to a sink.

Default is invalid stub.

Parameters:

sink - typically a file

Throws:

java.io.IOException

sinkFileSpecifiers

public FileSpecifier[] sinkFileSpecifiers()

Specify file passed to saveToSink(Object).

Returns:

one or more FileSpecifiers; default is invalid stub