CreateWindowExA-Funktion (winuser.h)

Artikel
11/18/2024

Erstellt ein überlappende, Popup- oder untergeordnetes Fenster mit einem erweiterten Fensterstil. andernfalls ist diese Funktion identisch mit der CreateWindow--Funktion. Weitere Informationen zum Erstellen eines Fensters und zur vollständigen Beschreibung der anderen Parameter von CreateWindowExfinden 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

Typ: DWORD-

Das erweiterte Fensterformat des zu erstellenden Fensters. Eine Liste der möglichen Werte finden Sie unter erweiterten Fensterformatvorlagen.

[in, optional] lpClassName

Typ: LPCTSTR-

Eine null-terminated string or a class atom.

Wenn eine null-terminated string, gibt sie den Namen der Fensterklasse an. Der Klassenname kann ein beliebiger Name sein, der bei der RegisterClass oder RegisterClassEx--Funktion registriert ist, vorausgesetzt, dass das Modul, das die Klasse registriert, auch das Modul ist, das das Fenster erstellt. Der Klassenname kann auch eine der vordefinierten Systemklasse Namen sein.

Wenn ein Klassenatom, das durch einen vorherigen Aufruf von RegisterClass oder RegisterClassExerstellt wurde, muss es mithilfe des Makros MAKEINTATOMkonvertiert werden. (Das Atom muss sich im Wort "low-order" von lpClassNamebefinden; das Wort mit hoher Reihenfolge muss null sein.)

[in, optional] lpWindowName

Typ: LPCTSTR-

Der Fenstername. Wenn die Fensterformatvorlage 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. Verwenden Sie beim Erstellen eines statischen Steuerelements mit der SS_ICON-Formatvorlage lpWindowName-, um den Symbolnamen oder den Bezeichner anzugeben. Um einen Bezeichner anzugeben, verwenden Sie die Syntax "#Zahl".

[in] dwStyle

Typ: DWORD-

Die Formatvorlage des zu erstellenden Fensters. Dieser Parameter kann eine Kombination aus den Fensterformatwertenund den im Abschnitt "Hinweise" angegebenen Steuerelementformatvorlagen sein.

[in] X

Typ: int

Die anfängliche horizontale Position des Fensters. Bei einem überlappenden oder Popupfenster ist der parameter x die erste 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_USEDEFAULTfestgelegt ist, wählt das System die Standardposition für die obere linke Ecke des Fensters aus und ignoriert den y Parameter. CW_USEDEFAULT gilt nur für überlappende Fenster; Wenn sie für ein Popup- oder untergeordnetes Fenster angegeben ist, werden die parameter x und y parameter auf 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. Für ein Listenfeld y ist 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 überlappende Fenster mit dem Bitsatz WS_VISIBLE Formatvorlage erstellt wird und der parameter x auf CW_USEDEFAULTfestgelegt ist, bestimmt der y Parameter, wie das Fenster angezeigt wird. Wenn der y-Parameter CW_USEDEFAULTist, ruft der Fenster-Manager ShowWindow mit dem SW_SHOW Flag 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 nWidth-CW_USEDEFAULTist, 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 Rand des Bildschirms; die Standardhöhe reicht von der anfänglichen y-Koordinate bis zum oberen Rand des Symbolbereichs. CW_USEDEFAULT gilt nur für überlappende Fenster; wenn CW_USEDEFAULT für ein Popup- oder untergeordnetes Fenster angegeben ist, werden die nWidth- und nHeight--Parameter 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_USEDEFAULTfestgelegt 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 einen gültigen Fensterziehpunkt an. Dieser Parameter ist optional für Popupfenster.

Um ein nur-Nachrichtenfensterzu erstellen, geben Sie HWND_MESSAGE oder ein Handle für ein vorhandenes Nur-Nachrichten-Fenster an.

[in, optional] hMenu

Typ: HMENU

Ein Handle zu einem Menü oder gibt je nach Fensterformat 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 des untergeordneten Fensters 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; Es muss für alle untergeordneten Fenster mit demselben übergeordneten Fenster eindeutig sein.

[in, optional] hInstance

Typ: HINSTANCE-

Ein Handle für die Instanz des Moduls, das dem Fenster zugeordnet werden soll.

[in, optional] lpParam

Typ: LPVOID-

Zeiger auf einen Wert, der über die CREATESTRUCT Struktur an das Fenster übergeben werden soll (lpCreateParams Member), auf den das lParam Param der WM_CREATE Nachricht verweist. Diese Nachricht wird vor dem Zurückgeben an das erstellte Fenster von dieser Funktion gesendet.

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 die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

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

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

Bemerkungen

Die CreateWindowEx--Funktion sendet WM_NCCREATE, WM_NCCALCSIZEund WM_CREATE Nachrichten an das zu erstellende Fenster.

Wenn das erstellte Fenster ein untergeordnetes Fenster ist, befindet sich die Standardposition unten in der Z-Reihenfolge. Wenn das erstellte Fenster ein Fenster der obersten Ebene ist, befindet sich die Standardposition oben in der Z-Reihenfolge (aber unter allen obersten Fenstern, es sei denn, das erstellte Fenster befindet sich ganz oben).

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 in der funktion DestroyWindow.

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

Klasse	Bedeutung
BUTTON-	Legt ein kleines rechteckiges untergeordnetes Fenster fest, das eine Schaltfläche darstellt, auf die der Benutzer klicken kann, um es zu aktivieren oder zu deaktivieren. Schaltflächensteuerelemente können allein oder in Gruppen verwendet werden, und sie können entweder ohne Text beschriftet oder angezeigt werden. Schaltflächensteuerelemente ändern in der Regel die Darstellung, wenn der Benutzer darauf klickt. Weitere Informationen finden Sie unter Schaltflächen. Eine Tabelle der Schaltflächenformatvorlagen, die Sie im parameter dwStyle angeben können, finden Sie unter Button Styles.
COMBOBOX-	Legt ein Steuerelement fest, das aus einem Listenfeld und einem Auswahlfeld besteht, das einem Bearbeitungssteuerelement ähnelt. Wenn Sie diese Formatvorlage verwenden, sollte eine Anwendung das Listenfeld jederzeit anzeigen oder ein Dropdown-Listenfeld aktivieren. Wenn das Listenfeld sichtbar ist, werden durch Eingeben von Zeichen in das Auswahlfeld der erste Listenfeldeintrag hervorgehoben, der den eingegebenen Zeichen entspricht. Umgekehrt wird beim Auswählen eines Elements im Listenfeld der markierte Text im Auswahlfeld angezeigt. Weitere Informationen finden Sie unter Kombinationsfelder. Eine Tabelle der Kombinationsfeldarten, die Sie im dwStyle--Parameter angeben können, finden Sie unter Kombinationsfeldarten.
EDIT	Legt ein rechteckiges untergeordnetes Fenster fest, in das der Benutzer Text über die 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 dem Steuerelement wechselt. Der Benutzer kann Text eingeben, wenn das Bearbeitungssteuerelement eine blinkende Caret anzeigt. Verwenden Sie die Maus, um den Cursor zu verschieben, zeichen auszuwählen, die ersetzt werden sollen, oder positionieren Sie den Cursor zum Einfügen von Zeichen. oder verwenden Sie den Schlüssel, um Zeichen zu löschen. Weitere Informationen finden Sie unter Bearbeiten von Steuerelementen. Eine Tabelle der Bearbeitungssteuerelementformatvorlagen, die Sie im dwStyle--Parameter angeben können, finden Sie unter Edit Control Styles.
LISTBOX-	Legt eine Liste von Zeichenfolgen fest. Geben Sie dieses Steuerelement an, wenn eine Anwendung eine Liste von Namen, z. B. Dateinamen, darstellen 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 Nachrichten, die die untergeordneten Fenster der MDI-Anwendung steuern. Die empfohlenen Formatvorlagenbits sind WS_CLIPCHILDREN und WS_CHILD. Geben Sie die formatvorlagen WS_HSCROLL und WS_VSCROLL an, um ein MDI-Clientfenster zu erstellen, das dem Benutzer das Scrollen untergeordneter MDI-Fenster in die Ansicht ermöglicht. Weitere Informationen finden Sie unter Multiple Document Interface.
RichEdit-	Legt ein Microsoft Rich Edit 1.0-Steuerelement fest. In diesem Fenster kann der Benutzer Text mit Zeichen- und Absatzformatierungen anzeigen und bearbeiten und eingebettete COM-Objekte (Component Object Model) enthalten. Weitere Informationen finden Sie unter Rich Edit Controls. Eine Tabelle der Rich-Edit-Steuerelementstile, 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 Absatzformatierungen anzeigen und bearbeiten und eingebettete COM-Objekte enthalten. Weitere Informationen finden Sie unter Rich Edit Controls. Eine Tabelle der Rich-Edit-Steuerelementstile, die Sie im dwStyle--Parameter angeben können, finden Sie unter Rich Edit Control Styles.
SCROLLBAR-	Legt ein Rechteck fest, das ein Bildlauffeld enthält und Richtungspfeile an beiden Enden aufweist. Die Bildlaufleiste sendet eine Benachrichtigung an das übergeordnete Fenster, wenn der Benutzer auf das Steuerelement klickt. Das übergeordnete Fenster ist bei Bedarf für die Aktualisierung der Position des Bildlauffelds verantwortlich. Weitere Informationen finden Sie unter Bildlaufleisten. Eine Tabelle der Bildlaufleisten-Steuerelementarten, die Sie im parameter dwStyle angeben können, finden Sie unter Bildlaufleisten-Steuerelementarten.
STATIC-	Legt ein einfaches Textfeld, ein Feld oder ein Rechteck fest, das zum Bezeichnen, Feld oder Trennen anderer Steuerelemente verwendet wird. Statische Steuerelemente nehmen keine Eingabe und geben keine Ausgabe an. Weitere Informationen finden Sie unter statische Steuerelemente. Eine Tabelle der statischen Steuerelementformatvorlagen, die Sie im dwStyle--Parameter angeben können, finden Sie unter Statische Steuerelementarten.

Der WS_EX_NOACTIVATE Wert für dwExStyle verhindert die Vordergrundaktivierung durch das System. Um die Warteschlangenaktivierung zu verhindern, wenn der Benutzer auf das Fenster klickt, müssen Sie die WM_MOUSEACTIVATE Nachricht entsprechend verarbeiten. Verwenden Sie SetForegroundWindow oder SetActiveWindow, um das Fenster programmgesteuert in den Vordergrund zu bringen oder es programmgesteuert zu aktivieren. Das Zurückgeben 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 Untergeordneten eines Fensters die Unter-nach-oben-Zeichenreihenfolge mithilfe von Doppelpufferung. Die Reihenfolge der untersten Bis-oben-Zeichen ermöglicht es einem absteigenden Fenster, Transluzenzeffekte (Alpha) und Transparenz (Farbtasteneffekt) zu haben, aber nur, wenn das absteigende Fenster auch den WS_EX_TRANSPARENT Bitsatz aufweist. Durch die Doppelpufferung kann das Fenster und seine Absteigenden ohne Flackern 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);
    }

Anmerkung

Der winuser.h-Header definiert CreateWindowEx als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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ützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll
API-Satz	ext-ms-win-ntuser-window-l1-1-0 (eingeführt in Windows 8)