CreateWindowExW, fonction (winuser.h)

Article
03/15/2023

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

Syntaxe

HWND CreateWindowExW(
  [in]           DWORD     dwExStyle,
  [in, optional] LPCWSTR   lpClassName,
  [in, optional] LPCWSTR   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

Une chaîne null-terminated string ou un atome de classe.

Si une chaîne null-terminated, elle spécifie le nom de la classe de fenêtre. Le nom de classe peut être n’importe quel nom inscrit auprès du RegisterClass ou RegisterClassEx, à condition que le module qui inscrit la classe soit également le module qui crée la fenêtre. Le nom de classe peut également être l’un des noms de classe système prédéfinis.

Si un atome de classe créé par un appel précédent à RegisterClass ou RegisterClassEx, il doit être converti à l’aide de la macro MAKEINTATOM. (L’atome doit être dans le mot de bas ordre de lpClassName; le mot de haut ordre doit être égal à zéro.)

[in, optional] lpWindowName

Type : LPCTSTR

Nom de la fenêtre. Si le style de 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 cases à cocher et des contrôles statiques, utilisez lpWindowName pour spécifier le texte du contrôle. Lorsque vous créez 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 les 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, dans les coordonnées de l’écran. Pour une fenêtre enfant, x est la coordonnée x du coin supérieur gauche de la fenêtre par rapport au coin 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 du coin supérieur gauche de la fenêtre et ignore le paramètre y. CW_USEDEFAULT est valide uniquement pour les fenêtres superposées ; s’il est spécifié 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, dans les coordonnées de l’é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 au coin supérieur gauche de la zone cliente de la fenêtre parente.

Si une fenêtre superposée est créée avec le jeu de bits de style WS_VISIBLE et que le paramètre x est défini sur 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être appelle ShowWindow avec l’indicateur de SW_SHOW une fois la fenêtre créée. Si le paramètre y est une autre valeur, le gestionnaire de fenêtre 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 superposées, 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 au haut de la zone d’icône. CW_USEDEFAULT est valide uniquement pour les fenêtres superposées ; si CW_USEDEFAULT est spécifié pour une fenêtre contextuelle ou enfant, le nWidth et paramètre 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 vers la fenêtre parent 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 message uniquement, fournissez HWND_MESSAGE ou un handle à une fenêtre de message uniquement existante.

[in, optional] hMenu

Type : HMENU

Handle vers un menu ou spécifie un identificateur de fenêtre enfant, selon le style de fenêtre. Pour une fenêtre contextuelle ou superposée, hMenu identifie le menu à utiliser avec la fenêtre ; il 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, 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 ; il doit être unique pour toutes les fenêtres enfants avec la même fenêtre parente.

[in, optional] hInstance

Type : HINSTANCE

Handle pour l’instance du module à associer à la fenêtre.

[in, optional] lpParam

Type : LPVOID

Pointeur vers une valeur à transmettre à la fenêtre via la structure CREATESTRUCT (lpCreateParams membre) pointée par l'lParam param du message WM_CREATE. Ce message est envoyé à la fenêtre créée par cette fonction avant de retourner.

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 être NULL si aucune donnée supplémentaire n’est nécessaire.

Valeur de retour

Type : HWND

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

Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, 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 WH_CBT hook 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 de fenêtre échoue WM_CREATE ou WM_NCCREATE

Remarques

La fonction CreateWindowEx envoie WM_NCCREATE, WM_NCCALCSIZEet WM_CREATE messages à 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 Z. 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 Z (mais sous toutes les fenêtres les plus hauts, 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 pour la fenêtre créée, consultez Gestion des boutons de 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
BUTTON	Désigne une petite fenêtre enfant rectangulaire qui représente un bouton que l’utilisateur peut cliquer pour l’activer ou la désactiver. Les contrôles de bouton peuvent être utilisés seul ou dans des groupes, et ils peuvent être étiquetés ou affichés sans texte. Les contrôles de bouton changent généralement l’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 modifiable.
EDIT	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 le déplaçant en appuyant sur la touche TAB. L’utilisateur peut taper du texte lorsque le contrôle d’édition affiche une touche flashing ; 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 un tableau des styles de contrôle d’édition 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 transmis à la fenêtre parente. Pour plus d’informations, consultez zones de liste. Pour obtenir un tableau 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 en mode affichage. Pour plus d’informations, consultez plusieursd’interface de document.
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ère et de paragraphe, et peut inclure des objets COM (Component Object Model) incorporés. Pour plus d’informations, consultez rich Edit Controls. Pour obtenir un tableau des styles de contrôle d’édition enrichis que vous pouvez spécifier dans le paramètre dwStyle, consultez Rich Edit Control Styles.
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ère et de paragraphe, et peut inclure des objets COM incorporés. Pour plus d’informations, consultez rich Edit Controls. Pour obtenir un tableau des styles de contrôle d’édition enrichis que vous pouvez spécifier dans le paramètre dwStyle, consultez Rich Edit Control Styles.
barre de défilement	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 un tableau 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.
static	Désigne un champ de texte simple, une zone ou un rectangle utilisé pour étiqueter, zone ou séparer d’autres contrôles. Les contrôles statiques ne prennent pas d’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 placer la fenêtre au premier plan ou l’activer par programme, utilisez SetForegroundWindow ou SetActiveWindow. Retourner faux à 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 inférieur à supérieur à l’aide de la mise en mémoire tampon double. L’ordre de peinture inférieur à haut permet à une fenêtre descendante d’avoir des effets de transparence (alpha) et de transparence (clé de couleur), mais uniquement si la fenêtre descendante a également le jeu de bits WS_EX_TRANSPARENT. La double mise en mémoire tampon permet à la fenêtre et à ses descendants d’être peints 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);
    }

Note

L’en-tête winuser.h définit CreateWindowEx comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winuser.h (include Windows.h)
bibliothèque	User32.lib
DLL	User32.dll
ensemble d’API	ext-ms-win-ntuser-window-l1-1-0 (introduit dans Windows 8)