Fonction CreateWindowExA (winuser.h)

Article
08/27/2023

Crée une fenêtre superposée, contextuelle ou enfant avec un style de fenêtre étendu ; sinon, cette fonction est identique à la fonction CreateWindow . Pour plus d’informations sur la création d’une fenêtre et pour obtenir une description complète des autres paramètres de CreateWindowEx, consultez CreateWindow.

Syntaxe

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
);

Paramètres

[in] dwExStyle

Type : DWORD

Style de fenêtre étendu de la fenêtre en cours de création. Pour obtenir la liste des valeurs possibles, consultez Styles de fenêtre étendus.

[in, optional] lpClassName

Type : LPCTSTR

Chaîne terminée par null ou atome de classe créé par un appel précédent à la fonction RegisterClass ou RegisterClassEx. L’atome doit être dans le mot d’ordre inférieur de lpClassName ; le mot d’ordre supérieur doit être égal à zéro. Si lpClassName est une chaîne, il spécifie le nom de la classe de fenêtre. Le nom de la classe peut être n’importe quel nom inscrit auprès de RegisterClass ou RegisterClassEx, à condition que le module qui inscrit la classe soit également le module qui crée la fenêtre. Le nom de la classe peut également être l’un des noms de classe système prédéfinis.

[in, optional] lpWindowName

Type : LPCTSTR

Nom de fenêtre. Si le style de la fenêtre spécifie une barre de titre, le titre de la fenêtre pointé par lpWindowName s’affiche dans la barre de titre. Lorsque vous utilisez CreateWindow pour créer des contrôles, tels que des boutons, des case activée des zones et des contrôles statiques, utilisez lpWindowName pour spécifier le texte du contrôle. Lors de la création d’un contrôle statique avec le style SS_ICON , utilisez lpWindowName pour spécifier le nom ou l’identificateur de l’icône. Pour spécifier un identificateur, utilisez la syntaxe « #num ».

[in] dwStyle

Type : DWORD

Style de la fenêtre en cours de création. Ce paramètre peut être une combinaison des valeurs de style de fenêtre, ainsi que des styles de contrôle indiqués dans la section Remarques.

[in] X

Type : int

Position horizontale initiale de la fenêtre. Pour une fenêtre contextuelle ou superposée, le paramètre x est la coordonnée x initiale du coin supérieur gauche de la fenêtre, en coordonnées d’écran. Pour une fenêtre enfant, x est la coordonnée x du coin supérieur gauche de la fenêtre par rapport à l’angle supérieur gauche de la zone cliente de la fenêtre parente. Si x est défini sur CW_USEDEFAULT, le système sélectionne la position par défaut pour le coin supérieur gauche de la fenêtre et ignore le paramètre y . CW_USEDEFAULT est valide uniquement pour les fenêtres qui se chevauchent ; si elle est spécifiée pour une fenêtre contextuelle ou enfant, les paramètres x et y sont définis sur zéro.

[in] Y

Type : int

Position verticale initiale de la fenêtre. Pour une fenêtre contextuelle ou superposée, le paramètre y est la coordonnée y initiale du coin supérieur gauche de la fenêtre, en coordonnées d’écran. Pour une fenêtre enfant, y est la coordonnée y initiale du coin supérieur gauche de la fenêtre enfant par rapport au coin supérieur gauche de la zone cliente de la fenêtre parente. Pour une zone de liste , y est la coordonnée y initiale du coin supérieur gauche de la zone cliente de la zone de liste par rapport à l’angle supérieur gauche de la zone cliente de la fenêtre parente.

Si une fenêtre superposée est créée avec le WS_VISIBLE jeu de bits de style et que le paramètre x a la valeur CW_USEDEFAULT, le paramètre y détermine la façon dont la fenêtre est affichée. Si le paramètre y est CW_USEDEFAULT, le gestionnaire de fenêtres appelle ShowWindow avec l’indicateur SW_SHOW une fois la fenêtre créée. Si le paramètre y est une autre valeur, le gestionnaire de fenêtres appelle ShowWindow avec cette valeur comme paramètre nCmdShow .

[in] nWidth

Type : int

Largeur, en unités d’appareil, de la fenêtre. Pour les fenêtres qui se chevauchent, nWidth est la largeur de la fenêtre, en coordonnées d’écran ou CW_USEDEFAULT. Si nWidth est CW_USEDEFAULT, le système sélectionne une largeur et une hauteur par défaut pour la fenêtre ; la largeur par défaut s’étend des coordonnées x initiales au bord droit de l’écran ; La hauteur par défaut s’étend de la coordonnée y initiale jusqu’au haut de la zone d’icône. CW_USEDEFAULT est valide uniquement pour les fenêtres qui se chevauchent ; si CW_USEDEFAULT est spécifié pour une fenêtre contextuelle ou enfant, les paramètres nWidth et nHeight sont définis sur zéro.

[in] nHeight

Type : int

Hauteur, en unités d’appareil, de la fenêtre. Pour les fenêtres superposées, nHeight est la hauteur de la fenêtre, en coordonnées d’écran. Si le paramètre nWidth est défini sur CW_USEDEFAULT, le système ignore nHeight.

[in, optional] hWndParent

Type : HWND

Handle de la fenêtre parente ou propriétaire de la fenêtre en cours de création. Pour créer une fenêtre enfant ou une fenêtre détenue, fournissez un handle de fenêtre valide. Ce paramètre est facultatif pour les fenêtres contextuelles.

Pour créer une fenêtre de message uniquement, fournissez HWND_MESSAGE ou un handle à une fenêtre de message uniquement existante.

[in, optional] hMenu

Type : HMENU

Handle d’un menu ou spécifie un identificateur de fenêtre enfant, en fonction du style de fenêtre. Pour une fenêtre contextuelle ou superposée, hMenu identifie le menu à utiliser avec la fenêtre ; elle peut être NULL si le menu de classe doit être utilisé. Pour une fenêtre enfant, hMenu spécifie l’identificateur de fenêtre enfant, une valeur entière utilisée par un contrôle de boîte de dialogue pour informer son parent des événements. L’application détermine l’identificateur de fenêtre enfant ; elle doit être unique pour toutes les fenêtres enfants avec la même fenêtre parente.

[in, optional] hInstance

Type : HINSTANCE

Handle du instance du module à associer à la fenêtre.

[in, optional] lpParam

Type : LPVOID

Pointeur vers une valeur à passer à la fenêtre via la structure CREATESTRUCT (membre lpCreateParams ) pointée par le paramètre lParam du message WM_CREATE . Ce message est envoyé à la fenêtre créée par cette fonction avant qu’elle ne retourne.

Si une application appelle CreateWindow pour créer une fenêtre cliente MDI, lpParam doit pointer vers une structure CLIENTCREATESTRUCT . Si une fenêtre cliente MDI appelle CreateWindow pour créer une fenêtre enfant MDI, lpParam doit pointer vers une structure MDICREATESTRUCT . lpParam peut avoir la valeur NULL si aucune donnée supplémentaire n’est nécessaire.

Valeur retournée

Type : HWND

Si la fonction réussit, la valeur de retour est un handle pour la nouvelle fenêtre.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Cette fonction échoue généralement pour l’une des raisons suivantes :

valeur de paramètre non valide
la classe système a été inscrite par un autre module
Le hook WH_CBT est installé et retourne un code d’échec
si l’un des contrôles du modèle de boîte de dialogue n’est pas inscrit, ou si sa procédure de fenêtre échoue WM_CREATE ou WM_NCCREATE

Remarques

La fonction CreateWindowEx envoie des messages WM_NCCREATE, WM_NCCALCSIZE et WM_CREATE à la fenêtre en cours de création.

Si la fenêtre créée est une fenêtre enfant, sa position par défaut se trouve en bas de l’ordre de plan. Si la fenêtre créée est une fenêtre de niveau supérieur, sa position par défaut se trouve en haut de l’ordre de plan (mais sous toutes les fenêtres les plus supérieures, sauf si la fenêtre créée est elle-même la plus haute).

Pour plus d’informations sur le contrôle de l’affichage d’un bouton dans la barre des tâches pour la fenêtre créée, consultez Gestion des boutons de la barre des tâches.

Pour plus d’informations sur la suppression d’une fenêtre, consultez la fonction DestroyWindow .

Les classes de contrôle prédéfinies suivantes peuvent être spécifiées dans le paramètre lpClassName . Notez les styles de contrôle correspondants que vous pouvez utiliser dans le paramètre dwStyle .

Classe	Signification
BOUTON	Désigne une petite fenêtre enfant rectangulaire qui représente un bouton sur lequel l’utilisateur peut cliquer pour l’activer ou le désactiver. Les contrôles de bouton peuvent être utilisés seuls ou en groupes, et ils peuvent être étiquetés ou apparaître sans texte. Les contrôles de bouton changent généralement d’apparence lorsque l’utilisateur clique dessus. Pour plus d’informations, consultez Boutons. Pour obtenir un tableau des styles de bouton que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de bouton.
COMBOBOX	Désigne un contrôle constitué d’une zone de liste et d’un champ de sélection similaire à un contrôle d’édition. Lorsque vous utilisez ce style, une application doit afficher la zone de liste à tout moment ou activer une zone de liste déroulante. Si la zone de liste est visible, la saisie de caractères dans le champ de sélection met en surbrillance la première entrée de zone de liste qui correspond aux caractères tapés. À l’inverse, la sélection d’un élément dans la zone de liste affiche le texte sélectionné dans le champ de sélection. Pour plus d’informations, consultez Zones de liste déroulante. Pour obtenir un tableau des styles de zone de liste modifiable que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de zone de liste déroulante.
MODIFIER	Désigne une fenêtre enfant rectangulaire dans laquelle l’utilisateur peut taper du texte à partir du clavier. L’utilisateur sélectionne le contrôle et lui donne le focus clavier en cliquant dessus ou en appuyant sur la touche TAB. L’utilisateur peut taper du texte lorsque le contrôle d’édition affiche une carete clignotante ; utilisez la souris pour déplacer le curseur, sélectionner des caractères à remplacer ou positionner le curseur pour l’insertion de caractères ; ou utilisez la clé pour supprimer des caractères. Pour plus d’informations, consultez Modifier les contrôles. Pour obtenir une table des styles de contrôle de modification que vous pouvez spécifier dans le paramètre dwStyle , consultez Modifier les styles de contrôle.
LISTBOX	Désigne une liste de chaînes de caractères. Spécifiez ce contrôle chaque fois qu’une application doit présenter une liste de noms, tels que des noms de fichiers, à partir desquels l’utilisateur peut choisir. L’utilisateur peut sélectionner une chaîne en cliquant dessus. Une chaîne sélectionnée est mise en surbrillance et un message de notification est passé à la fenêtre parente. Pour plus d’informations, consultez Zones de liste. Pour obtenir une table des styles de zone de liste que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de zone de liste.
MDICLIENT	Désigne une fenêtre cliente MDI. Cette fenêtre reçoit des messages qui contrôlent les fenêtres enfants de l’application MDI. Les bits de style recommandés sont WS_CLIPCHILDREN et WS_CHILD. Spécifiez les styles WS_HSCROLL et WS_VSCROLL pour créer une fenêtre cliente MDI qui permet à l’utilisateur de faire défiler les fenêtres enfants MDI dans l’affichage. Pour plus d’informations, consultez Interface de document multiple.
Richedit	Désigne un contrôle Microsoft Rich Edit 1.0. Cette fenêtre permet à l’utilisateur d’afficher et de modifier du texte avec une mise en forme de caractères et de paragraphes, et peut inclure des objets COM (Component Object Model) incorporés. Pour plus d’informations, consultez Contrôles d’édition enrichis. Pour obtenir un tableau des styles de contrôle d’édition enrichi que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de contrôle d’édition enrichi.
RICHEDIT_CLASS	Désigne un contrôle Microsoft Rich Edit 2.0. Ces contrôles permettent à l’utilisateur d’afficher et de modifier du texte avec une mise en forme de caractères et de paragraphes, et peuvent inclure des objets COM incorporés. Pour plus d’informations, consultez Contrôles d’édition enrichis. Pour obtenir un tableau des styles de contrôle d’édition enrichi que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de contrôle d’édition enrichi.
SCROLLBAR	Désigne un rectangle qui contient une zone de défilement et a des flèches de direction aux deux extrémités. La barre de défilement envoie un message de notification à sa fenêtre parente chaque fois que l’utilisateur clique sur le contrôle. La fenêtre parente est chargée de mettre à jour la position de la zone de défilement, si nécessaire. Pour plus d’informations, consultez Barres de défilement. Pour obtenir une table des styles de contrôle de barre de défilement que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de contrôle de barre de défilement.
STATIQUE	Désigne un champ de texte simple, une zone ou un rectangle utilisé pour étiqueter, boxer ou séparer d’autres contrôles. Les contrôles statiques ne prennent aucune entrée et ne fournissent aucune sortie. Pour plus d’informations, consultez Contrôles statiques. Pour obtenir une table des styles de contrôle statiques que vous pouvez spécifier dans le paramètre dwStyle , consultez Styles de contrôle statiques.

La valeur WS_EX_NOACTIVATE pour dwExStyle empêche l’activation au premier plan par le système. Pour empêcher l’activation de la file d’attente lorsque l’utilisateur clique sur la fenêtre, vous devez traiter le message WM_MOUSEACTIVATE de manière appropriée. Pour mettre la fenêtre au premier plan ou l’activer par programmation, utilisez SetForegroundWindow ou SetActiveWindow. Le retour de FALSE à WM_NCACTIVATE empêche la fenêtre de perdre l’activation de la file d’attente. Toutefois, la valeur de retour est ignorée au moment de l’activation.

Avec WS_EX_COMPOSITED défini, tous les descendants d’une fenêtre obtiennent un ordre de peinture de bas en haut à l’aide d’une double mise en mémoire tampon. L’ordre de peinture de bas en haut permet à une fenêtre descendante d’avoir des effets de translucidité (alpha) et de transparence (touche de couleur), mais uniquement si la fenêtre descendante a également le WS_EX_TRANSPARENT bit défini. La double mise en mémoire tampon permet de peindre la fenêtre et ses descendants sans scintillement.

Exemple

L’exemple de code suivant illustre l’utilisation de 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);
    }

Notes

L’en-tête winuser.h définit CreateWindowEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll
Ensemble d’API	ext-ms-win-ntuser-window-l1-1-0 (introduit dans Windows 8)