GuiBuilder API und Scripting Tutorial

Hier wird zum Einstieg ein Überblick über die wichtigsten Methoden des GuiBuilder-Frameworks gegeben. Ein intensiverer Umgang setzt das Studium von JavaDoc voraus, sowie ein Verständnis des Objekt-Modells.

Einige Beispiel-Scripts finden sich unter guibuilder/lib/example/Pnuts und example/BeanShell.

Umgang mit der GuiFactory

Ein Hauptfenster (Formular, Dialog) wird mit Hilfe der GuiFactory erzeugt.

Dieses kann auf Grundlage eines Datenamens oder eines Strings erfolgen.

Bei Angabe eines Dateinamens wird die zuvor gesetzte DocumentBase berücksichtigt (siehe GuiUtil.setDocumentBase).
Beachten Sie, daß Pnuts für den Zugriff auf statische Methoden einen "::" verlangt: GuiFactory::getInstance()

myWin = GuiFactory.getInstance().createWindow("MyScript.xml");

myWin = GuiFactory.getInstance().createWindowXml( "<?xml version='1.0' encoding='ISO-8859-1'?> <!DOCTYPE GDL SYSTEM 'gdl.dtd'> <GDL> <Dialog label='MyDialogTitle'> <Text label='Eingabe:' /> <Button label='OK' x='1'/> </Dialog> </GDL>");

Fenster-Manipulationen

Wichtige Methoden:

show(): Zeigt ein Fenster an.
boolean showDialog(): Nur für modale Dialoge, die hier wie eine Funktion eingesetzt werden.
Liefert "true", wenn der Benutzer den OK-Button des Dialoges betätigt hat, ansonsten "false".
hide(): Versteckt das Fenster; es kann anschließend mit show() wieder angezeigt werden.
dispose(): Vernichtet das Fenster. Achtung! Anschließend die Objekt-Referenz auf das Fenster auf null setzen.
setTitle(String title): Setzt die Beschriftung in der Titelzeile des Fensters.
reset(): Leert alle Eingabefelder des Fensters. Bei allen Members wir die Eigenschaft "modified" auf "false" gesetzt.
verify(): Überprüft alle Eingabefelder auf gültige Eingaben (notNull, minLen, maxLen, usw.).
Es wird eine IllegalStateException geworfen, wenn ungültige Eingaben vorliegen.
Document getAllValuesXml(): Liefert die Eingaben als ein Xml-Document.
setAllValuesXml(Document doc): Setzt alle Felder auf den Inhalt des übergebenen Documents.
Achtung!
Es wird eine IllegalArgumentException geworfen, wenn in dem Document Feldnamen enthalten sind, die im Fenster nicht definiert sind.
Object getValue(String memberName): Liefert den Inhalt des angegebenen Feldes.
setValue(String memberName, Object value): Füllt des angegebene Feld mit dem angegebenen Inhalt.
GuiRootPane getRootPane(): Jedem Fenster ist eine RootPane zugeordnet; hier sind weitere Methoden verfügbar.
GuiPanel getRootPane().getMainPanel(): Der RootPane ist immer genau ein Haupt-Panel zugeordent; hier sind weitere Methoden verfügbar.

Umgang mit modalen Dialogen.

Modale Dialoge können wie eine Funktion eingesetzt werden:

Script "MyDialog.xml"

<Dialog label="MyDialog" typ="MODAL"> <Text label="Text:" />  <Button label="OK" file="Close()" />  <Button label="Cancel" file="Cancel()" /> </Dialog>

Verwendung dieses Dialoges mit Java:

// Dialog von der Factory erzeugen lassen.GuiDialog myDialog = (GuiDialog)GuiFactory.getInstance().createWindow("MyDialog.xml"); // Dialog mit Werten füllen. myDialog.setValue("text", "Hier steht ein Text"); // Dialog anzeigen, und auf Schließen des Dialoges durch den Benutzer warten. // Die Control-Box des Dialoges liefert gleichfalls "false". if (myDialog.showDialog()) { // Benutzereingaben auslesen. String eingabe = myDialog.getValue("text"); } // Aufräumen, wenn der Dialog nicht mehr benötigt wird. myDialog.dispose(); myDialog = null;

Mit BeanShell wirds etwa einfacher:

... <Button label="Drück mich" cmd="actionPerformed" /> ...

<Script language="BeanShell"> import de.guibuilder.framework.*; import de.guibuilder.framework.event.*; actionPerformed(event) { myDialog = GuiFactory.getInstance().createWindow("MyDialog.xml"); myDialog.setValue("text", "Hier steht ein Text"); if (myDialog.showDialog()) { eingabe = myDialog.getValue("text"); } myDialog.dispose(); myDialog = null; } </Script>

GuiRootPane

(Fast) alle Komponenten verfügen über eine Methode getRootPane(); auf dieses Objekt kann also jederzeit zugegriffen werden.

GuiPanel getMainPanel(): Liefert das Wurzel-Panel für alle weiteren Komponenten.
GuiMenuBar getGuiMenuBar(): Für Zugriff auf Menubar.
GuiToolbar getToolBar(): Für Zugriff auf Toolbar.
GuiWindow getParentWindow(): Das Formular, Dialog usw. zu diesem RootPane.
getCurrentTable() / getCurrentTree() / getSplit(): Vorsicht:
Der Returnwert kann auch dann null sein, selbst wenn eine oder mehrere Komponenten in der Oberfläche vorhanden sind, der Benutzer aber z.B. noch keine Tabelle angeklickt hat.
activateTab(String tabname) / enableTab(String tabname, boolean b) / enableAllTabs(boolean b): Diese Methoden setzen voraus, daß die Namen der Registerkarten eindeutig sind.

Methoden auf Container-Ebene

Container sind vor allem Registerkarten, und (wenn besonders gekennzeichnet) auch Panels und beschriftete Rahmen. Das HauptPanel eines Fensters ist immer über myWindow.getRootPane().getMainPanel() erreichbar.

GuiMember getMember(String memberName): Liefert das Objekt mit dem angegebenen Namen. Dieses ist naturgemäß eine von GuiMember abgeleitete Klasse; also ein weiterer Container oder eine von GuiComponent abgeleitete Klasse.
Mit myMember.getGuiType() kann ermittelt werden, um was es sich eigentlich handelt.
GuiAction getAction(String actionName): Liefert den Menüeintrag oder den Button mit dem angegebenen Namen.
Achtung! Alle Menüeinträge der MenuBar sind immer dem MainPanel zugeordnet.
ArrayList getMemberNames(): Liefert eine ArrayList von Strings mit allen Member-Namen in der Reihenfolge ihrer Spezifikation.
reset(): Leert alle Eingabefelder des Fensters und setzt bei allen enthaltenen Child-Komponenten modified auf "false".
verify(): Überprüft alle Eingabefelder auf gültige Eingaben (notNull, minLen, maxLen, usw.).
Es wird eine IllegalStateException geworfen, wenn ungültige Eingaben vorliegen.
Document getAllValuesXml(): Liefert die Eingaben als ein Xml-Document.
setAllValuesXml(Document doc): Setzt alle Felder auf den Inhalt des übergebenen Documents.
Achtung!
Es wird eine IllegalArgumentException geworfen, wenn in dem Document Feldnamen enthalten sind, die im Fenster nicht definiert sind.
Object getValue(String memberName): Liefert den Inhalt des angegebenen Feldes.
setValue(String memberName, Object value): Füllt des angegebene Feld mit dem angegebenen Inhalt.

Methoden auf Member-Ebene

GuiMember ist eine abstrakte Klasse, die zusammen mit GuiContainer und GuiElement ein Kompositum Pattern bilden: Ein Container enthält Member, die wiederum Container oder Elemente sind.

Auch GuiElement und GuiContainer sind abstrakt; von ihnen sind weitere - auch abstrakte - Klassen abgeleitet.

GuiAction erweitert GuiElement, und wird seinerseit von GuiButton und GuiMenuItem erweitert. Hier handelt es sich also um Klassen, mit deren Hilfe der Benutzer eine Aktion auslösen kann.
Achtung!
GuiMenuItemOption und GuiMenuItemCheck lösen keine derartige Benutzeraktionen aus, sondern sind in ihrem Verhalten einem RadioButton bzw. einer CheckBox vergleichbar!

GuiComponent erweitert GuiElement und repräsentiert die abstrakte Basis-Klasse für alle Oberflächenkomponenten, die einen Inhalt haben können, den der Benutzer (zumeist) durch Eingaben manipulieren kann; also TextFelder, ComboBoxen, RadioButtons usw.

GuiTable und GuiTree haben naturgemäß spezielle Eigenschaften.

Siehe auch die entsprechenden Klassendiagramme.

GuiMember

String getName(): Liefert den - innerhalb eines Containers - eindeutigen Namen.
int getGuiType(): Liefert den Typ der Komponente.
JComponent getJComponent(): Die eigentlichen Swing-Komponenten werden vom GuiBuilder per Delegation angesprochen. Für den Ausnahmefall, daß das Swing-Objekt direkt manipuliert werden soll, kann man sich hierüber eine ObjektReferenz verschaffen.
long getOid() / setOid(long oid): Dieses Attribut wird vom GuiBuilder selbst niemals benutzt; der Anwender hat hier die Möglichkeit, seine eigene Object-ID (oder was auch immer) abzulegen, und später wieder darauf zuzugreifen.
getOid() liefert -1, wenn keine oid gesetzt wurde.
Object getUserObject() / setUserObject (Object o): Auch dieses Attribut wird vom GuiBuilder selbst niemals verwendet; der Anwender kann für seine Zwecke eine beliebige Objekt-Referenz eintragen.
Object getControler() / setControler(Object c): Der Controler ist dasjenige Objekt, an welches Benutzerereignisse weitergereicht werden können.
getControler() liefert u.U. den Controler des Parents, wenn bei der Komponente selbst kein Controler eingetragen wurde.
Beim Einsatz von Scripting hat dieses Vorrang.
Nachmal langsam zum mitdenken:
Wenn Sie eine Ereignis-Methode OnChange="machWas" definiert haben, und Sie im Script eine Funktion
machWas(event)geschrieben haben, wird diese aufgerufen; gibt es diese Methode in Ihrem Script nicht (oder gibts es in diesem Dialog gar kein Script), wird nach einem Controler gesucht, der über eine Methode machWas(GuiUserEvent event) verfügt.
Sie können damit Pnuts- oder BeanShell-Scripts ähnlich wie JavaScript einsetzen, also die einfachen Dinge per Scripting erledigen und die wesentlichen an den Server weiterreichen.

GuiElement

setEnabled(boolean b) / boolean isEnabled(): Ein Element kann aktiviert oder deaktiviert, d.h. für Benutzeraktionen gesperrt werden.
GuiTable getParentTable(): Wenn das Element Spalte in einer Tabelle ist, kann hierauf auf diese zugegriffen werden.

GuiComponent

Object getValue() / setValue(Object o): Liefert oder setzt den Inhalt der Komponente. Je nach Komponente sind dieses naturgemäß verschiedene Klassen.
int getDataType(): Liefert den Datentyp, den dieses Element speichern kann.
isModified() / setModified(): Die Eigenschaft "modified" wird durch Benutzereingaben vom GuiBuilder auf "true" gesetzt.
Ein reset() beim Container setzt diese Eigengschaft wieder auf "false".

GuiTable

Eine Tabelle hält eine Menge von Spalten, die das Interface TableColumnAble implementieren. Außerdem eine Menge von Zeilen vom Typ GuiTableRow.

Document getAllValuesXml() / setAllValuesXml(Element e): Der Inhalt einer Tabelle kann mit XML-Dokumenten gefüllt oder ausgelesen werden.
insertRow() / insertRow(int index) / insertRow(GuiTableRow row) / insertRow(GuiTableRow, int index): Es wird eine Zeile eingefügt und die eingefügte Zeile erhält die Eingenschaft inserted = true.
Ist keine Index angegeben, wird die Zeile am Ende der Tabelle angefügt.
Wird kein Objekt GuiTableRow angegeben, wird eine Leerzeile eingefügt.
deleteRow() / deletRow(int index): Es wird eine Zeile aus der Tabelle gelöscht.
Ist kein Index angegeben, wird die selektierte Zeile gelöscht.
Vector getDeletedRows(): Liefert einen Vector von GuiTableRows, die mit deleteRow() gelöscht, aber ohne die, die neu inserted wurden.
reset(): Leert die Tabelle.
int getSelectedRow(): Liefert die selektierte Zeile oder -1, wenn keine Zeile selektiert.
GuiTableRow getRow(int index): Liefert die Zeile mit dem angegebenen Index.

GuiTableRow

boolean isInserted(): Liefert true, wenn die Zeile frisch inserted wurde.
boolean isEditable() / setEditable(boolean b): Einzelne Zeilen können auf nicht editierbar gesetzt werden.
boolean isModified() / setModified(boolean b): Bei Benutzereingaben setzt der GuiBuilder die Eigenschaft modified automatisch auf "true".
Vector getData() / setData(Vector v): Liefert den Inhalt der Spalten als Vector bzw. setzt ihn.
Object getValueAt() / setValueAt(Object o): Der Inhalt einer Zelle kann ausgelesen oder gesetzt werden.
long getOid() / setOid(long oid): Der Zeile kann vom Anwender eine beliebige ObjectId für seine eigenen Zwecke zugewiesen werden.

GuiTree

Die Tree-Komponente hält eine in sich gegliederten Menge von GuiTreeNodes.

Document getAllValuesXml() / setAllValuesXml(Element e): Der komplette Baum wird auf XML angebildet.
GuiTreeNode getSelectedNode() / setSelectedNode(String path): Der vom Benutzer selektierte Node kann ausgelesen oder gesetzt werden.
addGuiNode(GuiTreeNode node) / addGuiNode(String title) / addGuiNode(String title, String name): Es wird eine neuer Node unterhalb des selected Nodes eingehängt.
cutNode(): Löschen den selektierten Node.
Der gelöschte Node kann später mit pasteNode() wieder eingefügt werden.
copyNode(): Der selektierte Node wird kopiert und kann später mit pasteNode() eingefügt werden.
pasteNode(): Fügt den kopierten oder gelöschten Node unterhabl des selektierten Nodes ein.
Kopierte Nodes werden ge-clone-d.

GuiTreeNode

Die Besonderheit dieser Komponente besteht darin, daß hier ein "Navigator-Pattern" implementiert ist:
Ein Node kann einen Verweis auf ein Panel halten, daß im rechten Fenster eines Split-Panels angezeigt wird.

Hierbei ist zu beachten, daß viele Nodes durchaus auf das selbe Panel verweisen können, aber unterschiedliche Inhalte repräsentieren. Der GuiBuilder erzeugt das Swing-Panel dann nur ein einziges mal. Die dem Panel entsprechenden Daten werden jedoch vom Node in einem Xml-Dokument vorgehalten, und wenn der Benutzer zwischen den verschiedenen Nodes wechselt jeweils zugewiesen.

GuiTreeNode(String title) / GuiTreeNode(String title, String name): Erzeugt einen neuen Node.
String getFileName() / setFileName(String filename): Einem TreeNode kann der Dateiname eines GuiBuilder-Scripts zugewiesen werden.
Diese Spezifikation muß vom Typ GuiPanel sein.
Hierbei ist es erlaubt, daß beliebig viele Nodes auf die selbe Spezifikation verweisen; z.B. um eine Menge von Adressen darzustellen.
GuiPanel getPanel(): Liefert das dem TreeNode zugeordenete Panel, wenn es mit setFileName() eines definiert wurde.
Sollte das Panel noch nicht existieren, wird es jetzt von der Factory erzeugt.
Document getAllValuesXml() / setAllValuesXml(Element e): Der Inhalt des XML-Dokuments entspricht dem des zugeordenten Panels.
setIconName(String name): Jedem Node kann ein individueller Icon zugewiesen werden; es ist die nur der Datename (relativ zur Codebase) anzugeben.
setName() / getName(): Schwesterknoten müssen eindeutige Namen haben.
GuiTreeNode getChildByName(String name): Liefert einen Tochter-Knoten über seinen Namen.
long getOid() / setOid(long oid): Dem Node kann vom Anwender eine beliebige ObjectId für seine eigenen Zwecke zugewiesen werden.
getValue(String xpath) / setValue(String xpath, String value): Der Inhalt des vom TreeNode gehaltenen XML-Documents kann über diese Methoden gelesen / geändert werden ohne daß der Node sichtbar ist; XPath-Angabe in Punkt-Notation: getValue("myTab.myTextBox");

GuiUtil

Diese Klasse umfaßt nur statische Methoden.

String[] fileOpenDialog() / fileSaveDialog(): Es wird der Plattform-spezifischer Datei-Öffnen oder Datei-Speichern-Dailog aufgerufen, und die Wahl des Benutzers in einem Array von drei String zurückgegeben: Voller Dateiname, Directory, Dateiname.
URL getDocumentBase() / setDocumentBase(URL): Liefert oder setzt die URL unter der die Gui-Scripte von der Factory gelesen werden; ist vom Typ file oder http.
awt.Image makeAwtImage(String filename): Erzeugt ein Image unter Angabe eines Dateinamens unter Berücksichtigung von DocumentBase.
swing.ImageIcon makeIcon(String filename): Erzeugt ein ImageIcon unter Angabe eines Dateinamens.
boolean okCancelMessage(): Zeigt eine OK/Abbrechen MessageBox und liefert "true", wenn OK.
showMessage(): Zeigt eine einfache Messagebox mit Button OK.
boolean yesNoMessage(): Zeigt eine Ja/Nein-Messagebox und liefert "true" bei "JA".

home