GuiControl

Verändert verschiedene Eigenschaften eines AutoHotkey GUI-Controls.

GuiControl, Sub-command, ControlID [, Param3]

Parameter

ErrorLevel

ErrorLevel wird auf 1 gesetzt, wenn das angegebene Fenster/Control nicht existiert oder andere Probleme die Ausführung der Anweisung verhindern, anderenfalls auf 0.

Sub-commands

(Leer): Sub-command wird leer gelassen, um dem Control einen neuen Inhalt über Param3 zu übergeben. Speziell:

Picture: In Param3 wird der Dateiname des neuen Bildes übergeben (siehe Gui Picture wegen der unterstützten Dateitypen). Folgende Optionen können direkt vor dem Dateinamen angegeben werden: *wN (Breite N), *hN (Höhe N) und *IconN (Nummer N der Icongruppe in einer DLL- oder EXE-Datei). Im folgenden Beispiel wird das Standardicon der zweiten Icongruppe geladen und mit einer Breite von 100 Pixeln und einer dem Seitenverhältnis des Originalicons entsprechenden Höhe angezeigt: GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My Application.exe. Bei Angabe von *w0 *h0 werden die Originalbreite und -höhe des Bildes verwendet. Wenn *w und *h weggelassen werden, wird das Bild auf der aktuellen Größe des Controls angepasst. Beim Laden aus einer ICO-Datei mit mehreren Icons wird durch die Angabe von Breite und Höhe auch bestimmt, welches Icon geladen wird. Hinweis: Zwischen der letzten Option und dem Dateinamen darf nur genau ein Leerzeichen/Tabulator stehen. Weitere Tabulatoren oder Leerzeichen werden als Bestandteil des Dateinamens behandelt.

Text/Button/GroupBox/StatusBar: In Param3 wird der neue Text des Controls übergeben. Weil diese Controls ihre Breite nicht automatisch anpassen, muss GuiControl, Move, MyText, W300 verwendet werden, wenn das Control verbreitert werden muss. Bei einer StatusBar wird nur der Text des ersten Teils ersetzt, SB_SetText() bietet hier mehr Möglichkeiten.

Edit: Alle Zeilenvorschübe (LF: `n) in Param3 ohne führenden Wagenrücklauf (CR: `r) werden automatisch in CR+LF (`r`n) übersetzt, damit sie korrekt angezeigt werden. Das hat aber normalerweise keine Folgen, weil die "Gui Submit" und "GuiControlGet OutputVar" Anweisungen diese Übersetzung bei der Ausgabe rückgängig machen und CR+LF durch LF (`n) ersetzen.

Hotkey: Param3 kann leer sein, um den Hotkey zu löschen, oder aus Modifizierungstasten und einem Tastennamen bestehen. Beispiele: ^!c, ^Numpad1, +Home. Nur folgende Modifizierungstasten werden unterstützt: ^ (Control), ! (Alt) und + (Shift). Die verfügbaren Tastennamen sind in der Tastenliste aufgeführt.

Checkbox: Param3 kann 0 sein, um die Checkbox auszuschalten, 1, um sie anzuschalten, oder -1, um sie auszugrauen. Andernfalls wird Param3 als neuer Erläuterungstext der Checkbox angesehen. Unten wird in Text beschrieben, wie dieses Verhalten geändert werden kann.

Radio: Wie oben bei Checkbox beschrieben. Wenn aber ein Radiobutton angeschaltet wird, der zu einer Gruppe mit mehreren Radiobuttons gehört, werden alle anderen Radiobuttons der Gruppe automatisch ausgeschaltet. Um einen Button einer Gruppe mit nur einer zugewiesenen Variablen anzuschalten, muss in ControlID der Name/Text des Buttons angegeben werden, wenn es nicht der Button ist, dem die Variable zugewiesen wurde.

DateTime/MonthCal: In Param3 wird ein Zeitstempel im Format YYYYMMDDHH24MISS angegegeben. Für das aktuelle Datum und die aktuelle Zeit kann %A_Now% angegeben werden. Für DateTime-Controls kann Param3 weggelassen werden, damit das Control keine Datum/Zeitauswahl enthält (wenn es mit dieser Fähigkeit erstellt wurde). Für MonthCal-Controls kann ein Bereich angegeben werden, wenn das Control eine Mehrfachauswahl zulässt.

UpDown/Slider/Progress: In Param3 wird der neue Positionswert des Controls übergeben. Wenn das erste Zeichen in Param3 das Pluszeichen ist, wird die nachfolgende Zahl als Distanz zum aktuellen Wert behandelt. +10 z.B. würde den Positionswert um 10 erhöhen und +-10 (plus minus zehn) um 10 vermindern. Wenn der neue Positionswert außerhalb des dem Control zugewiesenen Wertbereichs liegt, wird der Wert im allgemeinen auf den nächstliegenden gültigen Wert gesetzt.

Tab/DropDownList/ComboBox/ListBox: In Param3 wird eine mit dem Pipe-Zeichen (|) getrennte Liste von Einträgen übergeben, die am Ende des aktuellen Inhalts des Controls angefügt wird. Um stattdessen den Inhalt zu ersetzen (überschreiben), muss als erstes Zeichen ein Pipe-Zeichen eingefügt werden (z.B.: |Rot|Grün|Blau). Um das Control zu leeren, wird nur ein einzelnes Pipe-Zeichen angegeben. Wenn einer der Einträge als Vorauswahl verwendet werden soll, müssen dahinter zwei Pipe-Zeichen eingefügt werden (z.B.: Rot|Grün||Blau). Das Trennzeichen der Einträge kann auch auf ein anderes als das Pipe-Zeichen geändert werden. Gui +Delimiter`n z.B. würde es auf den Zeilenvorschub und Gui +DelimiterTab auf den Tabulator (`t) ändern.

Tab Controls: Zusätzlich zu dem im vorigen Absatz beschriebenen Verhalten werden die Controls der einzelnen Register eines Tab-Controls immer mit der ursprünglichen Registernummer verbunden, d.h. sie sind niemals mit dem angezeigten Namen des Registers verbunden. Aus diesem Grund wird durch das Umbenennen oder Entfernen eines Registers die Registernummer, der die Controls zugeordnet sind, nicht verändert. Wenn z.B. drei Register "Rot|Grün|Blau" erstellt wurden und das zweite per GuiControl,, MyTab, |Rot|Blau entfernt wird, sind die ursprünglich mit "Grün" (Register 2) verbundenen Controls jetzt mit "Blau" (neues Register 2) verbunden. Wegen dieses Verhaltens sollten generell nur Register am Ende des Tabcontrols entfernt werden. Diese Register können später wieder hinzugefügt werden und enthalten dann auch wieder ihre ursprünglichen Controls.

ListView und TreeView: Diese Controls werden nicht unterstützt, wenn Sub-command leer ist. Stattdessen verwendet man die eingebauten ListView-Funktionen und TreeView-Funktionen.

GuiControl, Text: Verhält sich wie oben beschrieben, ausgenommen für:
Checkbox/Radio: Param3 wird als neuer Erläuterungstext behandelt, selbst wenn er -1, 0 oder 1 ist.
DateTime: Param3 wird als neues Datum/Zeitformat für die Anzeige behandelt. Wenn Param3 weggelassen wird, wird die Anzeige auf das Format "Kurzdatum" zurückgesetzt.
ComboBox: Param3 wird als Text behandelt und direkt in das Eingabefeld (Edit-Control) der ComboBox geschrieben.

GuiControl, Move: Verschiebt und/oder ändert die Größe des Controls. In Param3 muss zumindest eine der folgenden Optionen angegeben werden: X (die X-Koordinate ), Y (die Y-Koordinate), W (Breite), H (Höhe). Beispiel:

GuiControl, Move, MyEdit, x10 y20 w200 h100
GuiControl, Move, MyEdit, % "x" VarX+10 "y" VarY+5 "w" VarW*2 "h" VarH*1.5 ; Benutzt einen Ausdruck über das "% " Präfix.

GuiControl, MoveDraw[v1.0.41.02+]: Verhält sich wie "Move" (s.o.), zeichnet aber die vom Control beanspruchte Fläche im GUI Fenster neu. Obwohl das ein unerwünschtes Flackern erzeugen kann, wenn es wiederholt und in schneller Folge aufgerufen wird, löst es die Anzeigeprobleme bei bestimmten Controls wie z.B. GroupBox. In den Versionen vor 1.0.41.02 hat sich  "Move" wie "MoveDraw" verhalten.

GuiControl, Focus: Setzt den Eingabefokus auf das Control. Das gelingt generell nur, wenn das Fenster nicht minimiert oder verborgen ist.

GuiControl, Disable / Enable: Deaktiviert (graut aus) oder aktiviert ein Control. Bei Tab-Controls werden auch alle zugehörigen Controls de- bzw. aktiviert. Wenn aber ein solches Control einzeln explizit mit GuiControl Disable deaktiviert wurde, bleibt es auch dann deaktiviert, wenn sein Tab-Control reaktiviert wird. Den Wörtern Disable oder Enable darf optional unmittelbar eine 0 oder 1 angehängt werden. Eine 0 invertiert den Effekt. Beispiel: Enable und Enable%Var_enhält_1% aktivieren beide das Control, aber Enable%Var_enthält_0% deaktiviert es.

GuiControl, Hide / Show: Verbirgt oder zeigt das Control. Bei Tab-Controls werden auch alle zugehörigen Controls verborgen bzw. angezeigt. Wenn auch die Funktion einer Shortcut-Taste (unterstrichener Buchstabe) verhindert werden soll, muss das Control mit GuiControl Disable deaktiviert werden. Den Wörtern Hide oder Show darf optional unmittelbar eine 0 oder 1 angehängt werden. Eine 0 invertiert den Effekt. Beispiel: Show und Show%Var_enthält_1% zeigen beide das Control an, aber Show%Var_enthält_0% verbirgt es.

GuiControl, Delete (noch nicht implementiert): Dieses sub-command gibt es noch nicht. Als Hilfslösung können Hide und/oder Disable (s.o.) verwendet oder die komplette GUI mit Gui Destroy zerstört und dann neu erstellt werden.

GuiControl, Choose, ControlID, N: Setzt die Auswahl einer ListBox, DropDownList, ComboBox oder eines Tab-Controls auf das N-te Element. N ist 1 für das erste Element, 2 für das zweite, etc. Wenn N keine Ganzzahl ist, wird automatisch die unten beschriebene ChooseString Methode verwendet. Anders als Control Choose wird durch dieses sub-command nicht das G-Label eines Controls aufgerufen, wenn N nicht ein Pipe-Zeichen (|) vorangestellt wird (selbst dann wird das G-Label nur aufgerufen, wenn sich die neue Auswahl von der bisherigen unterscheidet, zumindest bei Tab-Controls). Beispiel: GuiControl, Choose, MyListBox, |3.

Um zusätzlich noch ein abschließendes Ereignis zu erzeugen (z.B. ein Doppelklick im Falle einer ListBox), müssen zwei Pipe-Zeichen vorangestellt werden (das wird von Tab-Controls nicht unterstützt).

Um alle Elemente einer ListBox mit Mehrfachauswahl aus- oder abzuwählen, folge diesem Beispiel:

Gui +LastFound ; Vermeidet die Notwendigkeit, unten einen Fenstertitel anzugeben.
PostMessage, 0x185, 1, -1, ListBox1 ; Wählt alle Elemente aus. 0x185 ist LB_SETSEL.
PostMessage, 0x185, 0, -1, ListBox1 ; Hebt die Auswahl für alle Elemente auf.

GuiControl, ChooseString, ControlID, String: Setzt die Auswahl in einer ListBox, DropDownList, ComboBox oder einem Tab-Control auf das Element, das mit String beginnt. Die Groß/Kleinschreibung wird nicht beachtet. Wenn ein Control z.B. das Element "UNIX Text" enthält, reicht die Angabe von "unix" (klein geschrieben) für dessen Auswahl. Das einfache und das doppelte Pipe-Zeichen (|) werden auch unterstützt (s.o. "Choose" für Einzelheiten).

GuiControl, Font: Ändert Schriftart, Größe, Farbe und Stil des Zeichensatzes eines Controls auf die aktuellen Einstellungen des Fensters. Beispiel:

Gui, Font, s18 cRed Bold, Verdana ; So wird ein neuer Standardzeichensatz für das gesamte Fenster eingestellt.
GuiControl, Font, MyEdit ; So werden diese Einstellungen dem Control zugewiesen.

GuiControl, +/-Option1 +/-Option2 ... : Verschiedene Optionen und Gestaltungseigenschaften hinzufügen oder entfernen. Alle GUI-Optionen (controlspezifische und generelle) werden erkannt. Im folgenden Beispiel wird die AltSubmit Option aktiviert aber das G-Label des Controls entfernt: GuiControl, +AltSubmit -g, MyListBox

Im nächsten Beispiel wird der Button OK zum neuen Standardbutton:
GuiControl, +Default, OK

Obwohl Gestaltungseigenschaften und erweiterte Gestaltungseigenschaften ebenfalls erkannt werden, können manche nicht bearbeitet oder entfernt werden, nachdem das Control erstellt worden ist. 

ErrorLevel wird auf 0 gesetzt, wenn zumindest eine der angegebenen Änderungen erfolgreich angewandt werden konnte, sonst auf 1, um anzuzeigen, dass alle Änderungen erfolglos waren. Selbst wenn eine Änderung erfolgreich angewandt wurde, kann das Control diese Änderung ignorieren.

Anmerkungen

Um eine GUI mit einer anderen als der voreingestellten Nummer zu bearbeiten (s.u.), muss vor sub-command die Nummer der GUI gefolgt von einem Doppelpunkt eingefügt werden, wie in diesen Beispielen:
GuiControl, 2:Show, MyButton
GuiControl, 2:, MyListBox, Item1|Item2

Ein GUI-Thread ist jeder Thread, der als Folge einer Aktion in einer GUI aufgerufen wird. Das gilt auch für die Auswahl eines Eintrags der Menüzeile der GUI und den Aufruf eines G-Labels, wie z.B. durch Klick auf einen Button.

Die voreingestellte GUI-Nummer eines GUI-Threads ist die der aufrufenden GUI. Andere Threads haben als Voreinstellung die 1.

Siehe auch

Gui, GuiControlGet, Control

Beispiele

GuiControl,, MyListBox, |Red|Green|Blue ; Ersetzt die aktuelle Liste mit einer neuen.
GuiControl,, MyEdit, Neue Textzeile 1.`nNeue Textzeile 2.
GuiControl,, MyRadio2, 1 ; Schaltet diesen Radiobutton ein und alle anderen seiner Gruppe aus.
GuiControl, Move, OK, x100 y200 ; Verschiebt den OK Button.
GuiControl, Focus, LastName ; Setzt den Eingabefokus auf das Control, dessen zugeordnete Variable oder Inhalt "LastName" ist.