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

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

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.
protected  ITriggerState getTriggerState()
          Convenience method to obtain the ITriggerState that actually caused the execute method to be invoked.
 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  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 undo 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
 

Constructor Detail

AbstractCombination

public AbstractCombination()
Method Detail

handle

public 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 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 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 void enableEffectRecording()
Activate recording of old effects. This way old effects can be easily undone lateron. However, if they are never undone, this record may increase over time as arbitrarily many old effects may be stored.


undoRecordedEffects

protected void undoRecordedEffects()
Explicit call to undo 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 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

getTriggerState

protected ITriggerState getTriggerState()
Convenience method to obtain the ITriggerState 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

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 boolean isActive()
Check whether this combination is active.

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

setActive

public 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