facets.core.superficial
Class TargetCore

java.lang.Object
  extended by facets.util.Tracer
      extended by facets.core.superficial.TargetCore
All Implemented Interfaces:
Notifiable, Notifying, STarget, TargeterCore.TargetType, Identified, Titled
Direct Known Subclasses:
FrameGroup.Proxy, IndexingTarget, SFrameTarget, SIndexing, SNumeric, STextual, SToggling, STrigger, ViewerTarget

public class TargetCore
extends Tracer
implements STarget, TargeterCore.TargetType

Implements STarget.

TargetCore is the core implementation of STarget, extended both in this and other packages. It also serves as a means of grouping other simple targets.


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
static int targets
           
 
Fields inherited from interface facets.core.superficial.STarget
NONE
 
Constructor Summary
TargetCore(java.lang.String title)
          Convenience constructor that sets no child elements.
TargetCore(java.lang.String title, STarget... elements)
          Core constructor.
 
Method Summary
protected  boolean blockNotification()
          Enables notification to be restricted to this member of the tree.
 STarget[] elements()
          Implements interface method.
static
<T extends Notifiable>
T
findMonitorOfType(java.lang.Class<T> type, STarget target)
          Utility for finding a Notifiable ancestor in the notification tree.
 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 isLive()
          Indicates whether the STarget should be exposed by a surface facet as open to control eg 'enabled'.
static STarget[] join(STarget[] head, STarget[] tail)
           
protected  STarget[] lazyElements()
          Lazily creates elements for this target.
 Notifiable monitor()
          The current Notifiable in the notification tree, as set with setMonitor.
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()
          Create and return a targeter suitable for retargeting to this target.
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.
protected  void setElements(STarget[] elements)
          Sets the STarget children of the TargetCore.
 void setLive(boolean live)
          Sets the internal state used by isLive.
 void setMonitor(Notifiable monitor)
          Attach the Notifying to a Notifiable parent in the notification tree.
 java.lang.String title()
          Return human-readable identifying text.
 java.lang.String toString()
           
 boolean 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.Notifying
impact, monitor, notifyMonitor, setMonitor
 
Methods inherited from interface facets.core.superficial.Notifiable
notify
 

Field Detail

targets

public static int targets
Constructor Detail

TargetCore

public TargetCore(java.lang.String title)
Convenience constructor that sets no child elements.


TargetCore

public TargetCore(java.lang.String title,
                  STarget... elements)
Core constructor.

Parameters:
title - should be suitable for return as the (immutable) title property
elements - may be null (in which case suitable elements may be created using lazyElements); otherwise passed to setElements(STarget[])
Method Detail

setElements

protected final void setElements(STarget[] elements)
Sets the STarget children of the TargetCore.

Intended for use in specialised subclass construction; elements set are thereafter immutable.

Parameters:
elements - (which may not be null nor contain null members) will be returned as the elements property.

elements

public final STarget[] elements()
Implements interface method.

If no elements have been set, attempts to create them with lazyElements.

Each call to this method also sets the TargetCore as notification monitor of any element that is not a SFrameTarget.

Specified by:
elements in interface STarget
Returns:
a non-null STarget[]

lazyElements

protected STarget[] lazyElements()
Lazily creates elements for this target.

Called at most once from elements().

Though defined in TargetCore this method is primarily for use by SFrameTargets, which always create their elements dynamically by reimplementing this method. Default implementation returns an empty STarget[].


newTargeter

public STargeter newTargeter()
Create and return a targeter suitable for retargeting to this target.

This is the key method used by Facets to implement dynamic creation of a surface targeter tree. During initial retargeting each TargeterCore queries its target for any child elements, and calls this method on each child to obtain suitable STargeter instances which it then adds to its elements.

This method may be also called on subsequent retargetings where the specific type of a target is subject to change (for instance when it represents a selection). Either the STargeter returned can be matched to an existing one to which facet have already been attached, or such facet can be attached and the surface layout adjusted accordingly.


isLive

public boolean isLive()
Description copied from interface: STarget
Indicates whether the STarget should be exposed by a surface facet as open to control eg 'enabled'.

Returns true only if both the following conditions are met:

Specified by:
isLive in interface STarget

setLive

public void setLive(boolean live)
Description copied from interface: STarget
Sets the internal state used by isLive.

Specified by:
setLive in interface STarget

title

public 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

toString

public java.lang.String toString()

notifiesTargeter

protected boolean notifiesTargeter()
Used to construct the notification tree.

NOTE This method must NOT be overridden in application code.


newDebugChildren

protected TypedNode[] newDebugChildren()
Create a TypedNode[] representation of this Notifying for debug purposes.


join

public static final STarget[] join(STarget[] head,
                                   STarget[] tail)

wantsFocus

public boolean wantsFocus()
Specified by:
wantsFocus in interface STarget

findMonitorOfType

public static final <T extends Notifiable> T findMonitorOfType(java.lang.Class<T> type,
                                                               STarget target)
Utility for finding a Notifiable ancestor in the notification tree.

Searches up the tree from the current target of facet.

Parameters:
target - in tree exposed by calling facet
Returns:
the first found, or null

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

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