facets.core.superficial.app
Class ViewerTarget

java.lang.Object
  facets.util.Tracer
      facets.core.superficial.TargetCore
          facets.core.superficial.app.ViewerTarget

All Implemented Interfaces:

SViewer, Facetable, FacetedTarget, Notifiable, Notifying, STarget, TargeterCore.TargetType, Identified, Titled

Direct Known Subclasses:

ActionViewerTarget

public abstract class ViewerTarget
extends TargetCore

Connects a facet to the viewer and retargeting architectures.

ViewerTarget connects a viewer facet to the surface targeter tree in three distinct ways.

Firstly, it implements SViewer to supply a viewer facet with view policy and content based on two final STarget members passed to the constructor:

• views is either a SFrameTarget whose SFrameTarget.framed is a SView, or an SIndexing of several such.
• viewable is the ViewableFrame whose framed is to be exposed in whole or part by the viewer facet attached to the ViewerTarget

Both views and (most commonly) viewable can be shared with other ViewerTargets.

Secondly, ViewerTarget implements FacetedTarget to represent its facet in turn to the retargeting architecture via the SAreaTarget content area tree.

Finally, the ViewableActions passed to the constructor are coupled to STrigger targets that can be

• queried by the viewer facet to set/adjust its key mappings
• exposed in the surface
• used to trigger actions on viewable content

The STargeter returned by newTargeter() ensures that trigger live states are updated at each retargeting.

Nested Class Summary

Nested classes/interfaces inherited from interface facets.core.superficial.STarget

STarget.Targeted

Nested classes/interfaces inherited from interface facets.core.superficial.Notifying

Notifying.Impact

Field Summary

STrigger[]	actionTriggers Coupled to the ViewableActions passed to the constructor.
static int	ELEMENTS_FACET
static int	ELEMENTS_VIEWABLE
ViewableFrame	viewable Frames content of which some portion is to be exposed by the viewer facet.
STarget	views Either a SFrameTarget decorating a SView, or an SIndexing of several such.

Fields inherited from class facets.core.superficial.TargetCore

targets

Fields inherited from interface facets.core.superficial.STarget

NONE

Fields inherited from interface facets.core.superficial.app.SViewer

CURSOR_CROSSHAIR, CURSOR_DEFAULT, CURSOR_HAND, CURSOR_MOVE, CURSOR_NORTH, CURSOR_TEXT, CURSOR_WAIT, CURSOR_WEST

Constructor Summary

protected

ViewerTarget(java.lang.String title, ViewableFrame viewable, STarget views) Unique constructor.

Method Summary

protected void	actionTriggerFired(ViewableAction action) Responds to firing of a trigger coupled to the action.
SAreaTarget	areaParent() The parent in the area target tree.
SFacet	attachedFacet() The SFacet attached with FacetedTarget.attachFacet(SFacet).
void	attachFacet(SFacet facet) Attach an immutable facet.
protected boolean	blockNotification() Enables notification to be restricted to this member of the tree.
void	ensureActive(boolean notify) Ensure that the targeter tree treats the faceted as having the GUI focus.
protected abstract ViewableAction	getTriggerAction(STrigger trigger) Retrieve the action coupled to a trigger.
java.lang.Object	identity() Return an object that is as far as possible unique for the implementation.
Notifying.Impact	impact() Allows this Notifying to specify a default Notifying.Impact.
boolean	isActive() Should the targeter tree treat the facet as having the GUI focus?
protected STarget[]	lazyElements() Re-implementation.
Notifiable	monitor() The current Notifiable in the notification tree, as set with setMonitor.
protected STarget[]	newActionTriggerGroups(ViewableAction[] actions) Compose groups of triggers for use in the targeter tree.
protected abstract STrigger[]	newActionTriggers(ViewableAction[] actions) Create triggers coupled to the actions passed.
protected TypedNode[]	newDebugChildren() Create a TypedNode[] representation of this Notifying for debug purposes.
protected static TypedNode	newDebugContentNode(java.lang.String title, java.lang.Object source)
protected static TypedNode	newDebugContentNode(java.lang.String title, java.lang.Object[] source)
protected static TypedNode	newDebugMonitorNode(Notifiable monitor)
TypedNode	newGraphNode() Returns a descriptive node for use in debug object graph.
STargeter	newTargeter() Final re-implementation.
static SFrameTarget[]	newViewFrames(SView[] views) Convenenience method that wraps SViews in SFrameTargets.
protected boolean	notifiesTargeter() Used to construct the notification tree.
void	notify(Notice notice) Respond to the Notice passed.
void	notifyMonitor(Notifying.Impact impact) Call notify on the parent monitor in the notification tree, typically with itself as parameter to the Notice passed.
void	retargetFacets(Notifying.Impact impact) Implements interface method.
SSelection	selection() Implements abstract method.
void	selectionChanged(SSelection selection) Implements interface method.
void	selectionEdited(SSelection selection, java.lang.Object edit, boolean interim) Implements interface method.
void	setAreaParent(SAreaTarget parent)
void	setLive(boolean live) Re-implementation that ensures the viewable is also set live.
void	setMonitor(Notifiable monitor) Attach the Notifying to a Notifiable parent in the notification tree.
java.lang.String	toString()
SView	view() Implements abstract method.
SFrameTarget	viewFrame() Represents the SView currently returned by view().

Methods inherited from class facets.core.superficial.TargetCore

elements, findMonitorOfType, isLive, join, setElements, title, wantsFocus

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

Methods inherited from interface facets.core.superficial.STarget

elements, isLive, wantsFocus

Methods inherited from interface facets.util.Titled

title

Methods inherited from interface facets.core.superficial.Notifying

impact, monitor, notifyMonitor, setMonitor

Methods inherited from interface facets.core.superficial.Notifiable

notify

Field Detail

ELEMENTS_VIEWABLE

public static final int ELEMENTS_VIEWABLE

See Also:

Constant Field Values

ELEMENTS_FACET

public static final int ELEMENTS_FACET

See Also:

Constant Field Values

actionTriggers

public final STrigger[] actionTriggers

Coupled to the ViewableActions passed to the constructor.

views

public final STarget views

Either a SFrameTarget decorating a SView, or an SIndexing of several such.

viewable

public final ViewableFrame viewable

Frames content of which some portion is to be exposed by the viewer facet.

Constructor Detail

ViewerTarget

protected ViewerTarget(java.lang.String title,
                       ViewableFrame viewable,
                       STarget views)

Unique constructor.

The views passed can be either:

• a single SFrameTarget wrapping a SView
• an SIndexing of several such

Parameters:

title - passed to superclass

viewable - stored as immutable member

views - stored as immutable member; if an SIndexing the ViewerTarget is set as its notification monitor

Method Detail

newActionTriggers

protected abstract STrigger[] newActionTriggers(ViewableAction[] actions)

Create triggers coupled to the actions passed.

Called from the constructor (so should not rely on instance variables in subclasses)

Parameters:

actions - were passed to the constructor

Returns:

a STrigger[] for storage as actionTriggers

lazyElements

protected STarget[] lazyElements()

Re-implementation. Returns groups of STriggers created by newActionTriggerGroups(ViewableAction[]);

Overrides:

lazyElements in class TargetCore

newActionTriggerGroups

protected STarget[] newActionTriggerGroups(ViewableAction[] actions)

Compose groups of triggers for use in the targeter tree.

Groups must contain only members of actionTriggers.

Parameters:

actions -

Returns:

a STarget[] for return by lazyElements(); default returns a STarget[] with a single member grouping all actionTriggers

getTriggerAction

protected abstract ViewableAction getTriggerAction(STrigger trigger)

Retrieve the action coupled to a trigger.

Called during retargeting; the trigger live state is set to the value returned by ViewableFrame.actionIsLive(SViewer, ViewableAction),

Parameters:

trigger - was coupled in newActionTriggers(ViewableAction[]) to the action to be checked

actionTriggerFired

protected final void actionTriggerFired(ViewableAction action)

Responds to firing of a trigger coupled to the action.

Calls ViewableFrame.actionTriggered(SViewer, ViewableAction) with action.

Parameters:

action - was coupled in newActionTriggers(ViewableAction[]) to the trigger fired

newTargeter

public final STargeter newTargeter()

Final re-implementation.

Returns a targeter that updates trigger live states during STargeter.retarget(STarget, Notifying.Impact).

Overrides:

newTargeter in class TargetCore

view

public final SView view()

Implements abstract method.

Specified by:

view in interface SViewer

Returns:

the SFrameTarget.framed returned by viewFrame()

selection

public final SSelection selection()

Implements abstract method.

Returns a SSelection for display in its viewer facet, calling ViewableFrame.newViewerSelection(SViewer) to obtain a suitable (sub-)selection within its content.

The SSelection is memoed and returned at any subsequent invocation until the next invocation of retargetFacets(Notifying.Impact), when it is destroyed before SRetargetable.retarget(STarget,Notifying.Impact) is called on attachedFacet().

Specified by:

selection in interface SViewer

selectionChanged

public final void selectionChanged(SSelection selection)

Implements interface method.

Calls ViewableFrame.viewerSelectionChanged(SViewer,SSelection) followed by Notifying.notifyMonitor(Impact).

Specified by:

selectionChanged in interface SViewer

Parameters:

selection - defines the new selection.

selectionEdited

public final void selectionEdited(SSelection selection,
                                  java.lang.Object edit,
                                  boolean interim)

Implements interface method.

Calls ViewableFrame.viewerSelectionEdited(SViewer, Object, boolean) followed by Notifying.notifyMonitor(Impact).

Specified by:

selectionEdited in interface SViewer

Parameters:

selection - if null implies edit should be applied to the current selection; otherwise the selection should be changed to match

edit - defines the change proposed to the selection

interim - if true the edit forms part of a sequence

attachFacet

public final void attachFacet(SFacet facet)

Description copied from interface: FacetedTarget

Attach an immutable facet.

As a STarget representing its FacetedTarget.attachedFacet(), FacetedTarget can only attach a single viewer or area facet; it should complain if any attempt is made to attach another.

Specified by:

attachFacet in interface Facetable

Specified by:

attachFacet in interface FacetedTarget

Parameters:

facet - will be applied during each retargeting sequence

attachedFacet

public final SFacet attachedFacet()

Description copied from interface: FacetedTarget

The SFacet attached with FacetedTarget.attachFacet(SFacet).

Return the facet attached to this FacetedTarget, complaining if none yet attached.

Specified by:

attachedFacet in interface FacetedTarget

retargetFacets

public final void retargetFacets(Notifying.Impact impact)

Implements interface method.

Retargets any attached facet on this ViewerTarget; also destroys the currently memoed SSelection.

Specified by:

retargetFacets in interface Facetable

isActive

public boolean isActive()

Description copied from interface: FacetedTarget

Should the targeter tree treat the facet as having the GUI focus?

Specified by:

isActive in interface SViewer

Specified by:

isActive in interface FacetedTarget

ensureActive

public final void ensureActive(boolean notify)

Description copied from interface: FacetedTarget

Ensure that the targeter tree treats the faceted as having the GUI focus.

Specified by:

ensureActive in interface FacetedTarget

Parameters:

notify - if true, also trigger a retargeting

See Also:

Notifying

areaParent

public final SAreaTarget areaParent()

Description copied from interface: FacetedTarget

The parent in the area target tree.

Specified by:

areaParent in interface FacetedTarget

setLive

public final void setLive(boolean live)

Re-implementation that ensures the viewable is also set live.

Specified by:

setLive in interface STarget

Overrides:

setLive in class TargetCore

viewFrame

public final SFrameTarget viewFrame()

Represents the SView currently returned by view().

(Encapsulates the logic for the implementation of view().)

Returns:

either the single SFrameTarget or the indexed of the SIndexing set as views.

notifiesTargeter

protected final boolean notifiesTargeter()

Description copied from class: TargetCore

Used to construct the notification tree.

NOTE This method must NOT be overridden in application code.

Overrides:

notifiesTargeter in class TargetCore

toString

public java.lang.String toString()

Overrides:

toString in class TargetCore

newDebugChildren

protected TypedNode[] newDebugChildren()

Create a TypedNode[] representation of this Notifying for debug purposes.

Overrides:

newDebugChildren in class TargetCore

setAreaParent

public void setAreaParent(SAreaTarget parent)

newViewFrames

public static final SFrameTarget[] newViewFrames(SView[] views)

Convenenience method that wraps SViews in SFrameTargets.

Parameters:

views - to be wrapped

newDebugContentNode

protected static final TypedNode newDebugContentNode(java.lang.String title,
                                                     java.lang.Object source)

newDebugContentNode

protected static final TypedNode newDebugContentNode(java.lang.String title,
                                                     java.lang.Object[] source)

newDebugMonitorNode

protected static final TypedNode newDebugMonitorNode(Notifiable monitor)

newGraphNode

public final TypedNode newGraphNode()

Returns a descriptive node for use in debug object graph.

impact

public Notifying.Impact impact()

Description copied from interface: Notifying

Allows this Notifying to specify a default Notifying.Impact.

Specified by:

impact in interface Notifying

Returns:

typically Notifying.Impact.DEFAULT

identity

public java.lang.Object identity()

Description copied from interface: Identified

Return an object that is as far as possible unique for the implementation.

This will usually be a class instance counter.

Specified by:

identity in interface Identified

monitor

public final Notifiable monitor()

The current Notifiable in the notification tree, as set with setMonitor.

Complains if no parent has been set.

Specified by:

monitor in interface Notifying

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

notifyMonitor

public final void notifyMonitor(Notifying.Impact impact)

Description copied from interface: Notifying

Call notify on the parent monitor in the notification tree, typically with itself as parameter to the Notice passed.

Has no effect if no monitor has been set.

This is the usual means to trigger a surface retargeting, being called by an exposing SFacet on its target.

Specified by:

notifyMonitor in interface Notifying

Parameters:

impact - suggests the level of retargeting required

blockNotification

protected boolean blockNotification()

Enables notification to be restricted to this member of the tree.

Checked by notify(Notice); default returns false.

setMonitor

public final void setMonitor(Notifiable monitor)

Description copied from interface: Notifying

Attach the Notifying to a Notifiable parent in the notification tree.

Specified by:

setMonitor in interface Notifying