Información general sobre ventanas para WinUI 3 y el SDK de Apps

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

Icono de la galería de WinUI 3

La aplicación Galería de WinUI 3 incluye ejemplos interactivos de características y controles winUI. Obtenga la aplicación del Microsoft Store o examine el código fuente en GitHub.

XAML

En la aplicación, el objeto window es una instancia de la clase Microsoft.UI.Xaml. (o una clase derivada) que representa la ventana en el código del programa. Creas esto directamente con una llamada al constructor. Xaml 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 en la documentación de Win32 para obtener más información).

Una vez que crea la ventana de la aplicación, la función de creación devuelve un identificador () que identifica de forma única la ventana. El tipo de datos de es HWND, aunque aparece en C# como intPtr. Es un identificador opaco de una estructura de datos interna 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 , normalmente cuando se llama al método .Activate.

AppWindow

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

La duración de un objeto y un HWND es la misma: 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 , la API es miembro de para que esté disponible para otros marcos de interfaz de usuario, pero también se expone en la clase para mayor comodidad. El diagrama no es completo, pero muestra las API más usadas.

Diagrama de ventanas win u i

/ Comparación de API

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

Gestión del ciclo de vida

Al crear un nuevo proyecto WinUI en Visual Studio, la plantilla del proyecto proporciona una clase MainWindow para ti, la cual 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 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 que crea el sistema y se asocia con XAML y HWND. En WinUI 1.4 y versiones posteriores, puede usar la propiedad . para obtener la instancia de . En otros casos, puede usar el método estático .GetFromWindowId para obtener una instancia. Consulta Administrar ventanas de aplicaciones para obtener más información.

Content

. 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 (epx), no píxeles físicos reales. son una unidad virtual de medida y se usan para expresar dimensiones de diseño y espaciado, independientemente de la densidad de la pantalla.

Por otro lado, usa el sistema de coordenadas, donde la unidad básica de medida es píxeles de dispositivo físico. Se usan las 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 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 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 propiedad Current no se admite en aplicaciones WinUI, es posible que tenga que acceder a las API de Window desde otros lugares en su aplicación. Por ejemplo, es posible que tenga que obtener los límites de o controlar el evento .SizeChanged desde el código de un Page. En este caso, puede proporcionar acceso a la Window de forma similar a la propiedad Current mediante una propiedad estática pública en su clase App.

Para hacerlo, modifique la declaración Window 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 al 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 de manejo de ventanas
• Llamar a las API de interoperabilidad desde una aplicación .NET
• Recuperar un (HWND)
• Ejemplo de la galería de ventanas