facets.core.app
Class AppSurface

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

All Implemented Interfaces:

SSurface, Notifiable, Titled

Direct Known Subclasses:

ActionAppSurface

public abstract class AppSurface
extends Tracer
implements SSurface

Implements SSurface for both single- and multi-content applications.

AppSurface maintains a set of SContenter members and an internal surface area root containing content area roots exposing these members; a wide range of methods enable addition and removal of both roots and content.

Depending on AppSpecifier.contentStyle() in the AppSpecifier passed to the core constructor, AppSurface can build an application whose content is exposed three ways:

• SINGLE - single content and content root
• TABBED - multiple content exposed by content roots in folder tabs
• DESKTOP - multiple content (potentially of multiple types) roots exposed by windows within internal desktop

Once the surface is built, the add/removeXXX methods can be called to perform operations on both the content roots and their underlying SContenters.

Nested Class Summary

static class	AppSurface.ContentCreationException Enables a client to abandon creation of content.
static interface	AppSurface.Contenter SContenter for use in an AppSurface.
static class	AppSurface.ContentRoot Heads a content area tree for use in an application surface.
static class	AppSurface.ContentStyle The possible styles for an AppSurface.

Field Summary

static int	AREA_APP Convenience constant denoting level in the SAreaTarget tree.
static int	AREA_CONTENT Convenience constant denoting level in the SAreaTarget tree.
static int	AREA_PAGE Convenience constant denoting level in the SAreaTarget tree.
static int	AREA_PANE Convenience constant denoting level in the SAreaTarget tree.
AppSurface.ContentStyle	contentStyle Immutable AppSurface.ContentStyle for the application.
AppSurface.Contenter	emptyContent Non-existent content of an "empty" AppSurface.ContentStyle.DESKTOP application.
AppSpecifier	spec Immutable AppSpecifier for the application.
static java.lang.String	TITLE_EMPTY Title of emptyContent.

Constructor Summary

protected

AppSurface(AppSpecifier spec) Constructs an application surface.

Method Summary

SContentRootTargeter	activeContentRootTargeter() Returns the targeter of the currently active content root.
void	addContent(java.lang.Object source) Opens or activates a window/tab on source.
void	buildRetargeted() Builds an appropriate surface for the type passed to the constructor.
void	cloneActiveRoot() Opens a new tab/window on existing content.
abstract boolean	contentIsRemovable(AppSurface.Contenter content) Check if content passed may be removed.
protected void	contentNotAdded(AppSurface.ContentCreationException e)
AppSurface.Contenter	findActiveContent() Returns the content that created the active SAreaTarget tree.
SAreaTarget	firstContentRoot(java.lang.Object source) Returns the first SAreaTarget tree exposing the source passed.
protected abstract java.lang.Object[]	getOpeningContentSources() Return sources for content to be exposed when the surface is first created.
java.util.List<ViewerContenter>	getViewerContents() Returns all ViewerContenters currently active in the application.
boolean	isBuilt() Allows a check that the surface has been built.
protected boolean	isHeadless() Provides for an application to run headless.
protected STarget[]	lazySurfaceRootElements() Create targets to be returned as the elements of the surface root.
protected abstract SContenter	newContenter(java.lang.Object source) Return a SContenter wrapping content created from source.
protected abstract SHost.FacetLayout	newEmptyDesktopLayout(SHost host, SContentRootTargeter rootTargeter, SFacet surfaceRootFacet) Provide a empty SHost.FacetLayout.
protected SHost	newHeadlessHost() Provides the host for a headless application.
protected MountFacet	newMultiContentFacet(SAreaTarget surfaceRoot) May return a facet to be attached to the surface root.
void	notify(Notice notice) Respond to the Notice passed.
void	openApp() Defines an application and builds its surface.
boolean	removeActiveContent() Attempts to close all tabs/windows exposing content of the active viewer.
boolean	removeActiveRoot() Attempts to close tab/window containing active viewer.
void	removeAllContent() Attempts to close all tabs/windows.
void	replaceSingleContent(java.lang.Object source) Replaces content in single-content surface.
void	revertActiveContent() Restores content of active root.
void	runWatched(WatchableOperation r) Allows runtime exceptions in framework and client code to be handled gracefully, by AppWatcher.
protected void	surfaceRetargeted() Called whenever the surface root has been retargeted.
AreaTargeter	surfaceRootTargeter() The root of the surface targeter tree.
java.lang.String	title() Implements interface method.

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.superficial.app.SSurface

host

Field Detail

AREA_APP

public static final int AREA_APP

Convenience constant denoting level in the SAreaTarget tree.

See Also:

Constant Field Values

AREA_CONTENT

public static final int AREA_CONTENT

Convenience constant denoting level in the SAreaTarget tree.

See Also:

Constant Field Values

AREA_PANE

public static final int AREA_PANE

Convenience constant denoting level in the SAreaTarget tree.

See Also:

Constant Field Values

AREA_PAGE

public static final int AREA_PAGE

Convenience constant denoting level in the SAreaTarget tree.

See Also:

Constant Field Values

TITLE_EMPTY

public static final java.lang.String TITLE_EMPTY

Title of emptyContent.

See Also:

Constant Field Values

emptyContent

public final AppSurface.Contenter emptyContent

Non-existent content of an "empty" AppSurface.ContentStyle.DESKTOP application.

When returned by findActiveContent() serves as a flag.

contentStyle

public final AppSurface.ContentStyle contentStyle

Immutable AppSurface.ContentStyle for the application.

spec

public final AppSpecifier spec

Immutable AppSpecifier for the application.

Constructor Detail

AppSurface

protected AppSurface(AppSpecifier spec)

Constructs an application surface.

The surface may be empty if contentStyle is DESKTOP otherwise will be initialised with content constructed from return of getOpeningContentSources()).

The surface can form the basis of either a free-standing application that creates its own window and thus its own SHost.FacetLayout, or one created within and by its SHost such as an applet.

Application build sequence is as follows:

1. Create a suitable AppSurface in main if free-standing, in init if applet-hosted.
2. Call openApp() on the AppSurface.
3. The AppSurface calls SSurface.buildRetargeted() to build facet layouts which it passes the host.

Method Detail

lazySurfaceRootElements

protected STarget[] lazySurfaceRootElements()

Create targets to be returned as the elements of the surface root.

Returns:

a non-null (though possibly empty) STarget[]

openApp

public void openApp()

Defines an application and builds its surface.

Calls the final implementation of SSurface.buildRetargeted()

buildRetargeted

public final void buildRetargeted()

Builds an appropriate surface for the type passed to the constructor.

Opening content is created from sources returned by getOpeningContentSources().

Surfaces have the following features:

• SINGLE - content root facet from the single SContenter added directly to the host GUI; menu, tool and status facet from the content can be merged with roots defined by the AppSurface.
• TABBED - one or more tabs containing content root facets obtained from multiple SContenters, managed by the AppSurface which sets new merged menu, tool and status roots as required for the active tab.
• DESKTOP - content root facet in internal windows; DESKTOP as a singleton source signals that an empty desktop be created with suitable menus etc.

Specified by:

buildRetargeted in interface SSurface

notify

public void notify(Notice notice)

Description copied from interface: Notifiable

Respond to the Notice passed.

When this method is called, the Notifiable should respond based on

• its own nature and state
• the Notice passed.

Specified by:

notify in interface Notifiable

getOpeningContentSources

protected abstract java.lang.Object[] getOpeningContentSources()

Return sources for content to be exposed when the surface is first created.

The objects returned must be suitable for passing to newContenter(Object).

Returns:

suitable source[es] for opening content.

newContenter

protected abstract SContenter newContenter(java.lang.Object source)

Return a SContenter wrapping content created from source.

The content must be an implementor of AppSurface.Contenter such as ViewerContenter; it will appear in the surface as follows:

• SINGLE - replacing content in any existing surface
• TABBED, DESKTOP - in new window/tab

Parameters:

source - for the content

newEmptyDesktopLayout

protected abstract SHost.FacetLayout newEmptyDesktopLayout(SHost host,
                                                           SContentRootTargeter rootTargeter,
                                                           SFacet surfaceRootFacet)

Provide a empty SHost.FacetLayout.

Implements AppSurface.Contenter.newContentLayout(SHost, SFacet, SContentRootTargeter) on behalf of emptyContent

newMultiContentFacet

protected MountFacet newMultiContentFacet(SAreaTarget surfaceRoot)

May return a facet to be attached to the surface root.

Defines a tab folder or internal desktop for a multi-content surface - not called for single content as the content root facet is used instead.

Parameters:

surfaceRoot - was (re)created in SSurface.buildRetargeted()

addContent

public final void addContent(java.lang.Object source)

Opens or activates a window/tab on source.

Where type is TABBED or DESKTOP and source is different from that of any existing content, creates a new SContenter and from that a new content root; where source is already in use, activates an existing content root exposing the AppSurface.Contenter for that source.

If client code throws a AppSurface.ContentCreationException the method returns without effect after passing the exception to contentNotAdded(ContentCreationException).

Parameters:

source - for added content

contentNotAdded

protected void contentNotAdded(AppSurface.ContentCreationException e)

replaceSingleContent

public final void replaceSingleContent(java.lang.Object source)

Replaces content in single-content surface.

Where type is SINGLE, replaces content in existing surface with new AppSurface.Contenter created from source.

Parameters:

source - for replacement content

revertActiveContent

public final void revertActiveContent()

Restores content of active root.

Any other roots for the same content are removed.

removeActiveContent

public final boolean removeActiveContent()

Attempts to close all tabs/windows exposing content of the active viewer.

Providing contentIsRemovable(Contenter) returns true for the content of the active viewer, closes all tabs/windows exposing that content.

removeAllContent

public final void removeAllContent()

Attempts to close all tabs/windows.

Removes content roots for all content for which contentIsRemovable(Contenter) returns true;

cloneActiveRoot

public final void cloneActiveRoot()

Opens a new tab/window on existing content.

Where type is TABBED or DESKTOP, adds a new content root exposing the content of the active content root.

removeActiveRoot

public final boolean removeActiveRoot()

Attempts to close tab/window containing active viewer.

Where there is no other root for the content, fails if removeActiveContent() returns false.

findActiveContent

public final AppSurface.Contenter findActiveContent()

Returns the content that created the active SAreaTarget tree.

Returns:

the current content or emptyContent

firstContentRoot

public final SAreaTarget firstContentRoot(java.lang.Object source)

Returns the first SAreaTarget tree exposing the source passed.

Parameters:

source - of content to be found (typically a file)

contentIsRemovable

public abstract boolean contentIsRemovable(AppSurface.Contenter content)

Check if content passed may be removed.

The default implementation checks AppSurface.Contenter.hasChanged().

Parameters:

content - to be checked

surfaceRetargeted

protected void surfaceRetargeted()

Called whenever the surface root has been retargeted.

activeContentRootTargeter

public final SContentRootTargeter activeContentRootTargeter()

Returns the targeter of the currently active content root.

surfaceRootTargeter

public final AreaTargeter surfaceRootTargeter()

Description copied from interface: SSurface

The root of the surface targeter tree.

Specified by:

surfaceRootTargeter in interface SSurface

Returns:

the root of the targeter tree created in SSurface.buildRetargeted()

title

public final java.lang.String title()

Implements interface method.

Specified by:

title in interface Titled

Returns:

AppValues.appName from spec.

getViewerContents

public java.util.List<ViewerContenter> getViewerContents()

Returns all ViewerContenters currently active in the application.

isHeadless

protected boolean isHeadless()

Provides for an application to run headless.

Returns:

false by default

newHeadlessHost

protected final SHost newHeadlessHost()

Provides the host for a headless application.

Returns:

a Headless.HeadlessHost

isBuilt

public final boolean isBuilt()

Allows a check that the surface has been built.

Returns:

true once surfaceRootTargeter() does not throw an IllegalStateException

runWatched

public void runWatched(WatchableOperation r)

Allows runtime exceptions in framework and client code to be handled gracefully, by AppWatcher.

Default simply runs r