View Management (KIVi)

1

2

This project is currently not developed further.

3

4

5

== Project Overview ==

6

Related Publications:

7

8

* Hauke Fuhrmann and Reinhard von Hanxleden. On the Pragmatics of Model-Based Design. In //Foundations of Computer Software. Future Trends and Techniques for Development—15th Monterey Workshop//, Revised Selected Papers, vol. 6028 of LNCS, p. 116–140, Springer, 2010. ([[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/monterey08-proceedings.pdf||shape="rect"]]) The original publication is available at [[link.springer.com>>url:http://link.springer.com||shape="rect"]].

9

* Hauke Fuhrmann and Reinhard von Hanxleden. Taming Graphical Modeling. In //Proceedings of the ACM/IEEE 13th International Conference on Model Driven Engineering Languages and Systems// (MoDELS’10), vol. 6394 of LNCS, p. 196–210, Springer, 2010. ([[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/models10.pdf||shape="rect"]]) The original publication is available at [[link.springer.com>>url:http://link.springer.com||shape="rect"]].

Related Theses:

* Nils Beckel, //View Management for Visual Modeling//, October 2009. ([[pdf>>url:http://rtsys.informatik.uni-kiel.de/%7Ebiblio/downloads/theses/nbe-dt.pdf||shape="rect"]])

14

* Martin Müller, //View Management for Graphical Models//, December 2010. ([[pdf>>url:http://rtsys.informatik.uni-kiel.de/%7Ebiblio/downloads/theses/mmu-mt.pdf||shape="rect"]])

15

* Hauke Fuhrmann, //On the Pragmatics of Graphical Modeling//, 2011. Disputation: May 5th, 2011 ([[pdf>>url:http://eldiss.uni-kiel.de/macau/receive/dissertation_diss_00007185||shape="rect"]])

== Introduction ==

KIELER View Management (KIVi) is a high-level description engine for dynamic visualizations in diagrams (e.g. for graphical modeling). Its main driver is the availability of automatic layout as provided by KIML. It implements user interaction that builds upon automatic layout and therefore unfolds the full potentials of automatic layout. Different use-case examples are:

20

21

* Navigating in complex models using "Focus&Context"

22

** Show currently "interesting" elements in the Focus with full detail

23

** Show other elements as the Context in reduced detail (e.g. compartments collapsed, labels hidden)

24

* Use execution/simulation results for interactive debugging visualization of diagrams

25

* Perform editing by executing model-to-model transformations on the domain model while view management updates the diagram view

== User Guide ==

KIVi provides two preference pages to configure the view management. The first page lets you activate the view management itself and any combination you need. The second page shows all properties of all combinations registered with KIVi.

30

31

[[image:attach:preferences_kivi.png]][[image:attach:preferences_combinations.png]]

32

33

Enabling View Management Combinations will start the corresponding interaction paradigm automatically. It might react on internal Eclipse or Simulation events or it might wait for buttons pressed by the user. The result usually alters the currently visible diagrams.

34

35

== Developer Guide ==

36

37

The core view management uses three interacting components: Triggers, Combinations, and Effects. Implementing a new use-case for view management usually stays on a rather high-level abstraction of a //Combination// which specifies, //under what conditions// (triggers) a diagram should be displayed //in what way// (effects), e.g. in what level of detail. //Triggers// and //Effects// are low-level implementations of specific events resp. graphical effects in a diagram that Combinations work with. As KIELER provides a set of pre-defined triggers and effects (see list below), a developer might only work at the level of an Combination. Only if the provided triggers and effects are not enough for your combination, you need to delve a little bit deeper into Eclipse to extend KIVi by your own triggers/effects.

=== Examples ===

**See the running example [[ManualFocusCombination.java source code>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/ManualFocusCombination.java||shape="rect"]] as an example how simple implementation of a new view management use-case is.**

42

43

Find more minimal examples in the

44

45

* [[Unit Tests with many minimal examples>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/test/de.cau.cs.kieler.core.kivi.test||shape="rect"]]

=== Triggers ===

A Trigger is a low-level observer that notifies the view management about certain events. Each Trigger has an associated TriggerState class that handles these events and presents them as the current state to the combinations.

50

51

Every Trigger needs to implement the [[ITrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/ITrigger.java||shape="rect"]] interface, most conveniently by extending [[AbstractTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/AbstractTrigger.java||shape="rect"]]. Analogously the TriggerStates need to implement [[ITriggerState>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/ITriggerState.java||shape="rect"]] or extend [[AbstractTriggerState>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/AbstractTriggerState.java||shape="rect"]]. Extending the abstract classes is the recommended method to avoid re-implementation of some core features: Using the abstract implementation, a new Trigger only needs to call its own trigger(ITriggerState) method with a new instance of its TriggerState representing the new event whenever a new event needs to be passed to the view management.

52

53

==== Synchronization ====

54

55

It may happen that Triggers fire way too often and flood the system with too many events. In such case Combinations are also called very often and will flood the EffectsWorker queue with too many effects and the effects queue can overflow, resp. effects will not be executed in a reasonable time after the causing trigger.

56

57

If it is known in advance that a trigger might occur often, it can be synchronized with the effects queue. Call AbstractTrigger.synchronizedTrigger(ITriggerState) instead of the normal trigger method in order to block the current thread until all effects have been executed that have been caused by this triggering. This way backpressure can be induced from effects to the triggers.

58

59

Technically the synchronized step calls wait() on the corresponding TriggerState. The CombinationsWorker thread puts all effects resulting from a Combination onto the EffectsWorker's queue. Afterwards it also puts an UnlockEffect onto the queue with the corresponding TriggerState as parameter. The EffectsWorker thread eventually will take the UnlockEffect from the queue after all effects have been executed and will notifyAll() who listen to the given TriggerStates. This guarantees time-synchronization between the three involved threads, i.e. the Trigger will be blocked until the EffectsWorker has released the old TriggerState. Note that this may deadlock, e.g. if the Trigger executes in the UI thread, i.e. it blocks the UI thread and one effect also executes in the UI thread (e.g. LayoutEffect). Then this effect will wait for the Trigger and the Trigger waits for completion of all effects -> Deadlock. As many effects could arbitrarily work on the UI thread, avoid using synchronizedStep() in a Trigger that calls from the UI thread.

=== Combinations ===

Combinations bind Triggers and Effects together: A Combination is notified of updated TriggerStates that concern the Combination, and the Combination launches appropriate Effects to visualize these for the user.

64

65

Similarly to Triggers there is both an interface [[ICombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/ICombination.java||shape="rect"]] and an abstract class [[AbstractCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/AbstractCombination.java||shape="rect"]], either could be used to create a new combination. However, it is strongly recommended to use the abstract superclass because a lot of convenience is already built into it. That way you only need to implement an execute(TriggerState1, TriggerState2, ...) method that takes all TriggerState types you need as a parameter, all details such as making sure the corresponding Triggers are activated is already taken care of. This way the combination developer only needs to implement a very small and high-level part in KIVi as marked in the above sequence diagram.

66

67

The AbstractCombination provides a very convenient Effect handling mechanism. In order to launch an Effect you only need to call schedule(theEffect), the abstract implementation will take care of the rest. Specifically, all Effects are automatically undone when the entire combination is undone (e.g. disabled). Effects can be easily recorded to be explicitly undone, e.g. when one execution wants to undo the effect of earlier executions. Just call undoRecordedEffects() in an execute method. This removes the need for any Effects housekeeping within the Combination, for example remembering which Effects have been executed in the past and which need to be undone now. You simply schedule the Effects necessary to produce the desired state, independently of any past Effects - the Effects merging mechanism will take care of any redundant operations.

68

69

Combinations can contribute parameters to the KIVi Combinations preference page by implementing the static method [[CombinationParameter>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/CombinationParameter.java||shape="rect"]][] getParameters(). As of now, the preference page supports Strings, Integers, Floats, Doubles, Booleans and RGB color values. These parameters will automagically appear on the Combinations preference page as posted in the User Guide above.

70

71

In order to let KIVi know about your combinations you need to create an extension for the [[Combinations extension point>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/schema/de.cau.cs.kieler.core.kivi.combinations.exsd||shape="rect"]].

=== Effects ===

An Effect applies some visual change to the diagram, for example it might perform automatic layout. All Effects are created and scheduled by Combinations, their execution is done from within the Effects worker thread.

76

77

New Effects are implemented by implementing [[IEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/IEffect.java||shape="rect"]] or preferably by extending [[AbstractEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/AbstractEffect.java||shape="rect"]]. Then you only need to implement the execute() method, and override undo() if your Effect can be undone.

78

79

Many Effects are mergeable, for example if two Layout Effects are scheduled then one layout run would suffice. In order to support merging your Effect needs to let isMergeable() return true and implement merge(IEffect). The merge() method returns null by convention if the two Effects can not be merged, and it returns the newly merged Effect (usually itself with some modifications) if the two Effects can be merged - then the other Effect is automatically discarded. Correct merging of Effects is particularly important for the automatic scheduling/undoing mechanism in the AbstractCombination. It will often undo an effect right after scheduling its execution, and give programmer convenience in the Combination in return.

80

81

== Implemented Features ==

82

83

Follow the Javadoc links to see the corresponding //package// for the triggers, effects and combinations. It also gives a hint, which //plug-ins// to load in order to get access to the classes in your own plug-in.

84

85

=== Trigger(States) ===

86

87

* [[SelectionTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model/src/de/cau/cs/kieler/core/model/triggers/SelectionTrigger.java||shape="rect"]] - Contains the most recent list of selected EObjects and the containing DiagramEditor

88

* [[ButtonTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/menu/ButtonTrigger.java||shape="rect"]]- Generic TriggerState for KIVi buttons registered using the ButtonHandler. Buttons can be defined

89

** using the standard Command extension point of eclipse and by using the [[ButtonHandler>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/menu/ButtonHandler.java||shape="rect"]] as the handler, or

90

** defining a button programmatically, e.g. in the constructor of a Combination, using the [[KiviMenuContributionService>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/menu/KiviMenuContributionService.java||shape="rect"]]. See an example Combination in [[KiviMenuContributionDemoCombination.java>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/menu/KiviMenuContributionDemoCombination.java||shape="rect"]]

91

* [[EffectTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/triggers/EffectTrigger.java||shape="rect"]] - Triggered when a KIVi Effect has been executed

92

* [[ModelChangeTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/triggers/ModelChangeTrigger.java||shape="rect"]] - Contains the most recent change to a semantic model

93

* [[ModelChangeTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/triggers/ModelChangeTrigger.java||shape="rect"]].DiagramChangeState - Contains the most recent change to a GMF diagram model

94

* [[ModelChangeTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/triggers/ModelChangeTrigger.java||shape="rect"]].ActiveEditorState - Information about the active editor (not necessarily containing a diagram)

95

* [[DiagramTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model/src/de/cau/cs/kieler/core/model/triggers/DiagramTrigger.java||shape="rect"]] - Information about the active diagram (e.g. in the active editor or view), used instead of ActiveEditorState with convenient access to diagram and semantic model

96

97

Synccharts and Papyrus UML StateMachine specific

98

99

* [[StateActivityTrigger>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.sim.kivi/src/de/cau/cs/kieler/sim/kivi/StateActivityTrigger.java||shape="rect"]] - receives the most recent n steps of active states from the KIVi-KIEM data component during simulation of Synccharts or Ptolemy UML StateMachines

=== Effects ===

* [[UndoEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/UndoEffect.java||shape="rect"]] - Pseudo-Effect used to simplify undoing Effects. The only point of contact as a developer is when merging Effects, the other Effect passed may be an UndoEffect containing the actual Effect

104

* [[MenuItemEnableStateEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/menu/MenuItemEnableStateEffect.java||shape="rect"]] - Change the enabled state of a button defined with KVi

105

* [[LayoutEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.ui/src/de/cau/cs/kieler/kiml/ui/diagram/LayoutEffect.java||shape="rect"]] - Performs automatic layout with various options

106

* [[SetOptionsEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.ui/src/de/cau/cs/kieler/kiml/ui/diagram/SetOptionsEffect.java||shape="rect"]] - Sets layout option values for a specific model element

107

* [[HighlightEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/effects/HighlightEffect.java||shape="rect"]] - Provides different methods of highlighting an EObject: Change its color, line width, or line style without changing the notation model

108

* [[CompartmentCollapseExpandEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/effects/CompartmentCollapseExpandEffect.java||shape="rect"]] - Collapse or expand a compartment without changing the notation model

109

* [[ArrowEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/ArrowEffect.java||shape="rect"]] - Draws an arrow between two EObjects

110

* [[AnalysisEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.grana/src/de/cau/cs/kieler/kiml/grana/handlers/AnalysisEffect.java||shape="rect"]] - Performs graph analysis and shows results in the Analysis view

111

* [[FocusContextEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/effects/FocusContextEffect.java||shape="rect"]] - Reduce level of detail for context elements, show all details for focus elements (e.g. by collapsing/expanding compartments)

112

* [[TransformationEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model/src/de/cau/cs/kieler/core/model/effects/TransformationEffect.java||shape="rect"]] - Executes a model to model transformation according to passed information.

113

* [[RefreshGMFEditPoliciesEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/effects/RefreshGMFEditPoliciesEffect.java||shape="rect"]] - Refreshes the EditPolicies of an GMF editor.

114

* [[UnlockEffect>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.kivi/src/de/cau/cs/kieler/core/kivi/UnlockEffect.java||shape="rect"]] - Notify all waiting threads on a given Object. Can be used to synchronize threads with the execution of effects.

=== Combinations ===

* [[LayoutCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.ui/src/de/cau/cs/kieler/kiml/ui/diagram/LayoutCombination.java||shape="rect"]] - Performs automatic layout after key combo/layout button is pressed

119

* [[RandomLayoutCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.ui/src/de/cau/cs/kieler/kiml/ui/diagram/RandomLayoutCombination.java||shape="rect"]] - Perform random layout without changing any layout options.

120

* [[KSBasECombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.ksbase.ui/src/de/cau/cs/kieler/ksbase/ui/kivi/KSBasECombination.java||shape="rect"]] - Used to execute a ksbase transformation.

121

* [[LayoutAfterCollapseExpandCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.gmf/src/de/cau/cs/kieler/kiml/gmf/combinations/LayoutAfterCollapseExpandCombination.java||shape="rect"]] - Performs layout after a compartment was collapsed or expanded

122

* [[ShowHierarchyCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.core.model.gmf/src/de/cau/cs/kieler/core/model/gmf/combinations/ShowHierarchyCombination.java||shape="rect"]] - Paints the diagram like a rainbow depending on the hierarchy levels

123

* [[LayoutAnalysisCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kiml.grana/src/de/cau/cs/kieler/kiml/grana/handlers/LayoutAnalysisCombination.java||shape="rect"]] - Performs automatic analysis after layout

124

* [[ManualFocusCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/ManualFocusCombination.java||shape="rect"]] - Do Focus&Context viewing, where the focus are the selected elements in a diagram. Currently supported for Synccharts and KAOM-Diagrams.

125

* [[E2STransformationCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.kies/src/de/cau/cs/kieler/kies/kivi/E2STransformationCombination.java||shape="rect"]] - Performs a Esterel to Synccharts transformation and following a Synccharts optimization.

Synccharts specific

* [[LayoutAfterModelChangedCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/LayoutAfterModelChangedCombination.java||shape="rect"]] - Performs layout after the model was changed

130

* [[SignalFlowCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/SignalFlowCombination.java||shape="rect"]] - Displays the Dual Model

131

* [[SyncChartsCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.kivi/src/de/cau/cs/kieler/synccharts/kivi/SyncChartsCombination.java||shape="rect"]] - Highlights/Collapses/Expands states during simulation

132

* [[HighlightSelectedTransitionsCombination>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.diagram.custom/src/de/cau/cs/kieler/synccharts/diagram/custom/HighlightSelectedTransitionsCombination.java||shape="rect"]] - Higlights selected transitions (and all children) in Synccharts. Used to better see which transition belongs to which label.

Wiki source code of View Management (KIVi)

Navigation

Quick Links