Función CreateWindowExA (winuser.h)

Artículo
03/15/2023

Crea una ventana superpuesta, emergente o secundaria con un estilo de ventana extendida; De lo contrario, esta función es idéntica a la función CreateWindow. Para obtener más información sobre cómo crear una ventana y obtener descripciones completas de los demás parámetros de CreateWindowEx, vea CreateWindow.

Sintaxis

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

Parámetros

[in] dwExStyle

Tipo: DWORD de

Estilo de ventana extendida de la ventana que se va a crear. Para obtener una lista de los valores posibles, vea estilos de ventana extendidos.

[in, optional] lpClassName

Tipo: LPCTSTR de

Cadenaterminada en un null o un átomo de clase.

Si un cadena terminada en null, especifica el nombre de la clase de ventana. El nombre de clase puede ser cualquier nombre registrado con el RegisterClass o función registerClassEx, siempre que el módulo que registra la clase también sea el módulo que crea la ventana. El nombre de clase también puede ser cualquiera de los nombres predefinidos clase del sistema.

Si un átomo de clase creado por una llamada anterior a RegisterClass o RegisterClassEx, debe convertirse mediante la macro MAKEINTATOM. (El átomo debe estar en la palabra de orden bajo de lpClassName; la palabra de orden superior debe ser cero).

[in, optional] lpWindowName

Tipo: LPCTSTR de

Nombre de la ventana. Si el estilo de ventana especifica una barra de título, el título de la ventana al que apunta lpWindowName se muestra en la barra de título. Al usar createWindow para crear controles, como botones, casillas y controles estáticos, use lpWindowName para especificar el texto del control. Al crear un control estático con el estilo de SS_ICON, use lpWindowName para especificar el nombre o identificador del icono. Para especificar un identificador, use la sintaxis "#num".

[in] dwStyle

Tipo: DWORD de

Estilo de la ventana que se va a crear. Este parámetro puede ser una combinación de los valores de estilo de ventana , además de los estilos de control indicados en la sección Comentarios.

[in] X

Tipo: int

Posición horizontal inicial de la ventana. Para una ventana emergente o superpuesta, el parámetro x es la coordenada x inicial de la esquina superior izquierda de la ventana, en coordenadas de pantalla. Para una ventana secundaria, x es la coordenada x de la esquina superior izquierda de la ventana en relación con la esquina superior izquierda del área cliente de la ventana primaria. Si x se establece en CW_USEDEFAULT, el sistema selecciona la posición predeterminada para la esquina superior izquierda de la ventana y omite el parámetro y. CW_USEDEFAULT solo es válido para ventanas superpuestas; Si se especifica para una ventana emergente o secundaria, los parámetros x y y se establecen en cero.

[in] Y

Tipo: int

Posición vertical inicial de la ventana. Para una ventana emergente o superpuesta, el parámetro y es la coordenada y inicial de la esquina superior izquierda de la ventana, en coordenadas de pantalla. Para una ventana secundaria, y es la coordenada y inicial de la esquina superior izquierda de la ventana secundaria en relación con la esquina superior izquierda del área cliente de la ventana primaria. Para un cuadro de lista y es la coordenada y inicial de la esquina superior izquierda del área cliente del cuadro de lista en relación con la esquina superior izquierda del área cliente de la ventana primaria.

Si se crea una ventana superpuesta con el conjunto de bits de estilo WS_VISIBLE y el parámetro x se establece en CW_USEDEFAULT, el parámetro y determina cómo se muestra la ventana. Si el parámetro y es CW_USEDEFAULT, el administrador de ventanas llama a ShowWindow con la marca SW_SHOW después de crear la ventana. Si el parámetro y es otro valor, el administrador de ventanas llama a showWindow con ese valor como el parámetro nCmdShow .

[in] nWidth

Tipo: int

Ancho, en unidades de dispositivo, de la ventana. Para las ventanas superpuestas, nWidth es el ancho de la ventana, en coordenadas de pantalla o CW_USEDEFAULT. Si nWidth es CW_USEDEFAULT, el sistema selecciona un ancho y alto predeterminados para la ventana; el ancho predeterminado se extiende desde las coordenadas x iniciales hasta el borde derecho de la pantalla; el alto predeterminado se extiende desde la coordenada y inicial hasta la parte superior del área del icono. CW_USEDEFAULT solo es válido para ventanas superpuestas; Si se especifica CW_USEDEFAULT para una ventana emergente o secundaria, el nWidth y parámetro nHeight se establece en cero.

[in] nHeight

Tipo: int

Alto, en unidades de dispositivo, de la ventana. En el caso de las ventanas superpuestas, nHeight es el alto de la ventana, en coordenadas de pantalla. Si el parámetro nWidth está establecido en CW_USEDEFAULT, el sistema omite nHeight.

[in, optional] hWndParent

Tipo: HWND

Identificador de la ventana primaria o propietaria de la ventana que se va a crear. Para crear una ventana secundaria o una ventana de propiedad, proporcione un identificador de ventana válido. Este parámetro es opcional para las ventanas emergentes.

Para crear una ventana de solo mensaje , proporcione HWND_MESSAGE o un identificador a una ventana de solo mensaje existente.

[in, optional] hMenu

Tipo: HMENU de

Identificador de un menú o especifica un identificador de ventana secundaria, según el estilo de ventana. Para una ventana emergente o superpuesta, hMenu identifica el menú que se va a usar con la ventana; puede ser NULL si se va a usar el menú de clase. Para una ventana secundaria, hMenu especifica el identificador de ventana secundaria, un valor entero usado por un control de cuadro de diálogo para notificar a su elemento primario los eventos. La aplicación determina el identificador de ventana secundaria; debe ser único para todas las ventanas secundarias con la misma ventana primaria.

[in, optional] hInstance

Tipo: HINSTANCE

Identificador de la instancia del módulo que se va a asociar a la ventana.

[in, optional] lpParam

Tipo: LPVOID de

Puntero a un valor que se va a pasar a la ventana a través de la estructura CREATESTRUCT (miembro lpCreatePara ms) al que apunta el lParam parámetro del mensaje de WM_CREATE. Esta función envía este mensaje a la ventana creada antes de que se devuelva.

Si una aplicación llama a CreateWindow para crear una ventana de cliente MDI, lpParam debe apuntar a una estructura CLIENTCREATESTRUCT. Si una ventana de cliente MDI llama a CreateWindow para crear una ventana secundaria de MDI, lpParam debe apuntar a una estructura MDICREATESTRUCT . lpParam puede ser NULL si no se necesita ningún dato adicional.

Valor devuelto

Tipo: HWND

Si la función se ejecuta correctamente, el valor devuelto es un identificador de la nueva ventana.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Normalmente, esta función produce un error por uno de los siguientes motivos:

un valor de parámetro no válido
la clase del sistema se registró mediante un módulo diferente
El enlace de WH_CBT está instalado y devuelve un código de error.
si uno de los controles de la plantilla de diálogo no está registrado o se produce un error en el procedimiento de ventana de ventana WM_CREATE o WM_NCCREATE

Observaciones

La función createWindowEx envía WM_NCCREATE, WM_NCCALCSIZEy WM_CREATE mensajes a la ventana que se crea.

Si la ventana creada es una ventana secundaria, su posición predeterminada está en la parte inferior del orden Z. Si la ventana creada es una ventana de nivel superior, su posición predeterminada está en la parte superior del orden Z (pero debajo de todas las ventanas de nivel superior a menos que la ventana creada esté más arriba).

Para obtener información sobre cómo controlar si la barra de tareas muestra un botón para la ventana creada, vea Administrar botones de la barra de tareas.

Para obtener información sobre cómo quitar una ventana, consulte la función DestroyWindow.

Las siguientes clases de control predefinidas se pueden especificar en el parámetro lpClassName. Tenga en cuenta los estilos de control correspondientes que puede usar en el parámetro dwStyle.

Clase	Significado
BUTTON	Designa una pequeña ventana secundaria rectangular que representa un botón que el usuario puede hacer clic para activarlo o desactivarlo. Los controles de botón se pueden usar solos o en grupos, y se pueden etiquetar o aparecer sin texto. Los controles de botón suelen cambiar la apariencia cuando el usuario hace clic en ellos. Para obtener más información, consulte Botones. Para obtener una tabla de los estilos de botón que puede especificar en el parámetro dwStyle, consulte Estilos de botón.
COMBOBOX	Designa un control que consta de un cuadro de lista y un campo de selección similar a un control de edición. Al usar este estilo, una aplicación debe mostrar el cuadro de lista en todo momento o habilitar un cuadro de lista desplegable. Si el cuadro de lista está visible, al escribir caracteres en el campo de selección se resalta la primera entrada del cuadro de lista que coincide con los caracteres tipados. Por el contrario, al seleccionar un elemento en el cuadro de lista se muestra el texto seleccionado en el campo de selección. Para obtener más información, vea cuadros combinados. Para obtener una tabla de los estilos de cuadro combinado que puede especificar en el parámetro dwStyle, consulte Estilos de cuadro combinado.
EDITAR	Designa una ventana secundaria rectangular en la que el usuario puede escribir texto desde el teclado. El usuario selecciona el control y le da el foco del teclado haciendo clic en él o moviéndolo presionando la tecla TAB. El usuario puede escribir texto cuando el control de edición muestra un símbolo de intercalación parpadeante; use el mouse para mover el cursor, seleccionar caracteres que se van a reemplazar o colocar el cursor para insertar caracteres; o use la clave para eliminar caracteres. Para obtener más información, vea Editar controles. Para obtener una tabla de los estilos de control de edición que puede especificar en el parámetro dwStyle, consulte Editar estilos de control.
LISTBOX de	Designa una lista de cadenas de caracteres. Especifique este control cada vez que una aplicación debe presentar una lista de nombres, como nombres de archivo, desde los que el usuario puede elegir. El usuario puede seleccionar una cadena haciendo clic en ella. Se resalta una cadena seleccionada y se pasa un mensaje de notificación a la ventana primaria. Para obtener más información, consulte cuadros de lista. Para obtener una tabla de los estilos de cuadro de lista que puede especificar en el parámetro dwStyle de , consulte Estilos de cuadro de lista.
MDICLIENT	Designa una ventana de cliente MDI. Esta ventana recibe mensajes que controlan las ventanas secundarias de la aplicación MDI. Los bits de estilo recomendados son WS_CLIPCHILDREN y WS_CHILD. Especifique los estilos WS_HSCROLL y WS_VSCROLL para crear una ventana de cliente MDI que permita al usuario desplazar las ventanas secundarias de MDI a la vista. Para obtener más información, vea de la interfaz de varios documentos.
RichEdit	Designa un control Microsoft Rich Edit 1.0. Esta ventana permite al usuario ver y editar texto con formato de caracteres y párrafos, y puede incluir objetos de modelo de objetos componentes incrustados (COM). Para obtener más información, vea Controles de edición enriquecidos. Para obtener una tabla de los estilos de control de edición enriquecidos, puede especificar en el parámetro dwStyle, consulte estilos de control de edición enriquecidos.
RICHEDIT_CLASS	Designa un control Microsoft Rich Edit 2.0. Estos controles permiten al usuario ver y editar texto con formato de caracteres y párrafos, y pueden incluir objetos COM incrustados. Para obtener más información, vea Controles de edición enriquecidos. Para obtener una tabla de los estilos de control de edición enriquecidos, puede especificar en el parámetro dwStyle, consulte estilos de control de edición enriquecidos.
SCROLLBAR	Designa un rectángulo que contiene un cuadro de desplazamiento y tiene flechas de dirección en ambos extremos. La barra de desplazamiento envía un mensaje de notificación a su ventana primaria cada vez que el usuario hace clic en el control. La ventana primaria es responsable de actualizar la posición del cuadro de desplazamiento, si es necesario. Para obtener más información, vea barras de desplazamiento. Para obtener una tabla de los estilos de control de barra de desplazamiento que puede especificar en el parámetro dwStyle, consulte Estilos de control de barra de desplazamiento.
static	Designa un campo de texto simple, un cuadro o un rectángulo que se usa para etiquetar, cuadro o separar otros controles. Los controles estáticos no toman ninguna entrada y no proporcionan ninguna salida. Para obtener más información, vea controles estáticos. Para obtener una tabla de los estilos de control estáticos que puede especificar en el parámetro dwStyle de , consulte estilos de control estáticos.

El valor WS_EX_NOACTIVATE de dwExStyle impide la activación en primer plano por parte del sistema. Para evitar la activación de cola cuando el usuario hace clic en la ventana, debe procesar el mensaje WM_MOUSEACTIVATE correctamente. Para poner la ventana en primer plano o activarla mediante programación, use SetForegroundWindow o SetActiveWindow. Devolver FALSE a WM_NCACTIVATE impide que la ventana pierda la activación de la cola. Sin embargo, el valor devuelto se omite en el momento de la activación.

Con WS_EX_COMPOSITED establecido, todos los descendientes de una ventana obtienen un orden de pintura inferior a superior mediante el almacenamiento en búfer doble. El orden de pintura inferior a superior permite que una ventana descendiente tenga efectos de translucencia (alfa) y transparencia (tecla de color), pero solo si la ventana descendiente también tiene el WS_EX_TRANSPARENT bit establecido. El almacenamiento en búfer doble permite pintar la ventana y sus descendientes sin parpadear.

Ejemplo

En el código de ejemplo siguiente se muestra el uso 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);
    }

Nota

El encabezado winuser.h define CreateWindowEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winuser.h (incluya Windows.h)
biblioteca de	User32.lib
DLL de	User32.dll
conjunto de API de	ext-ms-win-ntuser-window-l1-1-0 (introducido en Windows 8)