ButtonWidget
===============================================================================
``maongo.core.toolkit.ButtonWidget extends Widget``

.. note:: ########### gegenlesen laeuft / 24.3.11 ####################

Ein einfacher **Button** führt eine Aktion bei Klick aus::
  
  Beispiel 1:
  <?xml version="1.0" encoding="UTF-8"?>
  <presentation width="340" height="200">
    
    <!-- erster Button -->
    <widget name="TheButton1" type="Button" x="20" y="20" shape="R 50 50">
    <action trigger="button-clicked">
       this.BackgroundColor = "red";
    </action>
    </widget>
    
    <!-- zweiter Button -->
    <widget name="TheButton2" type="Button" x="90" y="20" shape="R 50 50">
    <action trigger="button-clicked">
      this.BackgroundColor = "yellow";
    </action>
    </widget>
    
    <!-- dritter Button -->
    <widget name="TheButton3" type="Button" x="160" y="20" shape="R 50 50">
    <action trigger="button-clicked">
      $(this, "TheButton1").BackgroundColor = "white";
      $(this, "TheButton2").BackgroundColor = "white";
      this.BackgroundColor = "green";
    </action>
    </widget>
  
  </presentation>

Bei Klick auf den ersten Button wird die Hintergrundfarbe von ``TheButton1`` auf rot gesetzt, bei Klick auf den zweiten Button wird die Hintergrundfarbe von ``TheButton2`` auf gelb gesetzt, und ein Klick auf den dritten Button setzt die Farbe der ersten beiden Buttons auf weiß und sich selber auf grün.

Ein **Data-Button** speichert ein ankommendes Data und sendet es bei Klick weiter::

  Beispiel 2:
  
  <!-- Data-Transmission -->
  <transmission id="1">
    <data action="Update">
      <property name="myColor" type="Color">#ffff00</property>
    </data>
  </transmission>

  <!-- Presentation -->
  <presentation>
    <route property="*" match="*" target="btn" />
    <widget name="btn" type="Button" location="10,10">
      <property name="DataMode" value="store-forward" />
      <route property="*" match="*" target="aWidget" />
    </widget>
    <widget name="aWidget" location="120,10">
      <bind property="BackgroundColor" to="DataObserver" key="myColor" />
      <property name="BorderWidth" value="1" />
    </widget>
  </presentation>
  
Das bei Aufruf der Presentation geladene Data wird an den Button geroutet und dort gespeichert, bis ein Klick erfolgt. Dann wird es anhand der in ``btn`` angegebenen Route weitergeleitet zu ``aWidget``, wo über ein Binding eine Property aus dem Data ausgelesen wird. ``aWidget`` wird die in ``myColor`` gespeicherte Farbe annehmen. Näheres zu Data und Binding siehe :ref:`ref-data`.

Eine **Buttongruppe** erlaubt das Umschalten zwischen verschiedenen Optionen:: 

  Beispiel 3:
  
  <presentation width="340" height="200">
    <widget name="btn1" type="Button" x="20" y="50" shape="R 2O 20">
      <property name="Mode" value="radio" />
      <property name="Group" value="myButtons" />
      <property name="State" value="on" />
    </widget>
    <widget name="btn2" type="Button" x="50" y="50" shape="R 2O 20">
      <property name="Mode" value="radio" />
      <property name="Group" value="myButtons" />
    </widget>
    <widget name="btn3" type="Button" x="80" y="50" shape="R 2O 20">
      <property name="Mode" value="radio" />
      <property name="Group" value="myButtons" />
    </widget>
    <widget name="btn4" type="Button" x="110" y="50" shape="R 2O 20">
      <action trigger="button-clicked">
      <![CDATA[
          // NYI: trace($(this, "Presentation").getButtonGroup('myButtons').getPressed());
          // see codebase #256 for bugs
          trace("Button 1:" + $(this, "btn1").State);
          trace("Button 2:" + $(this, "btn2").State);
          trace("Button 3:" + $(this, "btn3").State);
      ]]>
      </action>
    </widget>
    
  </presentation>

Beim Start der Presentation wird ``btn1`` eingeschaltet (State = `on`). Ein Klick auf ``btn2`` oder ``btn3`` wird ``btn1`` ausschalten und den geklickten Button einschalten. ``btn4`` gehört nicht zur ButtonGroup. Klick auf ``btn4`` gibt hier den aktuell gedrückten Button der ButtonGroup ``myButtons`` aus.


Funktionsweisen des ButtonWidgets
----------------------------------------

Das Button-Widget kennt drei Verhaltensweisen, die über die Property ``ButtonType`` eingestellt werden.

Die folgende Aufstellung gibt an, welche Zustandsänderungen bei zwei vollständigen Klicks auf den Button (Press und Release auf dem ButtonWidget) stattfinden und wann jeweils die Buttonaktionen ausgeführt werden.

Verhalten bei...

... ButtonType = ``"click"``::
  
    Aktion      State   Signal            Aktion?

    Press       'on'    button-pressed
    Release     'off'   button-released   ButtonAktion
    Press       'on'    button-pressed
    Release     'off'   button-released   ButtonAktion
  
... ButtonType = ``"toggle"``::

    Press       'on'    button-pressed
    Release     'on'                      ButtonAktion
    Press       'on'
    Release     'off'   button-released
  
... ButtonType = ``"radio"``::
  
    Press       'on'    button-pressed
    Release     'on'                      ButtonAktion
    Press       'on'
    Release     'on'

    ***Press*** 'off'   button-released
    (wird released bei Klick auf einen anderen Button der Gruppe)

Das direkte Setzen der Property ButtonState auf ``"on"`` bzw. ``"off"`` ist möglich, um eigene Buttonfunktionen zu implementieren. Eine solche Property-Änderung löst direkt ``button-pressed`` bzw. ``button-released`` aus, unabhängig vom ButtonType.

Mit der Property ``ActionOnPress`` lässt sich außerdem bewirken, dass die Buttonaktion bereits bei der Press-Aktion ausgeführt wird.

**Button und Data:**

Der Button verhält sich in Bezug auf Data, die durch die Anwendung geroutet werden, standardmäßig wie ein normales Widget: Es leitet das Data 
weiter, wenn entsprechende Routen auf dem Widget definiert sind. 

Zusätzlich speichert der Button das Data in seiner Property ``Data`` (was ein ``data``-Signal auslöst). Das ButtonWidget registriert sich 
außerdem als Listener für Änderungen im Data und sendet ein ``data-changed``-Signal, wenn sich das gespeicherte Data ändert.

Die Property DataMode ermöglicht es, dieses Verhalten zu modifizieren. Standardwert ist ``"route"``, mit der genau das geschilderte Verhalten 
erreicht wird.

Verhalten bei...

... DataMode = ``"store-forward"``:
  Das geroutete Data wird wie beschrieben gespeichert, und erst bei Klick wird das Data anhand der Routen weiter geroutet.

... DataMode = ``"request"``:
  Das geroutete Data wird wie beschrieben gespeichert, bei Klick wird ein Request gestartet, um eine Transmission von der in der Property 
  ``DataSource`` definierten URL abzuholen. Bei Eintreffen der Data-Transmission werden die enthaltenen Data anhand der Routen des 
  ButtonWidgets weiter geroutet.

Ein Data kann auch direkt der Property Data auf dem ButtonWidget zugewiesen werden. Ist dies der Fall, so wird das zugewiesene Data nicht 
automatisch weiter geroutet. Es ersetzt aber das gespeicherte Data und würde im DataMode ``store-forward`` bei Klick weiter geroutet.

**LabelTemplates:**

Der Button nutzt die Property ``Text``, um eine einfache Buttonbeschriftung anzuzeigen. 

Soll die Buttonbeschriftung spezifisch formatiert sein, so können Sie beliebige weitere Widgets in den Button legen, die die Darstellung übernehmen. Binden Sie an die Property Text des Buttons, um den Wert der Property an anderer Stelle zu verwenden.::


  Beispiel 4
  <presentation width="230" height="230">
    
    <widget name="mybutton" type="Button" x="30" y="30">
        <property name="Text" value="Button-Text" />
      
        <!-- dieses Textwidget wird als Label verwendet -->   
        <widget type="Text">
          <property name="ForegroundColor" value="orange" />
          <property name="TextAlign" value="right" />
          <bind property="Text" to="parent" key="Text" />
         </widget>
    
      </widget>
  
  </presentation>

Der Button ``mybutton`` nutzt ein vorformatiertes Textwidget; die Property ``Text`` des Childwidgets ist an die Property ``Text`` des Parents gebunden.

Properties
------------
Das ButtonWidget hat für zwei von Widget ererbte Properties andere Defaultwerte als das Widget:
  
  ``BorderWidth``: Default ``1.0``  (Widget: ``0.0``)
  
  ``Interactive``: Default ``true`` (Widget: ``false``)


Eigene Properties:

**ActionOnPress** (Boolean)
  Per Default werden Actions beim Loslassen (``button-released``) ausgeführt. Diese Property erlaubt es, dieses Verhalten zu modifizieren, um Aktionen bereits auf Drücken (``button-pressed``) auszuführen.
  
  Default: ``false``
  
**ButtonGroup** (String)
  Erlaubt die Zuordnung eines Buttons zu einer Gruppe. Ist der Typ der gruppierten Buttons ``radio``, so werden beim Einschalten eines Buttons alle anderen ausgeschaltet (wird der ButtonState auf ``0`` gesetzt). Ist der ButtonType ``toggle`` oder ``click``, so hat die ButtonGroup keinen Effekt.
  
  Gruppen gelten innerhalb einer Presentation.
  
  Default: ``""`` (keine ButtonGroup)

**ButtonState** (Symbol)
  Setzt den Zustand des Buttons auf ``on`` oder ``off``. Wenn damit eine State-Änderung einhergeht (d.h., wenn der Button nicht schon im gesetzten Zustand war), wird ein ``button-pressed``- oder ein ``button-released``-Signal gesendet.
  
  Default: ``"off"``

**ButtonType** (Symbol)
  Legt die Verhaltensweise des Buttons fest. Mögliche Werte sind: ``click``, ``toggle`` und ``radio``.
  
  Default: ``"click"``

**Data** (Object) : WidgetProperty
  Die Property erlaubt es, dem Button ein Data zuzuweisen (durch direktes Setzen der Property in einem JavaScript oder über Binding).
  
  Wird die Property ``Data`` auf ein Object vom Typ ``Data`` gesetzt, so sendet der Button ein ``data``-Signal. Ändert sich das gespeicherte Data, so sendet der Button ein ``data-changed``-Signal.
  
  Ein auf dem Button gespeichertes Data wird erst ersetzt, wenn ein neues Data einläuft oder gesetzt wird.
  
  Default: ``null`` (kein Data)
  
  Beispiel::
  
   <presentation width="230" height="230">
    
    <widget name="mybutton" type="Button" x="30" y="30">
      <property name="Shape" value="R 80,20"/> 
      <property name="Text" value="Button-Text" />
      <action trigger="data" args="d">
        trace("Data erhalten" + d);
      </action>
    </widget>
    
    
    <widget name="clickbtn" type="Button" x="30" y="50">
      <property name="Shape" value="R 80,20"/> 
      <property name="Text" value="set data" />
      <action trigger="button-clicked">
        var d = Type.newData("Hans");
        $(this,"mybutton").Data = d;
      </action>
    </widget> 
   </presentation>

**DataMode** (Symbol)
  Der DataMode ``store-forward`` legt fest, dass der Button ein auf ihn geroutetes Data automatisch in die Property Data speichert und erst bei Klick weiterleitet (entlang der gesetzten Routen). Der DataMode ``request`` legt fest, dass DataSource genutzt wird, um bei Klick eine Transmission anzufordern.
  
  Steht DataMode auf dem Defaultwert ``"route"``, so verhält sich das ButtonWidget wie ein normales Widget und leitet Data, die es empfängt, anhand seiner Routen direkt weiter.
  
  Werte: ``"route"``, ``"store-forward"``, ``"request"``
  
  Default: ``"route"`` (normales Widget-Verhalten, kein Data-Button)

**DataSource** (URL)
  Wenn der DataMode des Buttons ``request`` ist, wird bei Klick auf den Button eine Transmission von der in ``DataSource`` angegebenen URL geladen und das erste Data der Property Data zugewiesen. Enthält die Transmission weitere Data, so werden diese verworfen. Ist DataMode ``request`` und DataSource ``null``, so wird nichts geladen.
    
  Default: ``null`` (keine DataSource)
  
**Text** (String)
  Die Property erlaubt es, eine Buttonbeschriftung anzugeben.
  
  Default: ``""`` (Keine Beschriftung)

Methoden
-------------

**click**
  simuliert einen Klick auf den Button (was die Ausführung eines Klicks aus JavaScript heraus ermöglicht).

**press**
  simuliert einen Drücken auf dem Button.

**release**
  simuliert ein Loslassen auf dem Button.

Beispiel::

  $(this, "aButton").click()


Signale
-------------

**button-pressed**
  Signal, das anzeigt, dass der Button gedrückt wurde.
**button-released**
  Signal, das anzeigt, dass der gedrückte Button losgelassen wurde. Das Release ist auf dem Button selbst erfolgt.
**button-released-outside**
  Signal, das anzeigt, dass der gedrückte Button losgelassen wurde. Das Release ist nicht auf dem Button erfolgt.  
**button-clicked**
  Bei Mausbedienung das Signal, das einen vollständigen Klick (Press und Release innerhalb des Shape des Buttons) anzeigt.

Vgl. auch :ref:`ref-actions` und :ref:`ref-trigger`.