Información general sobre ventanas para WinUI y Windows SDK de aplicaciones

La funcionalidad de ventanas en una aplicación WinUI se proporciona mediante una combinación de la clase XAML Window y la AppWindow clase , ambas basadas en el modelo HWND de Win32.

La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 3. Obtén la aplicación desde la Microsoft Store o consigue el código fuente en GitHub

XAML Window

En la aplicación, el objeto window es una instancia de la clase Microsoft.UI.Xaml.Window (o una clase derivada) que representa la ventana en el código del programa. Creas esto directamente con una llamada al constructor. Xaml Window es donde adjuntas el contenido de la aplicación y administras el ciclo de vida de las ventanas de la aplicación.

HWND

El sistema operativo crea la ventana de aplicación y se representa mediante un objeto de ventana Win32. Es un contenedor administrado por el sistema en el que se hospeda el contenido y representa la entidad con la que interactúan los usuarios cuando cambian el tamaño y mueven la aplicación en pantalla. (Consulta Acerca de Windows en la documentación de Win32 para obtener más información).

Una vez que Windows crea la ventana de la aplicación, la función de creación devuelve un window handle identificador (HWND) que identifica de forma única la ventana. El tipo de datos de window handle es HWND, aunque aparece en C# como intPtr. Es un identificador opaco de una estructura de datos interna Windows que corresponde a una ventana dibujada por el sistema operativo y consume recursos del sistema cuando está presente.

El HWND se crea después del objeto XAML Window, normalmente cuando se llama al método Window.Activate.

AppWindow

El Windows SDK de aplicaciones proporciona funcionalidad de ventanas adicional a través de la clase Microsoft.UI.Windowing.AppWindow AppWindow representa una abstracción de alto nivel del HWND. Hay una asignación de 1:1 entre un AppWindow y un HWND de nivel superior en su aplicación. AppWindow y sus clases relacionadas proporcionan API que te permiten administrar muchos aspectos de las ventanas de nivel superior de la aplicación sin necesidad de acceder directamente al HWND.

La duración de un AppWindow objeto y un HWND es la misma: AppWindow está disponible inmediatamente después de crear la ventana; y se destruye cuando se cierra la ventana.

Diagrama de API de ventanas

En este diagrama se muestra la relación entre las clases y las API que se usan para administrar ventanas en la aplicación y qué clases son responsables de cada parte de la administración de ventanas. En algunos casos, como ExtendsContentIntoTitleBar, la API es miembro de AppWindow para que esté disponible para otros marcos de interfaz de usuario, pero también se expone en la Window clase para mayor comodidad. El diagrama no es completo, pero muestra las API más usadas.

Window/AppWindow Comparación de API

Si usas XAML de WinUI 3 como marco de interfaz de usuario de tu aplicación, tanto las API Window como las API AppWindow están disponibles para ti. Windows A partir de App SDK 1.4, puedes usar la Windowpropiedad .AppWindow para obtener un AppWindow objeto de una ventana XAML existente. Con este AppWindow objeto tiene acceso a las API de administración de ventanas adicionales.

Gestión del ciclo de vida

Al crear un nuevo proyecto de WinUI en Visual Studio, la plantilla de proyecto proporciona una MainWindow clase automáticamente, que es una subclase de Window. Si la aplicación solo necesita una ventana, esto es todo lo que necesitas. Para obtener información sobre cómo crear y administrar ventanas adicionales y por qué es posible que quiera, consulte Mostrar varias ventanas para la aplicación.

La AppWindow clase tiene API para crear y destruir una nueva ventana; sin embargo, para una aplicación WinUI, no lo hará en la práctica porque no hay ninguna API para adjuntar contenido a la ventana que cree. En su lugar, obtienes una instancia de AppWindow que crea el sistema y se asocia con XAML Window y HWND. En WinUI 1.4 y versiones posteriores, puede usar la propiedad Window.AppWindow para obtener la instancia de AppWindow. En otros casos, puede usar el método estático AppWindow.GetFromWindowId para obtener una AppWindow instancia. Consulta Administrar ventanas de aplicaciones para obtener más información.

Content

.Window La propiedad Content es donde se adjunta el contenido de la aplicación a la ventana que la muestra. Puedes hacerlo en XAML o en código.

Título, icono y barra de título

Puedes modificar la barra de título de la aplicación en distintos grados; establecer el título y el icono, cambiar los colores o reemplazar completamente la barra de título por contenido de la aplicación personalizada.

Para obtener información sobre el uso de api de barra de título, incluidos ejemplos de código, consulte Personalización de la barra de título.

Tamaño y posición

Utilizas la propiedad .Bounds y el evento SizeChanged para gestionar elementos en la interfaz de usuario de la aplicación, como reorganizar elementos cuando cambia el tamaño de la ventana. XAML usa effective pixels (epx), no píxeles físicos reales. Effective pixels son una unidad virtual de medida y se usan para expresar dimensiones de diseño y espaciado, independientemente de la densidad de la pantalla.

AppWindowPor otro lado, usa el Window sistema de coordenadas, donde la unidad básica de medida es píxeles de dispositivo físico. Se usan las AppWindow APIs para las acciones de ventana, como cambiar el tamaño de la ventana o moverla en relación con algo más en la pantalla.

En algunos casos, es posible que tenga que usar medidas de una clase en otra, en cuyo caso deberá convertir entre effective pixels y píxeles de dispositivo. Por ejemplo, si establece regiones de arrastre en una barra de título personalizada, deberá convertir medidas. Para obtener un ejemplo de cómo usar XamlRoot.RasterizationScale para convertir medidas, consulta la sección de contenido interactivo del artículo personalización de la barra de título.

Apariencia y comportamiento

Las API XAML Window suelen ser responsables de la apariencia del contenido de la aplicación, como el fondo. Para obtener más información sobre SystemBackdrop, consulta Aplicar materiales de Mica o Acrílico.

Las APIs son responsables de la parte no cliente de la ventana y de la interacción de la aplicación con el sistema operativo.

Seguimiento de la ventana actual

Aunque la Current propiedad no se admite en aplicaciones WinUI, es posible que tenga que acceder a las Window APIs desde otros lugares de la aplicación. Por ejemplo, es posible que tenga que obtener los límites de Window o controlar el evento Window.SizeChanged desde el código de un Page. En este caso, puede proporcionar acceso al Window de manera similar a la propiedad Current mediante una propiedad estática pública en su clase App.

Para ello, modifique la Window declaración en la clase App como se muestra aquí.

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

A continuación, para acceder a Window desde otros lugares de la aplicación, use App.Window, de la siguiente manera:

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

Temas relacionados

• Administración de ventanas de aplicaciones
• Migración de la funcionalidad basada en ventanas
• Llamada a las API de interoperabilidad desde una aplicación con una versión de .NET
• Recuperar un window handle (HWND)
• Ejemplo de la galería de ventanas