.. _ref-actions:

###############################################################################
Actions
###############################################################################
.. sectionauthor:: jo


.. note:: 

	Signals
	
	Signals und der <detect> tag sollten vor den Action abgehandelt werden.

Actions sind Scriptböcke in einer Maongo-Präsentation, die auf unterschiedliche
Weise ausgeführt werden können: Durch direkten Aufruf, über einen "trigger", als 
Teil einer Animation oder indem ein Data direkt auf die Action gerouted wird. 

Beispiel::

	<action name="goRed">
		this.BackgroundColor = "red";
		trace("Hello, World!");
	</action>


Skripte in einer Skriptingsprache sollen nicht vom XML-Parser behandelt werden 
und sollten daher in einem CDATA-Block stehen::
	
	<action language="javascript">
	<![CDATA[
		// ...
	]]>
	</action>
	
	
Die Scriptingsprache ist Javascript.
	

.. _ref-trigger:

Trigger
----------

Widgets senden Signale ("Signals") aus, mit denen Actions ausgeführt werden
können indem der Signalname als Trigger gesetzt wird.

Beispiel Buttonwidget::


	<widget type="Button">
	
		<property name="BackgroundColor" value="0x800000"/>
		
		<action trigger="button-pressed">
			this.BackgroundColor = "red";
		</action>
		
		<action trigger="button-released">
			this.BackgroundColor = "green";
		</action>
	
	</widget>




Trigger, die auf System- oder User-Signals reagieren::

	Data/Routen:
	<action trigger="data">
	<action trigger="data-changed">

	ButtonWidget: Maus ist auf dem Widget gedrückt/losgelassen worden:
	<action trigger="button-pressed">
	<action trigger="button-released">
	<action trigger="button-clicked">

	Allgemein: Maus ist auf dem Widget gedrückt/losgelassen worden:
	<action trigger="pointer-down">
	<action trigger="pointer-up">
	<action trigger="pointer-up-outside">

	Animation/Frame-Events:
	<action trigger="animation-play">
	<action trigger="frame" > ???? immer oder nur bei laufender Animation?
	<action trigger="animation-end">

aber auch selbstdefinierte Trigger sind möglich::

	<widget>
		<action language="js">
			signal("mao-test");
		</action>
		<action trigger="mao-test">
			// tu was
		</action>
	</widget>


Der ``action``-Tag
--------------------

::

	- trigger
		- Eine Action kann auch einen Trigger haben, 
		der auf einem anderen Widget registriert ist
	- name
		- Direktaufruf als Methode des Widgets
	- language
	- target


Eine Action kann auch einen Trigger haben, der auf einem anderen Widget registriert ist::

	<widget location="70,20" rect="160,30">
		<action trigger="btnOne:button-clicked">
			<set property="BackgroundColor" value="0xff0000"/>		
		</action>
		<action trigger="btnOne:button-released">
			<set property="BackgroundColor" value="0x0000ff"/>			
		</action>
	</widget>

Dieses Widget sollte sich umfärben, wenn auf btnOne geklickt wird!



Der ``set``-Tag
------------------


Actions = Methoden des Widgets
----------------------------------

- Benannte Actions direkt aufrufen

- Was ist der Vorteil, signal und trigger zu verwenden, gegenüber Methodenaufrufen mit <action name="Methodenname"> und Methodenname() in einer JS-Action?




Real-World-Beispiel
----------------------

Hier fehlt noch text... 

(inc_typ_kreis.mad):

- Eine Action in XML-Syntax, dann eine reihe von JavaScript-Actions.
- Die Actions "Setters" und "Scripts" werden durch entsprechendes Routing aufgerufen:

Eine Route geht direkt auf Setters: Dann ist kein trigger nötig, die Action wird ausgeführt, als (Default-)Argument enthält arg das geroutete Data.
Die Zweite Route geht auf das Widget "Scripts". Damit würde zunächst noch gar keine Action ausgeführt, es sei denn, sie hat einen entsprechenden Trigger (trigger="data").
Die Action "SetTotalValue" hat keinen Trigger, wird also nicht automatisch getriggert. Wenn Du in Zeile 84 guckst, siehst Du, dass die Action wie eine Methode in JavaScript aufgerufen wird: Das funktioniert, denn alle Actions, die in einem (Widget-)Kontext definiert werden, können auch direkt als Methoden aus JavaScript aufgerufen werden.





Rausgeworfen
-------------------

.. note:: Skripte im XML
	
	Skripte in einer Skriptingsprache sollen nicht vom XML-Parser behandelt werden 
und stehen daher in einem CDATA-Block::
	
	<action language="javascript">
	<![CDATA[
		// ...
	]]>
	</action>



In Actions kann der Autor einer Maongo/MP-Presentation in Abhängigkeit von User-Interaktionen, als Reaktion auf einlaufende Daten u.ä. Zustandsänderungen herbeiführen. 

Einfache Actions können vollständig im XML definiert werden; ist mehr Flexibilität vonnöten, als die XML-Syntax erlaubt, so kann der Template-Author Actions auch in JavaScript verfassen.

Beispiel für eine einfache Maus-Action::

	<widget name="btn" type="Button">
		<property name="BackgroundColor" value="0x800000"/>
		<action trigger="button-pressed" target="widget">
			<set property="BackgroundColor" value="0xff0000"/>
		</action>
		<action trigger="button-released" target="widget">
			<set property="BackgroundColor" value="0x800000"/>
		</action>
	</widget>

Auf dem Button-Widget sind zwei Actions definiert, die auf die Trigger ``button-pressed`` und ``button-released`` eine Zustandsänderung - hier die Änderung der Hintergrundfarbe des Widgets - herbeiführen.

Eine einfache JavaScript-Action kann so aussehen::

	<widget name="anim">
		<action trigger="frame" language="javascript" target="widget">
			this.Rotation = this.Rotation + 3;
		</action>
	</widget>

Hier wird bei jedem ``frame``-Event die Rotation-Eigenschaft des Widgets verändert.