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 Data und Routen.
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.
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...
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.
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:
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
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)
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"
Legt die Verhaltensweise des Buttons fest. Mögliche Werte sind: click, toggle und radio.
Default: "click"
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>
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)
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)
Die Property erlaubt es, eine Buttonbeschriftung anzugeben.
Default: "" (Keine Beschriftung)
Beispiel:
$(this, "aButton").click()