SetWindowLongA-Funktion (winuser.h)

2025-05-21

Ändert ein Attribut des angegebenen Fensters. Die Funktion legt auch den 32-Bit-Wert (lang) am angegebenen Offset in den zusätzlichen Fensterspeicher fest.

Anmerkung Diese Funktion wurde durch die SetWindowLongPtr-Funktion ersetzt. Verwenden Sie die SetWindowLongPtr-Funktion , um Code zu schreiben, der sowohl mit 32-Bit- als auch mit 64-Bit-Versionen von Windows kompatibel ist.

Syntax

LONG SetWindowLongA(
  [in] HWND hWnd,
  [in] int  nIndex,
  [in] LONG dwNewLong
);

Die Parameter

[in] hWnd

Typ: HWND-

Ein Handle für das Fenster und indirekt die Klasse, zu der das Fenster gehört.

[in] nIndex

Typ: int

Der nullbasierte Offset auf den festzulegenden Wert. Gültige Werte liegen im Bereich 0 bis zur Anzahl der Bytes des zusätzlichen Fensterspeichers, minus der Größe einer ganzen Zahl. Wenn Sie einen anderen Wert festlegen möchten, geben Sie einen der folgenden Werte an.

Wert	Bedeutung
GWL_EXSTYLE -20	Legt eine neue Formatvorlage für erweiterte Fenster fest.
GWL_HINSTANCE -6	Legt ein neues Anwendungsinstanzhandle fest.
GWL_HWNDPARENT -8	Legt einen neuen Besitzer für ein Fenster der obersten Ebene fest.
GWL_ID -12	Legt einen neuen Bezeichner des untergeordneten Fensters fest. Das Fenster kann kein Fenster der obersten Ebene sein.
GWL_STYLE -16	Legt eine neue Fensterformatvorlage fest.
GWL_USERDATA -21	Legt die Benutzerdaten fest, die dem Fenster zugeordnet sind. Diese Daten sind für die Verwendung durch die Anwendung vorgesehen, die das Fenster erstellt hat. Der Wert ist anfangs null.
GWL_WNDPROC –4	Legt eine neue Adresse für die Fensterprozedur fest. Sie können dieses Attribut nicht ändern, wenn das Fenster nicht zum gleichen Prozess wie der aufrufende Thread gehört.

Die folgenden Werte sind auch verfügbar, wenn der hWnd-Parameter ein Dialogfeld identifiziert.

Wert	Bedeutung
DWL_DLGPROC DWLP_MSGRESULT + sizeof(LRESULT)	Legt die neue Adresse der Dialogfeldprozedur fest.
DWL_MSGRESULT 0	Legt den Rückgabewert einer Nachricht fest, die in der Dialogfeldprozedur verarbeitet wird.
DWL_USER DWLP_DLGPROC + sizeof(DLGPROC)	Legt neue zusätzliche Informationen fest, die für die Anwendung privat sind, z. B. Handles oder Zeiger.

[in] dwNewLong

Typ: LONG

Der Ersetzungswert.

Rückgabewert

Typ: LONG

Wenn die Funktion erfolgreich ist, ist der Rückgabewert der vorherigen Wert der angegebenen 32-Bit-Ganzzahl.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Wenn der vorherige Wert der angegebenen 32-Bit-Ganzzahl null ist und die Funktion erfolgreich ist, ist der Rückgabewert null, die Funktion löscht jedoch nicht die letzten Fehlerinformationen. Dies macht es schwierig, Erfolg oder Fehler zu ermitteln. Um dies zu umgehen, sollten Sie die letzten Fehlerinformationen löschen, indem Sie SetLastError mit 0 aufrufen, bevor Sie SetWindowLong aufrufen. Dann wird funktionsfehler durch einen Rückgabewert von Null und ein GetLastError-Ergebnis angegeben, das ungleich Null ist.

Bemerkungen

Bestimmte Fensterdaten werden zwischengespeichert, sodass Änderungen, die Sie mit SetWindowLong vornehmen, erst wirksam werden, wenn Sie die SetWindowPos-Funktion aufrufen. Wenn Sie eines der Frameformatvorlagen ändern, müssen Sie SetWindowPos mit dem SWP_FRAMECHANGED Flag aufrufen, damit der Cache ordnungsgemäß aktualisiert wird.

Wenn Sie SetWindowLong mit dem GWL_WNDPROC Index verwenden, um die Fensterprozedur zu ersetzen, muss die Fensterprozedur den Richtlinien entsprechen, die in der Beschreibung der WindowProc-Rückruffunktion angegeben sind.

Wenn Sie SetWindowLong mit dem DWL_MSGRESULT Index verwenden, um den Rückgabewert für eine nachricht festzulegen, die von einer Dialogfeldprozedur verarbeitet wird, sollten Sie TRUE direkt danach zurückgeben. Wenn Sie andernfalls eine Funktion aufrufen, die dazu führt, dass ihre Dialogfeldprozedur eine Fenstermeldung empfängt, könnte die geschachtelte Fenstermeldung den Rückgabewert überschreiben, den Sie mit DWL_MSGRESULT festgelegt haben.

Durch Aufrufen von SetWindowLong mit dem GWL_WNDPROC Index wird eine Unterklasse der Fensterklasse erstellt, die zum Erstellen des Fensters verwendet wird. Eine Anwendung kann eine Systemklasse unterklassen, sollte jedoch keine Fensterklasse unterklassen, die von einem anderen Prozess erstellt wurde. Die SetWindowLong-Funktion erstellt die Fensterunterklasse durch Ändern der Fensterprozedur, die einer bestimmten Fensterklasse zugeordnet ist, wodurch das System die neue Fensterprozedur anstelle des vorherigen Aufrufs aufruft. Eine Anwendung muss alle Nachrichten übergeben, die nicht von der neuen Fensterprozedur an die vorherige Fensterprozedur verarbeitet werden, indem CallWindowProc aufgerufen wird. Auf diese Weise kann die Anwendung eine Kette von Fensterprozeduren erstellen.

Reservieren Sie zusätzlichen Fensterspeicher, indem Sie einen Wert ungleich Null im cbWndExtra-Element der WNDCLASSEX-Struktur angeben, die mit der RegisterClassEx-Funktion verwendet wird.

Rufen Sie SetWindowLong nicht mit dem GWL_HWNDPARENT Index auf, um das übergeordnete Element eines untergeordneten Fensters zu ändern. Verwenden Sie stattdessen die SetParent-Funktion .

GWL_HWNDPARENT wird verwendet, um den Besitzer eines Fensters der obersten Ebene und nicht das übergeordnete Fenster eines untergeordneten Fensters zu ändern.

Ein Fenster kann entweder über ein übergeordnetes Element oder einen Besitzer verfügen, aber nicht beide gleichzeitig.

Wenn das Fenster eine Klassenformatvorlage CS_CLASSDC oderCS_OWNDC aufweist, legen Sie die Formatvorlagen für erweiterte Fenster nicht WS_EX_COMPOSITED oder WS_EX_LAYERED fest.

Durch Aufrufen von SetWindowLong zum Festlegen der Formatvorlage auf einer Statusleiste wird die Position zurückgesetzt.

Beispiele

Ein Beispiel finden Sie unter "Unterklassen eines Fensters".

Hinweis

Der winuser.h-Header definiert SetWindowLong als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Mindestens unterstützter Client	Windows 2000 Professional [nur Desktop-Apps]
Mindestanforderungen für unterstützte Server	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Fenster
Überschrift	winuser.h (enthalten Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
API-Satz	ext-ms-win-ntuser-windowclass-l1-1-0 (eingeführt in Windows 8)