de.cau.cs.kieler.core.kivi
Class AbstractCombination

java.lang.Object
  extended by de.cau.cs.kieler.core.kivi.AbstractCombination
All Implemented Interfaces:
ICombination, ITriggerListener
Direct Known Subclasses:
E2STransformationCombination, HighlightSelectedTransitionsCombination, KiviMenuContributionDemoCombination, KSBasECombination, LayoutAfterCollapseExpandCombination, LayoutAfterDiagramReinitCombination, LayoutAfterModelChangedCombination, LayoutAnalysisCombination, LayoutCombination, ManualFocusCombination, RandomLayoutCombination, ShowGraphitiHierarchyCombination, ShowHierarchyCombination, SignalFlowCombination, StateMachineCombination, SyncChartsCombination, TestCombinationA, TestCombinationB, TestCombinationEffectsTrigger, TestCombinationEffectsTrigger2, TestCombinationManyExecutes, TestCombinationNoExecute, TestCombinationOverlappingParameters, TestCombinationSpammer, TestCombinationSpammerSynchronized, TestCombinationTwoEffects, TestCombinationUndo, TestCombinationWrongParameterType, UpdateVisibilityCombination

public abstract class AbstractCombination
extends Object
implements ICombination

Abstract base implementation for combinations. It implements many methods of ICombination and adds much extra convenience for Combination developers.

In the ICombination the developer has to implement ITriggerListener.getTriggerStates() and ICombination#trigger(ITriggerState). In this abstract implementation both methods are implemented such that developer instead implements execute() where the abstract implementation uses reflection to find out (1) which are the trigger classes that the combination listens to (by the execute parameters) and (2) what are other current ITriggerStates. Such way the execute method has direct access to all states that it requires.

Additionally, a static method getParameters() can be added to specify combination parameters that should be visible in the preference page. The return value must be an array of CombinationParameters. Warning: Do not publish the same parameter in the preferences of two different combinations, since that can lead to undesired behavior. However, the value of one parameter may be accessed from multiple combinations.

Rating red

Field Summary
protected static int FIFTH
          index constant for the fifth trigger state parameter.
protected static int FIRST
          index constant for the first trigger state parameter.
protected static int FOURTH
          index constant for the fourth trigger state parameter.
protected static int SECOND
          index constant for the second trigger state parameter.
protected static int SEVENTH
          index constant for the seventh trigger state parameter.
protected static int SIXTH
          index constant for the sixth trigger state parameter.
protected static int THIRD
          index constant for the third trigger state parameter.
 
Constructor Summary
AbstractCombination()
           
 
Method Summary
protected  void enableEffectRecording()
          Activate recording of old effects.
 List<IEffect> getEffects()
          Get the list of effects that are ready to be executed after the last triggering of an ITriggerState.
 Class<? extends ITriggerState>[] getTriggerStates()
          Get the array of trigger state classes this combination listens to.
 void handle(ITriggerState triggerState)
          Handle one specific trigger state that just changed.
 boolean isActive()
          Check whether this combination is active.
protected  ITriggerState latestState()
          Convenience method to obtain the trigger state that actually caused the execute method to be invoked.
protected  int latestStateIndex()
          Convenience method to obtain the index of the trigger state that actually caused the execute method to be invoked.
protected  void schedule(IEffect effect)
          Schedule an effect for execution, performs merging against all other effects scheduled during this execution before actually executing the effect.
protected  void schedule(IEffectCompound compoundEffect)
          Schedule a compound effect for execution, performs merging against all other effects scheduled during this execution before actually executing the effect.
 void setActive(boolean a)
          Change the active status of this combination.
 String toString()
           
 void undo()
          Attempt to undo all active effects, for example when shutting down view management or when disabling this combination.
protected  void undoRecordedEffects()
          Explicit call to enable undoing all old effects since the last call of this method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

FIRST

protected static final int FIRST
index constant for the first trigger state parameter.

See Also:
Constant Field Values

SECOND

protected static final int SECOND
index constant for the second trigger state parameter.

See Also:
Constant Field Values

THIRD

protected static final int THIRD
index constant for the third trigger state parameter.

See Also:
Constant Field Values

FOURTH

protected static final int FOURTH
index constant for the fourth trigger state parameter.

See Also:
Constant Field Values

FIFTH

protected static final int FIFTH
index constant for the fifth trigger state parameter.

See Also:
Constant Field Values

SIXTH

protected static final int SIXTH
index constant for the sixth trigger state parameter.

See Also:
Constant Field Values

SEVENTH

protected static final int SEVENTH
index constant for the seventh trigger state parameter.

See Also:
Constant Field Values
Constructor Detail

AbstractCombination

public AbstractCombination()
Method Detail

handle

public final void handle(ITriggerState triggerState)
Handle one specific trigger state that just changed.

Specified by:
handle in interface ITriggerListener
Parameters:
triggerState - the trigger state responsible for the triggering

getEffects

public List<IEffect> getEffects()
Get the list of effects that are ready to be executed after the last triggering of an ITriggerState.

Specified by:
getEffects in interface ICombination
Returns:
list of effects that should be executed

schedule

protected final void schedule(IEffect effect)
Schedule an effect for execution, performs merging against all other effects scheduled during this execution before actually executing the effect.

Parameters:
effect - the effect to schedule

schedule

protected final void schedule(IEffectCompound compoundEffect)
Schedule a compound effect for execution, performs merging against all other effects scheduled during this execution before actually executing the effect. This is equivalent to schedule all primitive effects of an ICompoundEffect.

Parameters:
compoundEffect - the compound effect to schedule

enableEffectRecording

protected final void enableEffectRecording()
Activate recording of old effects. This way old effects can be easily undone later on. However, if they are never undone, this record may increase over time as arbitrarily many old effects may be stored.


undoRecordedEffects

protected final void undoRecordedEffects()
Explicit call to enable undoing all old effects since the last call of this method. This will schedule new UndoEffects and merge them with new effects of this round. This should be called from inside the execute method to easily undo old stuff. Don't use the plain undo() method, as it does not only schedule but also execute the undo immediately.


getTriggerStates

public final Class<? extends ITriggerState>[] getTriggerStates()
Get the array of trigger state classes this combination listens to. Use reflection to find out which ITriggerState classes this combination listens to. Read all methods called "execute" and get all parameters that they have. Return an array of these parameters. Can be overridden when the default mechanism of registering triggers by implementing execute(ConcreteTrigger) is not wanted.

Will throw the unchecked IllegalArgumentException if there are execute methods with overlapping parameters found. In such case KIVi cannot decide in which order it should execute such methods. So this case is currently not supported.

Specified by:
getTriggerStates in interface ITriggerListener
Returns:
array of trigger states

latestState

protected final ITriggerState latestState()
Convenience method to obtain the trigger state that actually caused the execute method to be invoked. This can be used to conceptually go back from the states to the event, to find out which state was constructed last.

Returns:
the trigger state that was constructed last

latestStateIndex

protected final int latestStateIndex()
Convenience method to obtain the index of the trigger state that actually caused the execute method to be invoked. Use this index in a switch statement to implement different behavior depending on the latest trigger state. The result corresponds to the index in the order of parameters as given in the execute method header. Caution: The meaning of the returned indices may change when more parameters are added to the execute method, or when their order is modified.

Returns:
the index of the latest trigger state

undo

public void undo()
Attempt to undo all active effects, for example when shutting down view management or when disabling this combination. Schedules all undo immediately.

Specified by:
undo in interface ICombination

isActive

public final boolean isActive()
Check whether this combination is active.

Specified by:
isActive in interface ICombination
Returns:
true if the combination is active

setActive

public final void setActive(boolean a)
Change the active status of this combination.

Specified by:
setActive in interface ICombination
Parameters:
a - new active status

toString

public String toString()
Overrides:
toString in class Object