Registriert eine Funktion oder Methode, die aufgerufen wird, wenn ein bestimmtes Ereignis durch ein GUI-Fenster oder -Steuerelement ausgelöst wird.
Gui.OnEvent(EreignisName, Rückruf , HinzufügenEntfernen) GuiCtrl.OnEvent(EreignisName, Rückruf , HinzufügenEntfernen)
Typ: Zeichenkette
Der Name des Ereignisses. Siehe Ereignisse weiter unten.
Typ: Zeichenkette oder Funktionsobjekt
Eine Funktion, eine Methode oder ein Objekt, die/das aufgerufen wird, wenn das Ereignis ausgelöst wird.
Wenn die GUI ein Event-Sink hat (d.h. wenn der EreignisObj-Parameter von Gui() angegeben wurde), kann dieser Parameter der Name einer Methode im Event-Sink sein. Andernfalls muss dieser Parameter ein Funktionsobjekt sein.
Informationen zu den Parametern, dem Rückgabewert, der Namensgebung und mehr finden Sie in den folgenden Abschnitten.
Typ: Integer
Wenn weggelassen, wird standardmäßig 1 verwendet. Andernfalls geben Sie eine der folgenden Zahlen an:
Wenn die Rückruffunktion eine via Name registrierte Methode ist, bekommt ihr versteckter this-Parameter direkt das Event-Sink-Objekt zugewiesen (also das Objekt, zu dem die Methode gehört). Dieser Parameter wird in den Parameterlisten dieser Dokumentation nicht angezeigt.
Da Rückruf ein Objekt sein kann, ist es auch möglich, ein BoundFunc-Objekt anzugeben, das zusätzliche Parameter am Anfang der Parameterliste einfügt und dann eine andere Funktion aufruft. Es handelt sich hierbei um eine allgemeine Technik, die nicht spezifisch für OnEvent ist, weshalb sie im Rest dieser Dokumentation grundsätzlich ignoriert wird.
Der erste explizite Parameter der Rückruffunktion ist das Gui- oder GuiControl-Objekt, das das Ereignis ausgelöst hat. Die einzige Ausnahme ist, dass dieser Parameter weggelassen wird, wenn eine Gui ihre eigenen Ereignisse behandelt, da this bereits eine Referenz enthält, die auf die Gui verweist.
Viele Ereignisse akzeptieren zusätzliche Parameter.
Wie bei allen dynamisch aufgerufenen Methoden oder Funktionen können Sie einen oder mehrere Parameter am Ende der Parameterliste der Rückruffunktion weglassen, wenn Sie die entsprechenden Informationen nicht benötigen, aber dann muss als letzter Parameter ein Sternchen angegeben werden, z.B. MeinRückruf(Param1, *). Wenn ein Ereignis mehr Parameter hat als von der Rückruffunktion deklariert, werden diese einfach ignoriert (es sei denn, die Rückruffunktion ist variadisch).
Die Rückruffunktion kann mehr Parameter deklarieren als das Ereignis bereitstellt, wenn (und nur wenn) die zusätzlichen Parameter als optional deklariert sind. Die Verwendung von optionalen Parametern wird jedoch nicht empfohlen, da zukünftige Versionen des Programms ein Ereignis mit zusätzlichen Parametern erweitern können; in diesem Fall würden die optionalen Parameter nicht mehr ihre Standardwerte erhalten.
Wenn mehrere Rückruffunktionen für ein Ereignis registriert sind, kann eine Rückruffunktion einen nicht-leeren Wert zurückgeben, um zu verhindern, dass die restlichen Rückruffunktionen aufgerufen werden.
Der Rückgabewert kann je nach Ereignis eine zusätzliche Bedeutung haben. Zum Beispiel kann eine Close-Rückruffunktion eine Zahl ungleich 0 zurückgeben (z.B. true), um die Schließung des GUI-Fensters zu verhindern.
Konventionsgemäß wird die Syntax jedes Ereignisses unten mit einem Funktionsnamen in Form von ObjektTyp_EreignisName angezeigt. Dies dient der Übersichtlichkeit. Skripte müssen sich nicht an diese Konvention halten und können beliebige gültige Funktionsnamen verwenden.
Jede Ereignis-Rückruffunktion wird in einem neuen Thread aufgerufen und verwendet daher vorerst die Standardwerte von Einstellungen wie SendMode. Diese Standardwerte können während der Startphase des Skripts geändert werden.
Jedes Mal, wenn ein GUI-Thread gestartet wird, ist das zuletzt gefundene Fenster dieses Threads zunächst das GUI-Fenster selbst. Dies ermöglicht Ihnen, FensterTitel und FensterText bei Fenster- und Steuerelementfunktionen wie WinGetStyle, WinSetTransparent und ControlGetFocus wegzulassen, um mit dem GUI-Fenster selbst zu arbeiten (sogar wenn es versteckt ist).
Sofern nicht anders angegeben, ist jedes Ereignis auf jeweils einen Thread pro Objekt beschränkt. Wenn ein Ereignis ausgelöst wird, bevor ein vorheriger Thread, der durch dieses Ereignis gestartet wurde, fertig ist, wird es normalerweise verworfen. Um das zu verhindern, geben Sie Critical in der ersten Zeile der Rückruffunktion an (allerdings werden dadurch auch andere Threads, wie z.B. das Drücken eines Hotkeys, gepuffert/verzögert).
Wenn eine GUI zerstört wird, werden alle Ereignis-Rückruffunktionen freigegeben. Wenn also die GUI beim Senden eines Ereignisses zerstört wird, werden nachfolgende Ereignis-Rückruffunktionen nicht aufgerufen. Aus Gründen der Übersichtlichkeit sollten Rückruffunktionen einen nicht-leeren Wert zurückgeben, nachdem die GUI zerstört wurde.
Die folgenden Ereignisse werden von Gui-Objekten unterstützt:
| Ereignis | Auslösende Aktion |
|---|---|
| Close | Das Fenster wurde geschlossen. |
| ContextMenu | Der Benutzer hat einen Rechtsklick innerhalb des Fensters gemacht oder Menü oder Umschalt+F10 gedrückt. |
| DropFiles | Dateien/Ordner wurden auf das Fenster gezogen und abgelegt. |
| Escape | Der Benutzer hat Esc gedrückt, während das GUI-Fenster aktiv war. |
| Size | Das Fenster wurde kleiner/größer gemacht, minimiert, maximiert oder wiederhergestellt. |
Die folgenden Ereignisse werden von GuiControl-Objekten unterstützt, abhängig vom Typ des Steuerelements:
| Ereignis | Auslösende Aktion |
|---|---|
| Change | Der Wert des Steuerelements hat sich geändert. |
| Click | Das Steuerelement wurde angeklickt. |
| DoubleClick | Das Steuerelement wurde doppelt angeklickt. |
| ColClick | Eine Spaltenüberschrift in der ListView wurde angeklickt. |
| ContextMenu | Der Benutzer hat einen Rechtsklick auf das Steuerelement gemacht oder Menü oder Umschalt+F10 gedrückt, während das Steuerelement fokussiert war. |
| Focus | Das Steuerelement hat den Tastaturfokus erhalten. |
| LoseFocus | Das Steuerelement hat den Tastaturfokus verloren. |
| ItemCheck | Ein Häkchen wurde bei einer ListView-Zeile oder einem TreeView-Element gesetzt oder entfernt. |
| ItemEdit | Die Beschriftung einer Listview-Zeile oder eines TreeView-Elements wird vom Benutzer editiert. |
| ItemExpand | Ein TreeView-Element wurde auf- oder zugeklappt. |
| ItemFocus | Eine andere ListView-Zeile wurde fokussiert. |
| ItemSelect | Eine ListView-Zeile oder ein TreeView-Element wurde ausgewählt oder eine ListView-Zeile wurde abgewählt. |
Wird gestartet, wenn der Benutzer oder ein anderes Programm versucht, das Fenster zu schließen, z.B. durch Drücken der X-Schaltfläche in der Titelleiste, Auswählen des Systemmenüpunkts "Schließen" oder Aufrufen von WinClose.
Gui_Close(GuiObj)
Standardmäßig wird das Fenster automatisch versteckt, wenn die Rückruffunktion endet oder wenn keine Rückruffunktionen registriert wurden. Eine Rückruffunktion kann dies verhindern, indem sie 1 (oder True) zurückgibt, wodurch auch verhindert wird, dass die restlichen Rückruffunktionen aufgerufen werden. Die Rückruffunktion kann das Fenster sofort mit GuiObj.Hide verstecken oder mit GuiObj.Destroy zerstören.
Das folgende Beispiel zeigt eine GUI, die den Benutzer fragt, ob das Fenster geschlossen werden soll:
MeineGui := Gui()
MeineGui.AddText("", "Drücken Sie Alt+F4 oder die X-Schaltfläche in der Titelleiste.")
MeineGui.OnEvent("Close", MeineGui_Close)
MeineGui_Close(thisGui) { ; Dieser Parameter muss nicht deklariert werden.
if MsgBox("Wollen Sie die GUI wirklich schließen?",, "y/n") = "No"
return true ; true = 1
}
MeineGui.Show
Wird gestartet, wenn der Benutzer mit der rechten Maustaste irgendwo im Fenster klickt (außer Titelleiste und Menüleiste). Das Ereignis wird auch gestartet, wenn der Benutzer Menü oder Umschalt+F10 drückt.
Gui_ContextMenu(GuiObj, GuiCtrlObj, Element, IstRechtklick, X, Y)
Typ: Objekt oder Zeichenkette (leer)
Das GuiControl-Objekt des Steuerelements, das das Ereignis empfangen hat (andernfalls leer).
Typ: Integer
Bei einer ListBox, ListView oder TreeView (ermittelbar via GuiCtrlObj) gibt Element an, auf welchem Listeneintrag, welcher Zeile oder welchem Element der Versuch unternommen wurde, das Kontextmenü zu öffnen.
ListBox: Die Positionsnummer des aktuell fokussierten Listeneintrags. Beachten Sie, dass in einer normalen ListBox ein Listeneintrag nicht fokussiert wird, wenn er mit der rechten Maustaste angeklickt wird, so dass diese Nummer nicht unbedingt den angeklickten Listeneintrag repräsentiert.
ListView und TreeView: Bei Rechtsklick wird Element auf die Zeilennummer oder ID des angeklickten Elements gesetzt (oder 0, wenn der Benutzer etwas anderes als ein Element anklickt). Bei Menü oder Umschalt+F10 wird Element auf die Zeilennummer oder ID des ausgewählten Elements gesetzt.
Typ: Integer (boolesch)
Einer der folgenden Werte:
Typ: Integer
Die X- und Y-Koordinate der Position, auf der das Kontextmenü angezeigt werden soll (z.B. MeinKontextmenü.Show X, Y). Die Koordinaten sind relativ zur linken oberen Ecke des Clientbereichs des Fensters.
Im Gegensatz zu den meisten anderen GUI-Ereignissen können mehrere ContextMenu-Threads zur selben Zeit aktiv sein.
Für jedes Steuerelement kann eine eigene ContextMenu-Rückruffunktion registriert werden, die vor allen anderen Rückruffunktionen, die für das Gui-Objekt registriert sind, aufgerufen wird. Steuerelementspezifische Rückruffunktionen haben keinen GuiObj-Parameter, aber alle anderen Parameter sind dieselben.
Hinweis: Da Edit und MonthCal über ein eigenes Kontextmenü verfügen, kann in solchen Steuerelementen kein GuiContextMenu-Ereignis via Rechtsklick gestartet werden.
Wird gestartet, wenn Dateien/Ordner während eines Ziehen-und-Ablegen-Vorgangs auf das Fenster abgelegt werden (wenn diese Rückruffunktion aber bereits läuft, werden Ablege-Ereignisse ignoriert).
Gui_DropFiles(GuiObj, GuiCtrlObj, DateiArray, X, Y)
Typ: Objekt oder Zeichenkette (leer)
Das GuiControl-Objekt des Steuerelements, auf dem die Dateien abgelegt wurden (andernfalls leer).
Typ: Array
Ein Array von Dateinamen, wobei DateiArray[1] die erste Datei ist und DateiArray.Length die Anzahl der Dateien zurückgibt. Mit einer For-Schleife können die Dateien einzeln durchgegangen werden:
Gui_DropFiles(GuiObj, GuiCtrlObj, DateiArray, X, Y) {
for i, AbgelegteDatei in DateiArray
MsgBox "Datei " i " ist:`n" AbgelegteDatei
}Typ: Integer
Die X- und Y-Koordinate der Position, auf der die Dateien abgelegt wurden, relativ zur linken oberen Ecke des Clientbereichs des Fensters.
Wird gestartet, wenn der Benutzer Esc drückt, während das GUI-Fenster aktiv ist.
Gui_Escape(GuiObj)
Standardmäßig hat das Drücken von Esc keinen Effekt. Bekannte Einschränkung: Wenn die Interaktion mit dem ersten Steuerelement im Fenster verboten ist (möglicherweise abhängig vom Typ des Steuerelements), wird das Escape-Ereignis nicht gestartet. Es gibt eventuell noch andere Faktoren, die diesen Effekt hervorrufen.
Wird gestartet, wenn das Fenster kleiner/größer gemacht, minimiert, maximiert oder wiederhergestellt wird.
Gui_Size(GuiObj, MinMax, Breite, Höhe)
Typ: Integer
Einer der folgenden Werte:
Beachten Sie, dass die Größe eines maximierten Fensters auch ohne Wiederherstellung oder Entmaximierung geändert werden kann, so dass ein Wert von 1 nicht unbedingt bedeutet, dass dieses Ereignis als Reaktion auf die Maximierung des Fensters durch den Benutzer ausgelöst wurde.
Typ: Integer
Die neue Breite und Höhe des Clientbereichs des Fensters (das ist der Bereich ohne Titelleiste, Menüleiste und Rahmen).
Ein Skript kann das Size-Ereignis verwenden, um Steuerelemente neu zu positionieren und größer/kleiner zu machen, wenn der Benutzer die Größe des Fensters ändert.
Beim Ändern der Fenstergröße (auch via Skript) kann es vorkommen, dass das Size-Ereignis nicht sofort ausgelöst wird. Wie jedes Fensterereignis wird das Size-Ereignis erst ausgelöst, wenn der aktuelle Thread unterbrechbar wird. Gehen Sie wie folgt vor, um sicherzustellen, dass das Size-Ereignis beim Ändern der Fenstergröße sofort ausgelöst wird:
Critical "Off" ; Selbst wenn Critical "On" nie verwendet wurde. Sleep -1
Gui.Show macht automatisch ein Sleep -1, demzufolge muss in diesem Fall kein Sleep aufgerufen werden.
Wird ausgelöst, wenn sich der Wert des Steuerelements ändert.
Ctrl_Change(GuiCtrlObj, Info)
Typ: Integer
Slider: Ein numerischer Wert, der angibt, wie sich der Schieberegler verschoben hat. Weitere Informationen finden Sie unter Erkennen von Änderungen.
Bei allen anderen Steuerelementen hat Info zur Zeit keine Bedeutung.
Mit GuiCtrlObj.Value kann der neue Wert des Steuerelements abgerufen werden.
Betrifft: DDL, ComboBox, ListBox, Edit, DateTime, MonthCal, Hotkey, UpDown, Slider, Tab.
Wird ausgelöst, wenn das Steuerelement angeklickt wird.
Ctrl_Click(GuiCtrlObj, Info) Link_Click(GuiCtrlObj, Info, Href)
Typ: Integer
ListView: Die Zeilennummer der angeklickten Zeile, oder 0, wenn sich der Mauszeiger nicht über einer Zeile befindet.
TreeView: Die ID des angeklickten Elements, oder 0, wenn sich der Mauszeiger nicht über einem Element befindet.
Link: Das ID-Attribut des Links (eine Zeichenkette), falls vorhanden, andernfalls der Index des Links (ein Integer).
StatusBar: Die Nummer des angeklickten Segments (allerdings kann die Nummer ein sehr großer Integer sein, wenn der Benutzer in der Nähe des Größenziehpunkts auf der rechten Seite der Leiste klickt).
Bei allen anderen Steuerelementen hat Info zur Zeit keine Bedeutung.
Typ: Zeichenkette
Link: Das HREF-Attribut des Links. Beachten Sie, dass das HREF-Attribut nicht automatisch ausgeführt wird, wenn eine Click-Ereignis-Rückruffunktion registriert ist.
Betrifft: Text, Pic, Button, CheckBox, Radio, ListView, TreeView, Link, StatusBar.
Wird ausgelöst, wenn das Steuerelement doppelt angeklickt wird.
Ctrl_DoubleClick(GuiCtrlObj, Info)
Typ: Integer
ListView, TreeView und StatusBar: Dasselbe wie beim Click-Ereignis.
ListBox: Die Positionsnummer des aktuell fokussierten Listeneintrags. Ein Doppelklick auf den leeren Bereich unter dem letzten Listeneintrag führt normalerweise dazu, dass der letzte Listeneintrag fokussiert wird und die aktuelle Auswahl unverändert bleibt.
Betrifft: Text, Pic, Button, CheckBox, Radio, ComboBox, ListBox, ListView, TreeView, StatusBar.
Wird ausgelöst, wenn eine Spaltenüberschrift in der ListView angeklickt wird.
Ctrl_ColClick(GuiCtrlObj, Info)
Typ: Integer
Die 1-basierte Spaltennummer, die angeklickt wurde. Dies ist die Nummer, die der Spalte ursprünglich bei ihrer Erstellung zugewiesen wurde, d.h. die Nummer spiegelt nicht das Ziehen und Ablegen von Spalten durch den Benutzer wider.
Betrifft: ListView.
Wird ausgelöst, wenn der Benutzer einen Rechtsklick auf das Steuerelement gemacht oder Menü oder Umschalt+F10 gedrückt hat, während das Steuerelement fokussiert war.
Ctrl_ContextMenu(GuiCtrlObj, Element, IstRechtklick, X, Y)
Weitere Informationen finden Sie unter ContextMenu.
Betrifft: Alle Steuerelemente außer Edit und MonthCal (und das Eingabefeld einer ComboBox) - diese verfügen über ein eigenes Kontextmenü.
Wird ausgelöst, wenn das Steuerelement den Tastaturfokus erhält oder verliert.
Ctrl_Focus(GuiCtrlObj, Info) Ctrl_LoseFocus(GuiCtrlObj, Info)
Reserviert.
Betrifft: Button, CheckBox, Radio, DDL, ComboBox, ListBox, ListView, TreeView, Edit, DateTime.
Nicht unterstützt: Hotkey, Slider, Tab und Link. Beachten Sie, dass Text-, Pic-, MonthCal-, UpDown- und StatusBar-Steuerelemente keinen Tastaturfokus akzeptieren.
Wird ausgelöst, wenn ein Häkchen bei einer ListView-Zeile oder einem TreeView-Element gesetzt oder entfernt wird.
Ctrl_ItemCheck(GuiCtrlObj, Element, HäkchenGesetzt)
Wird ausgelöst, wenn die Beschriftung einer Listview-Zeile oder eines TreeView-Elements vom Benutzer editiert wird.
Ctrl_ItemEdit(GuiCtrlObj, Element)
Die Beschriftung kann nur editiert werden, wenn -ReadOnly in den Optionen des Steuerelements angegeben wurde.
Wird ausgelöst, wenn ein TreeView-Element auf- oder zugeklappt wird.
Ctrl_ItemExpand(GuiCtrlObj, Element, Aufgeklappt)
Betrifft: TreeView.
Wird ausgelöst, wenn eine andere ListView-Zeile fokussiert wird.
Ctrl_ItemFocus(GuiCtrlObj, Element)
Betrifft: ListView.
Wird ausgelöst, wenn eine ListView-Zeile oder ein TreeView-Element ausgewählt oder eine ListView-Zeile abgewählt wird.
ListView_ItemSelect(GuiCtrlObj, Element, Ausgewählt) TreeView_ItemSelect(GuiCtrlObj, Element)
ListView: Dieses Ereignis wird ausgelöst, wenn eine Zeile ab- oder ausgewählt wird, folglich kann das Ereignis mehrmals durch eine einzige Benutzeraktion ausgelöst werden.
Andere Arten von GUI-Ereignissen können via OnNotify, OnCommand oder OnMessage erkannt und verarbeitet werden. Zum Beispiel kann ein Skript jedes Mal eine kontextabhängige Hilfe via Tooltip anzeigen, wenn der Benutzer den Mauszeiger über bestimmte Steuerelemente im Fenster bewegt. Siehe dazu das GUI-Tooltip-Beispiel.