Funzione CreateWindowExA (winuser.h)

Articolo
02/01/2024

Crea una finestra sovrapposta, popup o figlio con uno stile di finestra estesa; in caso contrario, questa funzione è identica alla funzione CreateWindow . Per altre informazioni sulla creazione di una finestra e per le descrizioni complete degli altri parametri di CreateWindowEx, vedere CreateWindowEx.

Sintassi

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

Parametri

[in] dwExStyle

Tipo: DWORD

Stile della finestra estesa della finestra creata. Per un elenco di valori possibili, vedere Stili finestra estesi.

[in, optional] lpClassName

Tipo: LPCTSTR

Stringa con terminazione null o atom di classe creata da una chiamata precedente alla funzione RegisterClass o RegisterClassEx . L'atomo deve essere nella parola a basso ordine di lpClassName; la parola di ordine elevato deve essere zero. Se lpClassName è una stringa, specifica il nome della classe di finestra. Il nome della classe può essere qualsiasi nome registrato con RegisterClass o RegisterClassEx, purché il modulo che registra la classe sia anche il modulo che crea la finestra. Il nome della classe può anche essere uno dei nomi predefiniti della classe di sistema .

[in, optional] lpWindowName

Tipo: LPCTSTR

Nome della finestra. Se lo stile della finestra specifica una barra del titolo, il titolo della finestra a cui punta lpWindowName viene visualizzato nella barra del titolo. Quando si usa CreateWindow per creare controlli, ad esempio pulsanti, caselle di controllo e controlli statici, usare lpWindowName per specificare il testo del controllo. Quando si crea un controllo statico con lo stile SS_ICON , usare lpWindowName per specificare il nome o l'identificatore dell'icona. Per specificare un identificatore, usare la sintassi "#num".

[in] dwStyle

Tipo: DWORD

Stile della finestra creata. Questo parametro può essere una combinazione dei valori dello stile della finestra, oltre agli stili di controllo indicati nella sezione Osservazioni.

[in] X

Tipo: int

Posizione orizzontale iniziale della finestra. Per una finestra sovrapposta o popup, il parametro x è la coordinata x iniziale dell'angolo superiore sinistro della finestra, nelle coordinate dello schermo. Per una finestra figlio, x è la coordinata x dell'angolo superiore sinistro della finestra rispetto all'angolo superiore sinistro dell'area client della finestra padre. Se x è impostato su CW_USEDEFAULT, il sistema seleziona la posizione predefinita per l'angolo superiore sinistro della finestra e ignora il parametro y . CW_USEDEFAULT è valido solo per le finestre sovrapposte; se viene specificato per una finestra popup o figlio, i parametri x e y sono impostati su zero.

[in] Y

Tipo: int

Posizione verticale iniziale della finestra. Per una finestra sovrapposta o popup, il parametro y è la coordinata y iniziale dell'angolo superiore sinistro della finestra, nelle coordinate dello schermo. Per una finestra figlio, y è la coordinata y iniziale dell'angolo superiore sinistro della finestra figlio rispetto all'angolo superiore sinistro dell'area client della finestra padre. Per una casella di riepilogo y è la coordinata iniziale dell'angolo superiore sinistro dell'area client della casella di riepilogo rispetto all'angolo superiore sinistro dell'area client della finestra padre.

Se viene creata una finestra sovrapposta con il set di bit di stile WS_VISIBLE e il parametro x è impostato su CW_USEDEFAULT, il parametro y determina la modalità di visualizzazione della finestra. Se il parametro y è CW_USEDEFAULT, la gestione finestre chiama ShowWindow con il flag SW_SHOW dopo la creazione della finestra. Se il parametro y è un altro valore, la gestione finestre chiama ShowWindow con tale valore come parametro nCmdShow .

[in] nWidth

Tipo: int

Larghezza, in unità dispositivo, della finestra. Per le finestre sovrapposte, nWidth è la larghezza della finestra, nelle coordinate dello schermo o CW_USEDEFAULT. Se nWidthè CW_USEDEFAULT, il sistema seleziona una larghezza e un'altezza predefinita per la finestra; la larghezza predefinita si estende dalle coordinate x iniziali al bordo destro dello schermo; l'altezza predefinita si estende dalla coordinata y iniziale alla parte superiore dell'area dell'icona. CW_USEDEFAULT è valido solo per le finestre sovrapposte; se CW_USEDEFAULT viene specificato per una finestra popup o figlio, il parametro nWidth e nHeight sono impostati su zero.

[in] nHeight

Tipo: int

Altezza, in unità dispositivo, della finestra. Per le finestre sovrapposte, nHeight è l'altezza della finestra, nelle coordinate dello schermo. Se il parametro nWidth è impostato su CW_USEDEFAULT, il sistema ignora nHeight.

[in, optional] hWndParent

Tipo: HWND

Handle alla finestra padre o proprietario della finestra creata. Per creare una finestra figlio o una finestra di proprietà, specificare un handle di finestra valido. Questo parametro è facoltativo per le finestre popup.

Per creare una finestra solo messaggio, specificare HWND_MESSAGE o un handle a una finestra di solo messaggio esistente.

[in, optional] hMenu

Tipo: HMENU

Un handle a un menu o specifica un identificatore di finestra figlio, a seconda dello stile della finestra. Per una finestra sovrapposta o popup, hMenu identifica il menu da usare con la finestra; può essere NULL se il menu della classe deve essere usato. Per una finestra figlio, hMenu specifica l'identificatore della finestra figlio, un valore intero utilizzato da un controllo finestra di dialogo per notificare agli eventi padre. L'applicazione determina l'identificatore della finestra figlio; deve essere univoco per tutte le finestre figlio con la stessa finestra padre.

[in, optional] hInstance

Tipo: HINSTANCE

Handle per l'istanza del modulo da associare alla finestra.

[in, optional] lpParam

Tipo: LPVOID

Puntatore a un valore da passare alla finestra tramite la struttura CREATESTRUCT (membro lpCreateParams ) a cui fa riferimento il param lParam del messaggio di WM_CREATE . Questo messaggio viene inviato alla finestra creata da questa funzione prima di restituire.

Se un'applicazione chiama CreateWindow per creare una finestra client MDI, lpParam deve puntare a una struttura CLIENTCREATESTRUCT . Se una finestra client MDI chiama CreateWindow per creare una finestra figlio MDI, lpParam deve puntare a una struttura MDICREATESTRUCT . lpParam può essere NULL se non sono necessari dati aggiuntivi.

Valore restituito

Tipo: HWND

Se la funzione ha esito positivo, il valore restituito è un handle per la nuova finestra.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Questa funzione ha in genere esito negativo per uno dei motivi seguenti:

valore di parametro non valido
la classe di sistema è stata registrata da un modulo diverso
L'hook WH_CBT è installato e restituisce un codice di errore
se uno dei controlli nel modello di dialogo non è registrato o la relativa procedura finestra non riesce WM_CREATE o WM_NCCREATE

Commenti

La funzione CreateWindowEx invia WM_NCCREATE, WM_NCCALCSIZE e WM_CREATE messaggi alla finestra creata.

Se la finestra creata è una finestra figlio, la posizione predefinita si trova nella parte inferiore dell'ordine Z. Se la finestra creata è una finestra di primo livello, la sua posizione predefinita si trova nella parte superiore dell'ordine Z (ma sotto tutte le finestre più in alto a meno che la finestra creata non sia più in alto).

Per informazioni sul controllo se la barra delle applicazioni visualizza un pulsante per la finestra creata, vedere Gestione dei pulsanti della barra delle applicazioni.

Per informazioni sulla rimozione di una finestra, vedere la funzione DestroyWindow .

Le classi di controllo predefinite seguenti possono essere specificate nel parametro lpClassName . Si notino gli stili di controllo corrispondenti che è possibile usare nel parametro dwStyle .

Classe	Significato
PULSANTE	Designa una piccola finestra figlio rettangolare che rappresenta un pulsante che l'utente può fare clic per attivarlo o disattivarlo. I controlli pulsante possono essere usati solo o in gruppi e possono essere etichettati o visualizzati senza testo. I controlli pulsante cambiano in genere l'aspetto quando l'utente li fa clic. Per altre informazioni, vedere Pulsanti. Per una tabella degli stili del pulsante che è possibile specificare nel parametro dwStyle , vedere Stili pulsante.
COMBOBOX	Definisce un controllo costituito da una casella di riepilogo e da un campo di selezione simile a un controllo di modifica. Quando si usa questo stile, un'applicazione deve visualizzare la casella di riepilogo in qualsiasi momento o abilitare una casella di riepilogo a discesa. Se la casella di riepilogo è visibile, digitando i caratteri nel campo di selezione viene evidenziata la prima voce della casella di riepilogo corrispondente ai caratteri digitati. Al contrario, selezionando un elemento nella casella di riepilogo viene visualizzato il testo selezionato nel campo di selezione. Per altre informazioni, vedere Caselle combinate. Per una tabella degli stili della casella combinata, è possibile specificare nel parametro dwStyle , vedere Stili casella combinata.
MODIFICA	Definisce una finestra figlio rettangolare in cui l'utente può digitare testo dalla tastiera. L'utente seleziona il controllo e lo dà lo stato attivo della tastiera facendo clic su di esso o spostandolo premendo il tasto TAB. L'utente può digitare testo quando il controllo di modifica visualizza una caret lampeggiante; usare il mouse per spostare il cursore, selezionare i caratteri da sostituire o posizionare il cursore per l'inserimento di caratteri; oppure usare la chiave per eliminare i caratteri. Per altre informazioni, vedere Modifica controlli. Per una tabella degli stili di controllo di modifica che è possibile specificare nel parametro dwStyle , vedere Modifica stili di controllo.
LISTBOX	Definisce un elenco di stringhe di caratteri. Specificare questo controllo ogni volta che un'applicazione deve presentare un elenco di nomi, ad esempio nomi file, da cui l'utente può scegliere. L'utente può selezionare una stringa facendo clic su di essa. Una stringa selezionata è evidenziata e viene passato un messaggio di notifica alla finestra padre. Per altre informazioni, vedere Caselle di riepilogo. Per una tabella degli stili della casella di riepilogo è possibile specificare nel parametro dwStyle , vedere Stili casella di riepilogo.
MDICLIENT	Definisce una finestra client MDI. Questa finestra riceve messaggi che controllano le finestre figlio dell'applicazione MDI. I bit di stile consigliati sono WS_CLIPCHILDREN e WS_CHILD. Specificare gli stili WS_HSCROLL e WS_VSCROLL per creare una finestra client MDI che consente all'utente di scorrere le finestre figlio MDI nella visualizzazione. Per altre informazioni, vedere Più interfacce documento.
RichEdit	Designa un controllo Microsoft Rich Edit 1.0. Questa finestra consente all'utente di visualizzare e modificare il testo con la formattazione del carattere e del paragrafo e può includere oggetti Component Object Model (COM) incorporati. Per altre informazioni, vedere Controlli di modifica avanzati. Per una tabella degli stili di controllo di modifica avanzati che è possibile specificare nel parametro dwStyle, vedere Rich Edit Control Styles.For a table of the rich edit control styles you can specific in the dwStyle parameter, see Rich Edit Control Styles.
RICHEDIT_CLASS	Designa un controllo Microsoft Rich Edit 2.0. Questo controllo consente all'utente di visualizzare e modificare il testo con la formattazione del carattere e del paragrafo e può includere oggetti COM incorporati. Per altre informazioni, vedere Controlli di modifica avanzati. Per una tabella degli stili di controllo di modifica avanzati che è possibile specificare nel parametro dwStyle, vedere Rich Edit Control Styles.For a table of the rich edit control styles you can specific in the dwStyle parameter, see Rich Edit Control Styles.
SCROLLBAR	Designa un rettangolo che contiene una casella di scorrimento e ha frecce di direzione a entrambe le estremità. La barra di scorrimento invia un messaggio di notifica alla finestra padre ogni volta che l'utente fa clic sul controllo. La finestra padre è responsabile dell'aggiornamento della posizione della casella di scorrimento, se necessario. Per altre informazioni, vedere Barre di scorrimento. Per una tabella degli stili di controllo della barra di scorrimento che è possibile specificare nel parametro dwStyle , vedere Stili di controllo barra di scorrimento.
STATICO	Definisce un campo di testo semplice, una casella o un rettangolo usato per etichettare, casella o separare altri controlli. I controlli statici non accettano alcun input e non forniscono alcun output. Per altre informazioni, vedere Controlli statici. Per una tabella degli stili di controllo statici è possibile specificare nel parametro dwStyle , vedere Stili di controllo statico.

Il valore WS_EX_NOACTIVATE per dwExStyle impedisce l'attivazione in primo piano dal sistema. Per impedire l'attivazione della coda quando l'utente fa clic sulla finestra, è necessario elaborare il messaggio di WM_MOUSEACTIVATE in modo appropriato. Per portare la finestra in primo piano o per attivarla a livello di codice, usare SetForegroundWindow o SetActiveWindow. La restituzione di FALSE a WM_NCACTIVATE impedisce alla finestra di perdere l'attivazione della coda. Tuttavia, il valore restituito viene ignorato in fase di attivazione.

Con WS_EX_COMPOSITED impostato, tutti i discendenti di una finestra ottengono l'ordine di pittura inferiore a superiore usando il buffer double-buffer. L'ordine di pittura in basso a alto consente a una finestra discendente di avere effetti di translucenza (alfa) e trasparenza (chiave colore), ma solo se la finestra discendente ha anche il set di bit WS_EX_TRANSPARENT . Il buffer doppio consente di disegnare la finestra e i relativi discendenti senza flicker.

Esempio

Il codice di esempio seguente illustra l'uso di 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);
    }

Nota

L'intestazione winuser.h definisce CreateWindowEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-window-l1-1-0 (introdotto in Windows 8)