CreateWindowExA-Funktion (winuser.h)

Artikel
08/27/2023

Erstellt ein überlappenes, popupfähiges oder untergeordnetes Fenster mit einem erweiterten Fensterstil. Andernfalls ist diese Funktion mit der CreateWindow-Funktion identisch. Weitere Informationen zum Erstellen eines Fensters und vollständige Beschreibungen der anderen Parameter von CreateWindowEx finden Sie unter CreateWindow.

Syntax

HWND CreateWindowExA(
  [in]           DWORD     dwExStyle,
  [in, optional] LPCSTR    lpClassName,
  [in, optional] LPCSTR    lpWindowName,
  [in]           DWORD     dwStyle,
  [in]           int       X,
  [in]           int       Y,
  [in]           int       nWidth,
  [in]           int       nHeight,
  [in, optional] HWND      hWndParent,
  [in, optional] HMENU     hMenu,
  [in, optional] HINSTANCE hInstance,
  [in, optional] LPVOID    lpParam
);

Parameter

[in] dwExStyle

Art: DWORD

Der erweiterte Fensterstil des fensters, das erstellt wird. Eine Liste der möglichen Werte finden Sie unter Erweiterte Fensterstile.

[in, optional] lpClassName

Typ: LPCTSTR

Eine null-endende Zeichenfolge oder ein Klassenatom, das durch einen vorherigen Aufruf der RegisterClass - oder RegisterClassEx-Funktion erstellt wurde. Das Atom muss sich in der niedrigen Reihenfolge des Worts lpClassName befinden. Das Wort mit hoher Ordnung muss 0 (null) sein. Wenn lpClassName eine Zeichenfolge ist, wird der Name der Fensterklasse angegeben. Der Klassenname kann ein beliebiger Name sein, der bei RegisterClass oder RegisterClassEx registriert ist, vorausgesetzt, das Modul, das die Klasse registriert, ist auch das Modul, das das Fenster erstellt. Der Klassenname kann auch jeder der vordefinierten Systemklassennamen sein.

[in, optional] lpWindowName

Typ: LPCTSTR

Der Fenstername. Wenn das Fensterformat eine Titelleiste angibt, wird der Fenstertitel, auf den lpWindowName verweist, in der Titelleiste angezeigt. Wenn Sie CreateWindow zum Erstellen von Steuerelementen wie Schaltflächen, Kontrollkästchen und statischen Steuerelementen verwenden, verwenden Sie lpWindowName , um den Text des Steuerelements anzugeben. Wenn Sie ein statisches Steuerelement mit dem SS_ICON-Stil erstellen, verwenden Sie lpWindowName , um den Symbolnamen oder bezeichner anzugeben. Verwenden Sie die Syntax "#zahl", um einen Bezeichner anzugeben.

[in] dwStyle

Art: DWORD

Der Stil des Fensters, das erstellt wird. Bei diesem Parameter kann es sich um eine Kombination der Fensterstilwerte sowie der im Abschnitt Hinweise angegebenen Steuerelementstile handeln.

[in] X

Typ: int

Die anfängliche horizontale Position des Fensters. Bei einem überlappenden Oder Popupfenster ist der x-Parameter die anfängliche x-Koordinate der oberen linken Ecke des Fensters in Bildschirmkoordinaten. Bei einem untergeordneten Fenster ist x die x-Koordinate der oberen linken Ecke des Fensters relativ zur oberen linken Ecke des Clientbereichs des übergeordneten Fensters. Wenn x auf CW_USEDEFAULT festgelegt ist, wählt das System die Standardposition für die obere linke Ecke des Fensters aus und ignoriert den y-Parameter . CW_USEDEFAULT ist nur für überlappende Fenster gültig; Wenn er für ein Popup- oder untergeordnetes Fenster angegeben ist, werden die Parameter x und y auf 0 (null) festgelegt.

[in] Y

Typ: int

Die anfängliche vertikale Position des Fensters. Bei einem überlappenden Oder Popupfenster ist der y-Parameter die anfängliche y-Koordinate der oberen linken Ecke des Fensters in Bildschirmkoordinaten. Bei einem untergeordneten Fenster ist y die anfängliche y-Koordinate der oberen linken Ecke des untergeordneten Fensters relativ zur oberen linken Ecke des Clientbereichs des übergeordneten Fensters. Bei einem Listenfeld ist y die anfängliche y-Koordinate der oberen linken Ecke des Clientbereichs des Listenfelds relativ zur oberen linken Ecke des Clientbereichs des übergeordneten Fensters.

Wenn ein überlappenes Fenster mit festgelegtem bit WS_VISIBLE Stil erstellt wird und der x-Parameter auf CW_USEDEFAULT festgelegt ist, bestimmt der y-Parameter , wie das Fenster angezeigt wird. Wenn der y-ParameterCW_USEDEFAULT ist, ruft der Fenster-Manager ShowWindow mit dem flag SW_SHOW auf, nachdem das Fenster erstellt wurde. Wenn der y-Parameter ein anderer Wert ist, ruft der Fenster-Manager ShowWindow mit diesem Wert als nCmdShow-Parameter auf.

[in] nWidth

Typ: int

Die Breite des Fensters in Geräteeinheiten. Bei überlappenden Fenstern ist nWidth die Breite des Fensters, in Bildschirmkoordinaten oder CW_USEDEFAULT. Wenn nWidthCW_USEDEFAULT ist, wählt das System eine Standardbreite und -höhe für das Fenster aus. die Standardbreite reicht von den anfänglichen x-Koordinaten bis zum rechten Bildschirmrand; Die Standardhöhe reicht von der anfänglichen y-Koordinate bis zum oberen Rand des Symbolbereichs. CW_USEDEFAULT ist nur für überlappende Fenster gültig; Wenn CW_USEDEFAULT für ein Popup- oder untergeordnetes Fenster angegeben ist, werden die Parameter nWidth und nHeight auf Null festgelegt.

[in] nHeight

Typ: int

Die Höhe des Fensters in Geräteeinheiten. Bei überlappenden Fenstern ist nHeight die Höhe des Fensters in Bildschirmkoordinaten. Wenn der nWidth-Parameter auf CW_USEDEFAULT festgelegt ist, ignoriert das System nHeight.

[in, optional] hWndParent

Typ: HWND

Ein Handle für das übergeordnete Fenster oder das Besitzerfenster des zu erstellenden Fensters. Um ein untergeordnetes Fenster oder ein eigenes Fenster zu erstellen, geben Sie ein gültiges Fensterhandle an. Dieser Parameter ist für Popupfenster optional.

Um ein Fenster mit nur Nachrichten zu erstellen, geben Sie HWND_MESSAGE oder ein Handle für ein vorhandenes Nachrichtenfenster an.

[in, optional] hMenu

Typ: HMENU

Ein Handle für ein Menü oder gibt je nach Fensterstil einen Bezeichner für untergeordnete Fenster an. Bei einem überlappenden Oder Popupfenster identifiziert hMenu das Menü, das mit dem Fenster verwendet werden soll. Es kann NULL sein, wenn das Klassenmenü verwendet werden soll. Für ein untergeordnetes Fenster gibt hMenu den Bezeichner für untergeordnete Fenster an, einen ganzzahligen Wert, der von einem Dialogfeld-Steuerelement verwendet wird, um das übergeordnete Element über Ereignisse zu benachrichtigen. Die Anwendung bestimmt den Bezeichner des untergeordneten Fensters. Sie muss für alle untergeordneten Fenster mit demselben übergeordneten Fenster eindeutig sein.

[in, optional] hInstance

Typ: HINSTANCE

Ein Handle zum instance des Moduls, das dem Fenster zugeordnet werden soll.

[in, optional] lpParam

Typ: LPVOID

Zeiger auf einen Wert, der über die CREATESTRUCT-Struktur (lpCreateParams-Element ) an das Fenster übergeben werden soll, auf die der lParam-Parameter der WM_CREATE Meldung zeigt. Diese Nachricht wird von dieser Funktion an das erstellte Fenster gesendet, bevor sie zurückgegeben wird.

Wenn eine Anwendung CreateWindow aufruft, um ein MDI-Clientfenster zu erstellen, sollte lpParam auf eine CLIENTCREATESTRUCT-Struktur verweisen. Wenn ein MDI-Clientfenster CreateWindow aufruft, um ein untergeordnetes MDI-Fenster zu erstellen, sollte lpParam auf eine MDICREATESTRUCT-Struktur verweisen. lpParam kann NULL sein, wenn keine zusätzlichen Daten erforderlich sind.

Rückgabewert

Typ: HWND

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neue Fenster.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Diese Funktion schlägt in der Regel aus einem der folgenden Gründe fehl:

ein ungültiger Parameterwert
Die Systemklasse wurde von einem anderen Modul registriert.
Der WH_CBT Hook ist installiert und gibt einen Fehlercode zurück.
, wenn eines der Steuerelemente in der Dialogvorlage nicht registriert ist oder die Fensterfensterprozedur WM_CREATE oder WM_NCCREATE

Hinweise

Die CreateWindowEx-Funktion sendet WM_NCCREATE-, WM_NCCALCSIZE- und WM_CREATE-Nachrichten an das fenster, das erstellt wird.

Wenn das erstellte Fenster ein untergeordnetes Fenster ist, befindet sich seine Standardposition am unteren Rand der Z-Reihenfolge. Wenn das erstellte Fenster ein Fenster auf oberster Ebene ist, befindet sich seine Standardposition oben in der Z-Reihenfolge (jedoch unter allen obersten Fenstern, es sei denn, das erstellte Fenster befindet sich selbst am obersten Rand).

Informationen zum Steuern, ob die Taskleiste eine Schaltfläche für das erstellte Fenster anzeigt, finden Sie unter Verwalten von Taskleistenschaltflächen.

Informationen zum Entfernen eines Fensters finden Sie unter der DestroyWindow-Funktion .

Die folgenden vordefinierten Steuerelementklassen können im lpClassName-Parameter angegeben werden. Beachten Sie die entsprechenden Steuerelementstile, die Sie im dwStyle-Parameter verwenden können.

Klasse	Bedeutung
SCHALTFLÄCHE	Gibt ein kleines rechteckiges untergeordnetes Fenster an, das eine Schaltfläche darstellt, auf die der Benutzer klicken kann, um sie zu aktivieren oder zu deaktivieren. Schaltflächensteuerelemente können allein oder in Gruppen verwendet werden, und sie können entweder beschriftet oder ohne Text angezeigt werden. Schaltflächensteuerelemente ändern in der Regel das Erscheinungsbild, wenn der Benutzer darauf klickt. Weitere Informationen finden Sie unter Schaltflächen. Eine Tabelle der Schaltflächenstile, die Sie im dwStyle-Parameter angeben können, finden Sie unter Schaltflächenstile.
COMBOBOX	Legt ein Steuerelement fest, das aus einem Listenfeld und einem Auswahlfeld besteht, das einem Bearbeitungssteuerelement ähnelt. Bei Verwendung dieses Stils sollte eine Anwendung entweder das Listenfeld jederzeit anzeigen oder ein Dropdown-Listenfeld aktivieren. Wenn das Listenfeld sichtbar ist, hebt die Eingabe von Zeichen in das Auswahlfeld den ersten Listenfeldeintrag hervor, der den eingegebenen Zeichen entspricht. Umgekehrt wird beim Auswählen eines Elements im Listenfeld der ausgewählte Text im Auswahlfeld angezeigt. Weitere Informationen finden Sie unter Kombinationsfelder. Eine Tabelle der Kombinationsfeldstile, die Sie im dwStyle-Parameter angeben können, finden Sie unter Kombinationsfeldstile.
BEARBEITEN	Gibt ein rechteckiges untergeordnetes Fenster an, in das der Benutzer Text von der Tastatur eingeben kann. Der Benutzer wählt das Steuerelement aus und gibt dem Steuerelement den Tastaturfokus, indem er darauf klickt oder durch Drücken der TAB-TASTE zu diesem Steuerelement wechselt. Der Benutzer kann Text eingeben, wenn das Bearbeitungssteuerelement ein blinkendes Caretzeichen anzeigt. verwenden Sie die Maus, um den Cursor zu bewegen, zu ersetzende Zeichen auszuwählen oder den Cursor zum Einfügen von Zeichen zu positionieren. oder verwenden Sie den Schlüssel, um Zeichen zu löschen. Weitere Informationen finden Sie unter Bearbeiten von Steuerelementen. Eine Tabelle der Bearbeitungssteuerelementstile, die Sie im dwStyle-Parameter angeben können, finden Sie unter Bearbeiten von Steuerelementstilen.
LISTBOX	Gibt eine Liste von Zeichenfolgen an. Geben Sie dieses Steuerelement immer dann an, wenn eine Anwendung eine Liste von Namen( z. B. Dateinamen) angeben muss, aus denen der Benutzer auswählen kann. Der Benutzer kann eine Zeichenfolge auswählen, indem er darauf klickt. Eine ausgewählte Zeichenfolge ist hervorgehoben, und eine Benachrichtigung wird an das übergeordnete Fenster übergeben. Weitere Informationen finden Sie unter Listenfelder. Eine Tabelle der Listenfeldformatvorlagen, die Sie im dwStyle-Parameter angeben können, finden Sie unter Listenfeldformatvorlagen.
MDICLIENT	Legt ein MDI-Clientfenster fest. Dieses Fenster empfängt Meldungen, die die untergeordneten Fenster der MDI-Anwendung steuern. Die empfohlenen Stilbits sind WS_CLIPCHILDREN und WS_CHILD. Geben Sie die formatvorlagen WS_HSCROLL und WS_VSCROLL an, um ein MDI-Clientfenster zu erstellen, in dem der Benutzer untergeordnete MDI-Fenster in die Ansicht scrollen kann. Weitere Informationen finden Sie unter Schnittstelle für mehrere Dokumente.
RichEdit	Legt ein Microsoft Rich Edit 1.0-Steuerelement fest. In diesem Fenster können Benutzer Text mit Zeichen- und Absatzformatierung anzeigen und bearbeiten und eingebettete COM-Objekte (Component Object Model) enthalten. Weitere Informationen finden Sie unter Rich Edit Controls. Eine Tabelle mit den Rich-Bearbeitungssteuerelementstilen, die Sie im dwStyle-Parameter angeben können, finden Sie unter Rich Edit Control Styles.
RICHEDIT_CLASS	Legt ein Microsoft Rich Edit 2.0-Steuerelement fest. Mit diesen Steuerelementen können Benutzer Text mit Zeichen- und Absatzformatierung anzeigen und bearbeiten und eingebettete COM-Objekte enthalten. Weitere Informationen finden Sie unter Rich Edit Controls. Eine Tabelle mit den Rich-Bearbeitungssteuerelementstilen, die Sie im dwStyle-Parameter angeben können, finden Sie unter Rich Edit Control Styles.
SCROLLBAR	Gibt ein Rechteck an, das ein Bildlauffeld enthält und an beiden Enden Richtungspfeile aufweist. Die Bildlaufleiste sendet eine Benachrichtigung an das übergeordnete Fenster, wenn der Benutzer auf das Steuerelement klickt. Das übergeordnete Fenster ist für die Aktualisierung der Position des Bildlauffelds zuständig, falls erforderlich. Weitere Informationen finden Sie unter Bildlaufleisten. Eine Tabelle der Bildlaufleisten-Steuerelementstile, die Sie im dwStyle-Parameter angeben können, finden Sie unter Bildlaufleisten-Steuerelementstile.
STATISCHE	Gibt ein einfaches Textfeld, Feld oder Rechteck an, das zum Bezeichnen, Kontrollkästchen oder Trennen anderer Steuerelemente verwendet wird. Statische Steuerelemente nehmen keine Eingaben und stellen keine Ausgabe bereit. Weitere Informationen finden Sie unter Statische Steuerelemente. Eine Tabelle der statischen Steuerelementstile, die Sie im dwStyle-Parameter angeben können, finden Sie unter Stile für statische Steuerelemente.

Der WS_EX_NOACTIVATE Wert für dwExStyle verhindert die Aktivierung des Vordergrunds durch das System. Um die Aktivierung der Warteschlange zu verhindern, wenn der Benutzer auf das Fenster klickt, müssen Sie die WM_MOUSEACTIVATE Meldung entsprechend verarbeiten. Um das Fenster in den Vordergrund zu bringen oder es programmgesteuert zu aktivieren, verwenden Sie SetForegroundWindow oder SetActiveWindow. Die Rückgabe von FALSE an WM_NCACTIVATE verhindert, dass das Fenster die Warteschlangenaktivierung verliert. Der Rückgabewert wird jedoch zur Aktivierungszeit ignoriert.

Wenn WS_EX_COMPOSITED festgelegt ist, erhalten alle Nachfolger eines Fensters die Strichreihenfolge von unten nach oben mithilfe der Doppeltpufferung. Die Bildreihenfolge von unten nach oben ermöglicht es einem absteigenden Fenster, Transluzenzeffekte (Alpha) und Transparenzeffekte (Farbschlüssel) zu haben, aber nur, wenn im Nachkommefenster auch das WS_EX_TRANSPARENT Bit festgelegt ist. Durch die Doppelpufferung können das Fenster und seine Nachfolger ohne Flimmern gezeichnet werden.

Beispiel

Der folgende Beispielcode veranschaulicht die Verwendung von CreateWindowExA.

BOOL Create(
        PCWSTR lpWindowName,
        DWORD dwStyle,
        DWORD dwExStyle = 0,
        int x = CW_USEDEFAULT,
        int y = CW_USEDEFAULT,
        int nWidth = CW_USEDEFAULT,
        int nHeight = CW_USEDEFAULT,
        HWND hWndParent = 0,
        HMENU hMenu = 0
        )
    {
        WNDCLASS wc = {0};

        wc.lpfnWndProc   = DERIVED_TYPE::WindowProc;
        wc.hInstance     = GetModuleHandle(NULL);
        wc.lpszClassName = ClassName();

        RegisterClass(&wc);

        m_hwnd = CreateWindowEx(
            dwExStyle, ClassName(), lpWindowName, dwStyle, x, y,
            nWidth, nHeight, hWndParent, hMenu, GetModuleHandle(NULL), this
            );

        return (m_hwnd ? TRUE : FALSE);
    }

Hinweis

Der winuser.h-Header definiert CreateWindowEx 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
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-window-l1-1-0 (eingeführt in Windows 8)