In vielen Fällen sind die Rich-UI-Widgets EGL-Handlerabschnitte vom Stereotyp RUIWidget.
Ausnahmen
von dieser Regel sind die Widgets 'Tooltip', 'DataGridTooltip' und 'TreeTooltip', die alle vom Stereotyp
RUIHandler sind, sowie die Dojo-Widgets, die alle auf einem externen Typ basieren.
Sie können sich über die Eigenschaften und Funktionen, die für einen Widgettyp verfügbar sind, mit einer
der folgenden Methoden informieren:
- Wenn Sie mit einem deklarierten Widget arbeiten wollen, verwenden Sie Content-Assist:
- Geben Sie den Widgetnamen und einen Punkt ein.
- Drücken Sie die Tastenkombination Strg-Leertaste.
- Alternativ können Sie die EGL-Dateien untersuchen, die den Widget-Code enthalten.
Details zu bestimmten Widgettypen finden Sie in den folgenden Quellen:
- Projekt 'com.ibm.egl.rui', Ordner 'EGLSource', Paket 'com.ibm.egl.rui.widgets'
- Projekt 'com.ibm.egl.rui.dojo.widgets', Ordner 'EGLSource', Paket 'dojo.widgets'
Verwenden Sie immer die Punktsyntax für den Zugriff auf eine Funktion oder Eigenschaft. Beispiel:
myWidget.myFunction() oder myWidget.myProperty.
Für die meisten Widgets verfügbare Eigenschaften
Die meisten EGL-Eigenschaften sind
nur für EGL-Systemcode verfügbar und stehen während der Ausführung nicht zur Verfügung. Allerdings handelt es
sich bei Widgeteigenschaften um Felder, die während der Ausführung für Ihren Code
verfügbar sind.
Stilbezogene Eigenschaften wie class und style
sind für alle von IBM gelieferten Widgets verfügbar. Details zu Stilen finden Sie im Abschnitt “Widgetstile”.
Die folgenden
Eigenschaften sind für die Entwicklung von Geschäftsanwendungen nützlich:
- children: Diese Eigenschaft ermöglicht den Zugriff auf eine Feldgruppe von untergeordneten
Widgets, sofern vorhanden. Detaillierte Informationen finden Sie in einem späteren Abschnitt.
- class: Diese Eigenschaft gibt eine Cascading Style Sheet-Klasse (CSS-Klasse) an,
die für die Anzeige des Widgets verwendet wird.
- disabled: Diese Eigenschaft akzeptiert einen booleschen Wert, der angibt, ob das Widget
inaktiviert ist. Ein inaktiviertes Widget kann nicht auf Ereignisse antworten und sein Text wird in den meisten
Browsern grau angezeigt.
- id: Diese Eigenschaft akzeptiert eine Zeichenfolge, die dazu dient,
eine Kennung (ID) für ein bestimmtes Widget zuzuordnen oder abzurufen. Sie können die ID in einem
Cascading Style Sheet (CSS) zur Angabe der Stilmerkmale für das betreffende Widget verwenden.
Wenn Sie EGL und JavaScript-Bibliotheken integrieren,
bietet diese Eigenschaft außerdem die Möglichkeit, eine ID für die Verwendung durch die
JavaScript-Logik zuzuordnen.
Wenn das Widget (z. B. ein Feld - 'Box'), einer untergeordneten DOM-Baumstruktur und nicht
einem bestimmten DOM-Element entspricht, gilt die ID für das DOM-Element der höchsten Ebene
in der untergeordneten Baumstruktur. Eine Einführung in DOM finden Sie im Abschnitt
“Informationen zur Verarbeitung einer Rich-UI-Anwendung in Browsern”.
- position: Diese Eigenschaft gibt die Bedeutung der X- und Y-Koordinaten
des Widgets an und akzeptiert einen der folgenden Werte:
- static
- Die X- und die Y-Koordinate des Widgets werden ignoriert, wie
dies das Standardverhalten ist. Die angezeigte Position ändert sich, wenn Sie den X-Wert und den Y-Wert
zu Anfang festlegen, wenn position den Wert static
hat, und den Wert für position anschließend ändern.
- absolute
- Die X- und die Y-Koordinate des Widgets, die Sie zuordnen und die Sie erhalten, sind unterschiedlich.
- Der Wert, den Sie zuordnen, muss relativ zum linken oberen Ursprungspunkt des nächsten nicht statischen
übergeordneten Elements sein. Diese Koordinaten werden durch den Wert von
alignment nicht beeinflusst.
- Die Werte der X- und der Y-Koordinate des Widgets, die Sie aus einem Widget erhalten, sind weiterhin
relativ zum Browser, einschließlich der Höhe der Schiebeleiste.
- relative
- Die X- und Y-Koordinaten des Widgets sind relativ zur linken oberen Ecke des
übergeordneten Elements. Wenn das übergeordnete Element des Widgets das Dokumentelement ist,
sind die Koordinaten relativ zur linken oberen Ecke des Anzeigebereichs des Browsers.
- tabIndex: Diese Eigenschaft akzeptiert einen ganzzahligen Wert, der
die Platzierung des Widgets in einer Tabreihenfolge angibt. Beispiel: Ein Widget, dem der Wert 2 für
tabIndex zugeordnet ist, empfängt den Fokus, wenn der Benutzer ein Widget, das den
Wert 1 für tabIndex hat, mithilfe der Tabulatortaste verlässt. Sie können Nummern
wie 10 und 20 (anstelle von 1 und 2) verwenden, um später weitere Widgets hinzufügen zu können.
Die Standardtabreihenfolge ist vom Browser abhängig.
- Die Werte x und y sind ganze Zahlen,
die sich auf die X- und Y-Koordinate des Widgets beziehen. Die Bedeutung dieser Koordinate variiert
abhängig vom Wert der Eigenschaft position.
Wie in der Beschreibung der Eigenschaft position erwähnt, ist der
grafische Ursprung entweder die linke obere Ecke des Browserfensters oder die linke obere Ecke
eines übergeordneten Widgets. Es gelten folgenden Regeln:
- Der x-Wert ist rechts vom Ursprung positiv und links vom Ursprung negativ.
- Der y-Wert ist unter dem Ursprung positiv und über dem
Ursprung negativ.
Sie können ein Widget außerhalb des übergeordneten Elements und sogar
außerhalb des sichtbaren Bereichs platzieren.
- zIndex: Diese Eigenschaft akzeptiert einen ganzzahligen Wert, der die Position
des Widgets angibt, d. h. seine Nähe zur Frontseite in Bezug auf andere Widgets an derselben X- und
Y-Position. Ein Widget mit einem relativ großen Wert für zIndex (z. B. 4) ist näher
an der Frontseite als ein Widget mit einem relativ kleinen Wert für zIndex (z. B.
2). Der Wert für zIndex hat keine Auswirkung, wenn der Wert für
position statisch ist.
Die folgenden Eigenschaften sind
insbesondere für die Entwicklung neuer Widgettypen nützlich, die auf dem Stereotyp
RUIWidget
basieren:
- innerHTML: Diese Eigenschaft ist eine Zeichenfolge, die zum Zuordnen oder
Abrufen eines HTML-Codes in einem Container wie zum Beispiel einem Widget 'Div', 'FloatLeft' oder
'FloatRight' verwendet wird.
- innerText: Diese Eigenschaft ist eine Zeichenfolge, die zum Zuordnen oder
Abrufen von Text in einem Container verwendet wird. Mit der Eigenschaft innerText
können Sie eine Texteigenschaft angeben, die für den Typ spezifisch ist.
- logicalParent: Diese Eigenschaft wird für die Entwicklung von Widgettypen
verwendet, die Container sind. Beim Schreiben des Codes, der dem Container untergeordnete Elemente hinzufügt,
legen Sie die Eigenschaft logicalParent so fest, dass sie auf das entsprechende
übergeordnete DOM-Element verweist. Eine Einführung in DOM finden Sie im Abschnitt
“Informationen zur Verarbeitung einer Rich-UI-Anwendung in Browsern”.
Beispiel: In Bezug auf das untergeordnete Element eines Felds ('Box') verweist die Eigenschaft
parent nicht auf das Feld, sondern auf ein DOM-Element 'TD' in einem DOM-Element
'Table'.
Die Eigenschaft logicalParent verweist jedoch auf das DOM-Element 'Div',
das das Feld darstellt und das übergeordnete Element des DOM-Elements 'Table' ist.
Die Eigenschaft
parent bezieht sich auf die Entwicklung von Widgettypen und ermöglicht
den Zugriff auf ein übergeordnetes DOM-Element.
Eine Einführung in DOM finden Sie im Abschnitt “Informationen zur Verarbeitung einer Rich-UI-Anwendung in
Browsern”.
Die folgenden Eigenschaften sind für die Interaktion mit Benutzern gedacht, die
Arabisch oder Hebräisch lesen:
Die folgenden Eigenschaften fügen barrierefreie
Bedienungsmöglichkeiten hinzu:
- ariaLive: Diese Eigenschaft gibt die Unterstützungsstufe an, die für
Technologie zur behindertengerechten Bedienung bereitgestellt wird; das heißt, für Sprachausgabeprogramme,
die Benutzer von Aktualisierungen an Anzeigenbereichen benachrichtigen können. Die Spezifikation für eine
solche Technologie finden Sie unter der folgenden Adresse:
http://www.w3.org/TR/wai-aria
Der Wert für
ariaLive ist eine Zeichenfolge in Anführungszeichen ("off", "polite", "assertive" oder "rude"),
die alle im Abschnitt property: live der Spezifikation beschrieben werden.
- ariaRole: Diese Eigenschaft gibt die Rolle an, die für das Widget angegeben
ist, wie sie für die Technologie für behindertengerechte Bedienung verwendet wird. Details finden Sie in der
oben angegebenen Spezifikation.
Der Wert für ariaRole ist eine in Anführungszeichen gesetzte Zeichenfolge wie
"button" oder "listbox", die jeweils im Abschnitt Roles der Spezifikation beschrieben werden.
Für die meisten Widgets verfügbare Funktionen
Die folgenden Funktionen sind für
alle von IBM gelieferten Widgets vom Typ
RUIWidget verfügbar:
- Die Funktion fadeIn bewirkt, dass das Widget allmählich eingeblendet wird
(zur langsamen Darstellung). Die Funktion fadeOut bewirkt, dass das Widget
langsam ausgeblendet wird (langsam unsichtbar gemacht wird):
fadeIn (duration int in, callback EffectCallback)
fadeOut (duration int in, callback EffectCallback)
Jede Funktion akzeptiert
zwei Parameter:
- duration
- Die Anzahl Millisekunden zwischen Beginn und Ende des Prozesses, durch den das Widget langsam ein- bzw.
ausgeblendet wird.
- callback
- Eine Referenz auf eine Funktion, die aufgerufen wird, sobald das Widget langsam ein-
oder ausgeblendet wird. Diese Funktion akzeptiert keine Parameter und hat keinen
Rückgabewert. Wenn Sie keine Funktion angeben wollen, setzen Sie dieses Argument auf
den Wert null.
Beispiel:
myButton.fadeOut(1000, null);
- Die Funktion focus bewirkt, dass das Widget den Fokus erhält:
focus()
Eine Schaltfläche im Fokus wird hervorgehoben und das Drücken der Eingabetaste
durch den Benutzer ist äquivalent zum Anklicken der Schaltfläche durch den Benutzer. Analog enthält ein Textfeld
im Fokus (sofern es nicht schreibgeschützt ist) einen Cursor, sodass der Benutzer Daten eingeben kann, indem er
ein druckbares Zeichen anschlägt, ohne zuerst mithilfe der Tabulatortaste das Feld anzusteuern.
Der Benutzer
kann die Tabulatortaste wiederholt drücken, um reihum zu den verfügbaren Feldern zu navigieren. Mit jedem Tastendruck
wird der Fokus zum nächsten Anwendungsfeld oder zu einem Feld im Browser versetzt, wie zum Beispiel zum Feld für
die Webadresse.
Das folgende Beispiel zeigt einen Aufruf der Funktion
focus:
myButton.focus();
- Die Funktion morph ermöglicht das Ändern der Anzeige eines Widgets im
Verlauf einer Zeitdauer. Die Funktion ruft eine Ihrer Funktionen wiederholt auf. Dadurch gibt Ihr Code
das Verhalten an, das durch den Laufzeitaufruf veranlasst wird:
morph (duration int in, callback EffectCallback, customMorphFunction MorphFunction )
Die
Funktion akzeptiert drei Parameter:
- duration
- Die Anzahl Millisekunden zwischen Beginn und Ende des Prozesses.
- callback
- Eine Referenz auf eine Funktion, die aufgerufen wird, sobald der Prozess abgeschlossen ist. Diese Funktion akzeptiert keine Parameter und hat keinen
Rückgabewert.
Wenn Sie keine Funktion angeben wollen, setzen Sie dieses zweite Argument auf
den Wert null.
- customMorphFunction
- Eine Referenz auf eine angepasste Umwandlungsfunktion, das heißt eine Funktion, die
wiederholt während der oben angegebenen Zeitdauer aufgerufen wird. Die angepasste Umwandlungsfunktion
akzeptiert zwei Parameter: das Widget, das geändert wird, und eine Gleitkommazahl, die durch
die EGL-Laufzeit zugeordnet wird. Die Gleitkommazahl gibt eine Bruchzahl zwischen 0 und 1 an,
die den Fortschritt in Bezug auf das Ende der Zeitdauer beschreibt.
(Bei jedem Aufruf der angepassten Umwandlungsfunktion ist der Wert dieser Gleitkommazahl
größer.) Dieser Bruchwert basiert auf einer Berechnung der Anzahl der Male, die die angepasste
Umwandlungsfunktion in der verfügbaren Dauer aufgerufen wird, und der Zeitdauer,
die zur Ausführung der angepassten Logik erforderlich ist. Die angepasste Umwandlungsfunktion
hat keinen Rückgabewert.
Beispiel:
myButton.morph(1000, null, myCustomMorphFunction);
- Die Funktion resize ermöglicht das Ändern der Größe eines
Widgets im Verlauf einer Zeitdauer:
resize (width int in, height int in,
duration int, callback EffectCallback)
Die Funktion akzeptiert vier Parameter:
- width
- Die gewünschte Endbreite in Pixeln.
- height
- Die gewünschte Endhöhe in Pixeln.
- duration
- Die Anzahl Millisekunden zwischen Beginn und Ende des Prozesses.
- callback
- Eine Referenz auf eine Funktion, die aufgerufen wird, sobald der Prozess abgeschlossen ist. Diese Funktion akzeptiert keine Parameter und hat keinen
Rückgabewert.
Wenn Sie keine Funktion angeben wollen, setzen Sie dieses Argument auf
den Wert null.
Beispiel:
myButton.resize(100, 100, 1000, myFunction);
Eigenschaft 'children' und zugehörige Funktionen
In “Rich-UI-Widgets” wird
eine Untergruppe von Widgets als “Container-Widgets” kategorisiert. Diese Widgets enthalten die Eigenschaft
children, die eine Feldgruppe von untergeordneten Widgets angibt. Jedes Element in der
Feldgruppe bezieht sich auf ein benanntes Widget oder ein anonymes Widgets, wie nachfolgend beschrieben:
- Ein benanntes Widget wird außerhalb der Feldgruppe 'children' deklariert, wie dies für jedes Widget
im folgenden Code der Fall ist:
myInTextField TextField{};
myButton Button{ text = "Input to Output", onClick ::= click };
myOutTextField TextField{};
myBox Box{ columns = 3,
children = [ myInTextField, myButton, myOutTextField ]};
Wenn die
Feldgruppe ein benanntes Widget mehrfach referenziert, wird nur die letzte Referenz verwendet und die übrigen
Referenzen werden ignoriert.
- Eine anonyme Deklaration beginnt mit dem Schlüsselwort new
und kann in Ihrem Code nicht referenziert werden. Sie ermöglicht das Erstellen eines Widgets
in dem Moment, in dem Sie über die Platzierung des Widgets nachdenken:
myInTextField TextField{};
myTextOutField TextField{};
myBox box{columns=3,
children=[myInTextField,
new Button{ text = "Input to Output", onClick ::= click},
myOutTextField]};
In vielen Fällen ist das übergeordnete
Widget vom Typ 'Box' oder 'Div' und die Platzierung der unterordneten Widgets wird vom übergeordneten Typ
beeinflusst:
- Ein Widget 'Box' enthält die Eigenschaft columns. Der Wert dieser Eigenschaft
gibt die Standardplatzierung jedes Widgets an, das in der Feldgruppe children
aufgelistet ist.
Beispiel: Bei Angabe von columns=1 werden die Widgets, die in der Feldgruppe
aufgelistet sind, in nur einer vertikalen Spalte angezeigt. Bei der Angabe columns=2 wird
jedes zweite Widget in der zweiten Spalte und das nachfolgende Widget (z. B. das dritte in der Feldgruppe)
in der ersten Spalte der nächsten Zeile angezeigt.
Im Allgemeinen gilt, dass, wenn columns den Wert n hat, das Widget
an Position n+1 in der Feldgruppe in der ersten Spalte einer neuen Zeilen angezeigt wird. Wenn Sie keinen
Wert für columns angeben, werden die untergeordneten Elemente des Widgets 'Box'
nach rechts ausgerichtet.
- Die untergeordneten Elemente eines Widgets 'Div' werden nach rechts ausgerichtet angezeigt. Bei
Bedarf wird eine horizontale Schiebeleiste angezeigt, um den Zugriff auf Widgets zu ermöglichen, die
sich rechts außerhalb des sichtbaren Bereichs befinden.
Widgets vom Typ 'Div', die
untergeordnete Elemente eines anderen Widgets sind, werden vertikal jeweils eines unter dem anderen
angezeigt.
Sie können der Eigenschaft
children in jeder Funktion einen
anderen Wert zuordnen und so die Webseite ändern. (In ähnlicher Weise können Sie der Eigenschaft
initialUI in der onConstruction-Funktion einen anderen Wert zuordnen.)
Die folgende Syntax ist zum Beispiel gültig, sofern die angegebenen Widgets deklariert wurden:
myBox.children = [myInTextField, myButton02, myOutTextField];
Obwohl Sie
eine Feldgruppe
children (oder
initialUI) angeben können, sollten
Sie keine Änderungen vornehmen, indem Sie dynamische Feldgruppenfunktionen wie
appendElement
oder den Operator
::= verwenden. Verwenden Sie stattdessen die widgetspezifischen Funktionen
appendChild,
appendChildren,
removeChild
und
removeChildren. Das folgende Beispiel geht davon aus, dass die angegebenen
Widgets deklariert wurden:
Function myFirstFunction(){}
myBox.appendChild(myOtherButton);
myBox.appendChildren([myOtherTextField, myOtherButton02]);
myBox.removeChild(myOtherButton);
myBox.removeChildren();
end
In ähnlicher Weise können Sie untergeordnete Elemente im obersten DOM-Element hinzufügen
oder entfernen, wie im folgenden Beispiel gezeigt:
document.body.appendChild(myOtherButton);
document.body.appendChildren([myOtherTextField, myOtherButton02]);
document.body.removeChild(myOtherButton);
document.body.removeChildren();
Die Funktionen appendChild und
removeChild akzeptieren ein einzelnes Widget. Die Funktion
appendChildren akzeptiert eine Feldgruppe von Widgets und die Funktion
removeChildren akzeptiert keine Argumente. Bei den Funktionen
appendChild und appendChildren können die
Widgetdeklarationen anonym oder benannt sein. Im Fall der Funktion removeChild
müssen die Widgetdeklarationen benannt sein.
Anmerkung: Die
Verwendung der Funktion removeChild oder removeChildren durch die Anwendung
hat keine Auswirkung auf die Speicherzuordnung. Details zu diesem potenziell wichtigen Problem finden Sie im Abschnitt
“Rich-UI-Speicherverwaltung”.
Effekt der Zuordnung eines Widgets zu einem anderen übergeordneten Element
Ein bestimmtes
Widget kann das untergeordnete Element nur eines anderen Widgets (bzw. des Dokumenthauptteils) sein, wie in einem
späteren Beispiel gezeigt wird. Wenn ein Widget ein übergeordnetes Element hat, können Sie veranlassen, dass
das Widget zu einem untergeordneten Element eines anderen übergeordneten Elements wird. Diese Neuzuordnung
wird als Neuzuordnung zu einem übergeordneten Element ('Re-parenting') des untergeordneten Widgets
bezeichnet.
Betrachten Sie die folgende Deklaration des Widgets
myTopBox, das das
übergeordnete Element von zwei weiteren Feldern ist:
myTopBox Box{padding = 8, columns = 1, backgroundColor = "Aqua",
children =[myBox02, myBox03 ]};
Nehmen Sie an, dass sich die obige Deklaration in
einem Rich-UI-Handler befindet, der
myBox03 zum einzigen Element in der Feldgruppe
initialUI macht:
handler MyTest type RUIhandler{initialUI =[myBox03]}
Während der Ausführung wird die
Zuordnung zur Feldgruppe initialUI nach der Deklaration von
myTopBox verarbeitet. Der Effekt ist, dass das Element myBox03 dem Dokumenthauptteil
neu zugeordnet wird, sodass das Element myTopBox mit nur einem untergeordneten Element, nämlich
myBox02, zurückbleibt.
Ihr Code könnte das Element
myTopBox einer
Webseite als Antwort auf ein Laufzeitereignis, wie zum Beispiel einen Schaltflächenklick des Benutzers,
hinzufügen. Sie können den Effekt prüfen, indem Sie den folgenden Beispielcode ausführen und auf die
Schaltfläche klicken:
import com.ibm.egl.rui.widgets.Box;
import com.ibm.egl.rui.widgets.Button;
import com.ibm.egl.rui.widgets.TextField;
import egl.ui.rui.Event;
handler MyTest type RUIhandler{initialUI =[myBox03]}
myTopBox Box{padding = 8, columns = 1, backgroundColor = "Aqua",
children =[myBox02, myBox03 ]};
myBox02 Box{padding = 8, columns = 2, backgroundColor = "DarkGray",
children =[myHelloField ]};
myBox03 Box{padding = 8, columns = 3, backgroundColor = "CadetBlue",
children =[myInTextField, myButton, myOutTextField] };
myHelloField TextField{readOnly = true, text = "Hello"};
myInTextField TextField{};
myButton Button{text = "Input to Output", onClick ::= click};
myOutTextField TextField{};
function click(e EVENT in)
document.body.appendChildren([myTopBox]);
end
end
Effekt des Entfernens aller untergeordneten Elemente aus dem Dokumenthauptteil
Betrachten
Sie die folgende Anweisung:
document.body.removeChildren();
Diese Anweisung hat zwei Effekte:
- Alle untergeordneten Widgets werden von der Webseite entfernt.
- Der Zugriff auf das externe Style-Sheet wird entfernt (sofern vorhanden). Style-Sheets werden im Abschnitt
“Widgetstile” beschrieben.
Wenn Sie untergeordnete Elemente aus dem Dokumenthauptteil entfernen
wollen, ohne den Zugriff auf das externe Style-Sheet zu entfernen, entfernen Sie bestimmte untergeordnete Elemente,
wie in der folgenden Anweisung:
document.body.removeChild(myBox);