facets.core.app
Class DialogSurface

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

All Implemented Interfaces:

SSurface, Notifiable, Titled

Direct Known Subclasses:

FacetDialogSurface

public abstract class DialogSurface
extends Tracer
implements SSurface

Implements SSurface for modal dialogs.

DialogSurface can build different dialog styles depending on the DialogSurface.Contenters passed to its constructor and the methods overriden in the instance subclass.

• simple - pass a single DialogSurface.Contenter, from which a content root is created and added as the single page.
• tabbed - pass multiple DialogSurface.Contenters, from which the content roots are added as children of a single page.
• multi-page - create tree members whose SAreaTarget values are added as pages.

Nested Class Summary

static interface	DialogSurface.Contenter SContenter for use in a DialogSurface.
static class	DialogSurface.ContentRoot Heads a content area tree for use in a dialog page.
static class	DialogSurface.DialogActions Defines top-level buttons for a DialogSurface.

Field Summary

ActionAppSurface	app
static int	AT_NOT_SET
static int	MULTI_AREA_PAGES
static int	MULTI_AREA_TREE
static int	TRIMMINGS_TAB
static int	TRIMMINGS_TREE

Constructor Summary

DialogSurface(ActionAppSurface app, DialogHost host, java.lang.String title, DialogSurface.DialogActions actions, DialogSurface.Contenter[] contents)
Unique constructor.

Method Summary

protected abstract void	attachPageFacet(SAreaTarget page) Attach a suitable facet to this page area.
protected abstract void	attachSurfaceRootFacets(SAreaTarget surfaceRoot) Attach suitable facets to the dialog area root and its children.
void	buildRetargeted() Builds the dialog surface.
DialogSurface.Contenter[]	contents() The contenters for the surface.
static java.lang.Object	contentsKey(DialogSurface.Contenter[] contents) Creates a key representing the exact types of the SContenters passed.
protected boolean	contentsMatch(DialogSurface.Contenter[] existing, DialogSurface.Contenter[] proposed) Do the types of the two arrays match?
void	dismissHostWindow() Enables top-level buttons to dismiss the dialog host.
static STarget	findDialogTrigger(SContentRootTargeter rootTargeter, java.lang.String title)
static SAreaTarget	findRootArea(SContentRootTargeter rootTargeter) Convenience method for accessing the surface area root.
java.awt.Rectangle	getLaunchBounds(SAreaTarget areaRoot) Allows the host to calculate/retrieve its bounds before launch.
SHost	host()
void	hostWindowDismissed(java.awt.Rectangle bounds) Allows the surface tidy up upon dismissal of its host.
protected boolean	isMultiPage() Required to ensure correct calculation of default host size.
protected SAreaTarget[]	newContentPages(DialogSurface.Contenter[] contents, SAreaTarget[] contentRoots) Create at least one dialog page.
protected abstract SFacet	newControlButtons(STargeter link) Create facet managing the top-level dialog control buttons.
protected SFacet	newExtras(AreaTargeter targeter)
protected SView	newPagesTreeView(TypedNode[] treeNodes) Create a view for the page tree.
protected static TypedNode	newPageTreeNode(SAreaTarget page, TypedNode... children) Creates a node for a page selection tree.
protected TypedNode[]	newPageTreeNodes(SAreaTarget[] pages) Creates the top-level children of a page selection tree.
void	notify(Notice notice) Implements interface method.
boolean	persistBoundsState() Should host bounds be persisted?
void	replaceContents(DialogSurface.Contenter[] contents) Replaces all content in the surface.
AreaTargeter	surfaceRootTargeter()
java.lang.String	title() Return human-readable identifying text.

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, surfaceRootTargeter

Methods inherited from interface facets.util.Titled

title

Field Detail

TRIMMINGS_TAB

public static final int TRIMMINGS_TAB

See Also:

Constant Field Values

TRIMMINGS_TREE

public static final int TRIMMINGS_TREE

See Also:

Constant Field Values

AT_NOT_SET

public static final int AT_NOT_SET

See Also:

Constant Field Values

app

public final ActionAppSurface app

MULTI_AREA_TREE

public static final int MULTI_AREA_TREE

See Also:

Constant Field Values

MULTI_AREA_PAGES

public static final int MULTI_AREA_PAGES

See Also:

Constant Field Values

Constructor Detail

DialogSurface

public DialogSurface(ActionAppSurface app,
                     DialogHost host,
                     java.lang.String title,
                     DialogSurface.DialogActions actions,
                     DialogSurface.Contenter[] contents)

Unique constructor.

Parameters:

app - exposed in this surface; stored as app

host - the DialogHost managing the dialog window

title - passed to the host dialog window

actions - the DialogSurface.DialogActions defining a set of control actions for the dialog

contents - the DialogSurface.Contenters defining the content to be exposed in the dialog

Method Detail

contentsKey

public static final java.lang.Object contentsKey(DialogSurface.Contenter[] contents)

Creates a key representing the exact types of the SContenters passed.

Used to implement replaceContents(Contenter[]); available for use by any class requiring a definition of the composite type of a SContenter[]

Parameters:

contents - define the key returned by their types

buildRetargeted

public final void buildRetargeted()

Builds the dialog surface.

All surface variants are built by the same code, with execution path determined primarily by whether it builds a single or multiple page layout.

1. Content roots are constructed and their facet trees built for each of the DialogSurface.Contenters passed to the constructor, and passed to newContentPages(DialogSurface.Contenter[], SAreaTarget[]).
2. Facets are attached using attachPageFacet(SAreaTarget) to any pages returned that are not content roots (and thus already have facet attached).
3. A single page is contained directly by the root area passed to attachSurfaceRootFacets(SAreaTarget).
4. Multiple pages are passed to newPageTreeNodes(SAreaTarget[]) which defines nodes for a page selection tree, and these nodes passed to newPagesTreeView(TypedNode[]); from this a viewer area is created which is one of two children of the root area, the other being an area containing the pages.

Specified by:

buildRetargeted in interface SSurface

replaceContents

public void replaceContents(DialogSurface.Contenter[] contents)

Replaces all content in the surface.

Existing content roots are replaced by roots created by each member of contents, whose types must match exactly those of the existing contents.

Parameters:

contents - replace existing contents

notify

public void notify(Notice notice)

Implements interface method.

Specified by:

notify in interface Notifiable

getLaunchBounds

public final java.awt.Rectangle getLaunchBounds(SAreaTarget areaRoot)

Allows the host to calculate/retrieve its bounds before launch.

Default size may be retrieved from AppValues.nature(boolean) using keys headed with Dialogs.KEYTOP_NATURE_SIZE; and session bounds from AppValues.state(String...) using Dialogs.KEYTOP_BOUNDS.

Parameters:

areaRoot - root of the SAreaTarget content tree

hostWindowDismissed

public final void hostWindowDismissed(java.awt.Rectangle bounds)

Allows the surface tidy up upon dismissal of its host.

Parameters:

bounds - latest of host window

persistBoundsState

public boolean persistBoundsState()

Should host bounds be persisted?

Returns:

true by default

dismissHostWindow

public final void dismissHostWindow()

Enables top-level buttons to dismiss the dialog host.

isMultiPage

protected boolean isMultiPage()

Required to ensure correct calculation of default host size.

Default returns false.

contentsMatch

protected final boolean contentsMatch(DialogSurface.Contenter[] existing,
                                      DialogSurface.Contenter[] proposed)

Do the types of the two arrays match?

Called by replaceContents(Contenter[]); implemented with contentsKey(Contenter[]).

Parameters:

existing - set during initial build or last launch

proposed - for this launch

contents

public final DialogSurface.Contenter[] contents()

The contenters for the surface.

Returns:

contenters passed during construction or to replaceContents

findDialogTrigger

public static STarget findDialogTrigger(SContentRootTargeter rootTargeter,
                                        java.lang.String title)

findRootArea

public static final SAreaTarget findRootArea(SContentRootTargeter rootTargeter)

Convenience method for accessing the surface area root.

Parameters:

rootTargeter - within the area targeter tree

newExtras

protected SFacet newExtras(AreaTargeter targeter)

newContentPages

protected SAreaTarget[] newContentPages(DialogSurface.Contenter[] contents,
                                        SAreaTarget[] contentRoots)

Create at least one dialog page.

Where the implementation returns a multi-member array,

• a valid implementation will be required of newPagesTreeView(TypedNode[]) to define a tree/list viewer to select between the pages; for a full tree viewer newPageTreeNodes(SAreaTarget[]) will also need to be re-implemented
• the area passed to attachSurfaceRootFacets(SAreaTarget) will contain the tree viewer area and an area containing the pages

The default implementation defines a single-page dialog by returning a single-member array containing:

• if contentRoots is single-membered, that member
• otherwise an area containing contentRoots (whose root facet can be displayed as tab children of the facet attached to the area), titled from {title()

Parameters:

contents - passed during construction or to replaceContents(DialogSurface.Contenter[]); may be queried for additional information such as page titles

contentRoots - were created from contents

Returns:

an SAreaTarget[] with at least one member

newPageTreeNodes

protected TypedNode[] newPageTreeNodes(SAreaTarget[] pages)

Creates the top-level children of a page selection tree.

Children created will be passed to newPagesTreeView(TypedNode[]) which should be reimplemented to define a viewer for the tree.

The default implementation returns an array constructed from panelAreas using newPageTreeNode(SAreaTarget,TypedNode[]) and suitable for a list viewer; this method can also be used to created more complex trees.

Parameters:

pages - were returned from newContentPages(DialogSurface.Contenter[], SAreaTarget[])

newPagesTreeView

protected SView newPagesTreeView(TypedNode[] treeNodes)

Create a view for the page tree.

The SView returned should define a suitable viewer for the tree defined by treeNodes, which were returned by newPageTreeNodes(SAreaTarget[]).

Default implementation is an invalid stub.

Parameters:

treeNodes - will have at least two members

attachPageFacet

protected abstract void attachPageFacet(SAreaTarget page)

Attach a suitable facet to this page area.

Parameters:

page - was returned by newContentPages(DialogSurface.Contenter[], SAreaTarget[]) and will not itself be a content root.

attachSurfaceRootFacets

protected abstract void attachSurfaceRootFacets(SAreaTarget surfaceRoot)

Attach suitable facets to the dialog area root and its children.

Parameters:

surfaceRoot - contains either a single page area returned by newContentPages(DialogSurface.Contenter[], SAreaTarget[]) or viewer and switching areas managing multiple page areas

newControlButtons

protected abstract SFacet newControlButtons(STargeter link)

Create facet managing the top-level dialog control buttons.

Parameters:

link - will match the elements returned by lazyTriggerGroup()

Returns:

a SFacet[] with at least one member

surfaceRootTargeter

public final AreaTargeter surfaceRootTargeter()

title

public final java.lang.String title()

Description copied from interface: Titled

Return human-readable identifying text.

Specified by:

title in interface Titled

Returns:

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

newPageTreeNode

protected static final TypedNode newPageTreeNode(SAreaTarget page,
                                                 TypedNode... children)

Creates a node for a page selection tree.

The node returned will

• be of type TYPE_PAGE
• return as title the title of panelRoot
• contain panelRoot as its single value
• contain children as its children

Parameters:

page - should be an area tree defining the layout of a dialog page

children - to appear in a tree viewer below the node created; themselves created using this method

host

public final SHost host()