Administración de ventanas de aplicaciones (SDK de Aplicaciones para Windows)

  • Artículo

Esta tema contiene una sección de ejemplo de código.

El SDK de Aplicaciones para Windows proporciona la clase Microsoft.UI.Windowing.AppWindow fácil de usar. AppWindow es independiente del marco y está disponible para todas las aplicaciones de Windows, como Win32, WPF y WinForms. Puedes contrastar la naturaleza independiente del marco de trabajo de AppWindow a Microsoft.UI.Xaml.Window, que es la clase de ventana específica para el marco WinUI 3. AppWindow también es una evolución de la Plataforma universal de Windows (UWP) Windows.UI.WindowManagement.AppWindow.

La versión del SDK de Aplicaciones para Windows de Microsoft.UI.Windowing.AppWindow no se basa en patrones asincrónicos y proporciona comentarios inmediatos a la aplicación sobre si las llamadas API se han realizado correctamente.

Consulta también Instalación de herramientas para el SDK de Aplicaciones para Windows, Creación del primer proyecto de WinUI 3 y Usar SDK de Aplicaciones para Windows en un proyecto existente.

La clase AppWindow

Microsoft.UI.Windowing.AppWindow es una API de ventanas de alto nivel que permite escenarios de ventanas fáciles de usar. AppWindow se integra bien con la interfaz de usuario y la experiencia de usuario de Windows y con otras aplicaciones.

AppWindow representa una abstracción de alto nivel de un contenedor administrado por el sistema del contenido de una aplicación. Este es el contenedor en el que se hospeda el contenido y representa la entidad con la que los usuarios interactúan cuando cambian el tamaño y mueven la aplicación en la pantalla. Si estás familiarizado con Win32, la ventana de aplicación se puede ver como una abstracción de alto nivel de HWND. Si estás familiarizado con UWP, la ventana de aplicación se puede ver como un reemplazo de CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Para la versión de SDK de Aplicaciones para Windows de Microsoft.UI.Windowing.AppWindow solo se admiten HWND de nivel superior. En la aplicación, hay una asignación 1:1 entre una AppWindow y un HWND de nivel superior.

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

La clase AppWindowPresenter y las subclases

Cada AppWindow tiene un AppWindowPresenter (moderador) aplicada. Si eres un desarrollador de UWP que ha trabajado con Windows.UI.WindowManagement.AppWindow, esto te resultará familiar, aunque haya alguna diferencia en cuanto a funcionalidad y comportamiento. Consulta también Migración de la funcionalidad basada en ventanas.

Como nuevo concepto para el modelo de aplicación Win32, un moderador no es igual, pero sí similar, a una combinación de estilos y estado de ventana. Algunos moderadores también tienen comportamientos de interfaz de usuario y experiencia de usuario definidos en ellos que no se pueden inspeccionar desde propiedades de estilo y estado de ventana clásica (como una barra de título oculta automáticamente).

De forma predeterminada, el sistema crea un moderador y se aplica a una AppWindow en tiempo de creación. En el SDK de Aplicaciones para Windows 1.0, dentro del escritorio de Windows, el tipo de moderador es OverlappedPresenter, que es una subclase de AppWindowPresenter. No es necesario que la aplicación lo guarde, ni mantener una referencia a ella para volver al moderador predeterminado para una ventana después de haber aplicado otro moderador. Esto se debe a que el sistema mantiene la misma instancia de este moderador durante la vigencia de AppWindow para la que se creó; y la aplicación puede volver a aplicarla llamando al método AppWindow.SetPresenter con AppWindowPresenterKind.Default como parámetro.

Un moderador solo se puede aplicar a una sola ventana a la vez. Al intentar aplicar el mismo moderador a una segunda ventana, se produce una excepción. Esto significa que si tienes varias ventanas y deseas cambiar cada una a un modo de presentación específico, debes crear varios moderadores del mismo tipo y, a continuación, aplicar cada uno a su propia ventana.

Algunos moderadores tienen una funcionalidad que permite al usuario realizar cambios fuera del propio control de la aplicación. Cuando se produce este cambio, la aplicación recibe una notificación por un evento de AppWindow.Changed en la AppWindow afectada, con la propiedad AppWindowChangedEventArgs.DidPresenterChange establecida en true. A continuación, la aplicación debe inspeccionar la propiedad del moderador aplicado para ver lo que ha cambiado.

El moderador aplicado es un objeto activo. Un cambio en cualquier propiedad del objeto AppWindow.Presenter surte efecto inmediatamente.

Un moderador no se puede destruir mientras se aplica a una ventana. Para destruir un objeto moderador, aplica primero un objeto moderador diferente a la ventana; de este modo, el moderador que pretendes destruir se elimina de la ventana. Puedes hacerlo si aplicas otro moderador específico a la ventana o llamando al método AppWindow.SetPresenter con AppWindowPresenterKind.Default como argumento, que volverá a aplicar el moderador creado por el sistema predeterminado a la ventana. Si has seguido manteniendo una referencia al moderador creado por el sistema para la ventana, será válido en este momento (es decir, se volverá a aplicar la instancia que se creó por primera vez para la ventana).

Moderadores disponibles

Se proporcionan estos moderadores derivados de AppWindowPresenter y están disponibles en todas las versiones del sistema operativo compatibles.

  • CompactOverlayPresenter. Crea una ventana siempre visible de un tamaño fijo, con una relación de aspecto de 16:9 para permitir experiencias de imagen en imagen.
  • FullScreenPresenter. Permite que una ventana entre en una experiencia de pantalla completa.
  • OverlappedPresenter. El moderador predeterminado creado por el sistema, que te permite solicitar y reaccionar para minimizar, maximizar o restaurar operaciones y cambios de estado.

Marco de interfaz de usuario e interoperabilidad de HWND

La clase AppWindow está disponible para cualquierHWND de nivel superior en la aplicación. Esto significa que, al trabajar con un marco de interfaz de usuario de escritorio (incluido WinUI 3), puedes seguir usando el punto de entrada de ese marco para crear una ventana y adjuntar su contenido. Y una vez que hayas creado una ventana con ese marco de interfaz de usuario, puedes usar las funciones de interoperabilidad de ventanas (consulta la información mostrada a continuación) proporcionadas en el SDK de Aplicaciones para Windows para acceder a la AppWindow correspondiente y sus métodos, propiedades y eventos.

A continuación, se indican algunas de las ventajas de usar AppWindow (incluso cuando se trabaja con un marco de interfaz de usuario):

  • Personalización sencilla de la barra de título; que de forma predeterminada mantiene la interfaz de usuario de Windows 11 (esquinas redondeadas, control flotante del grupo de ajuste).
  • Experiencias de superposición compacta y de pantalla completa (imagen en imagen) proporcionadas por el sistema.
  • Superficie de API de Windows Runtime (WinRT) para algunos de los conceptos básicos de ventanas de Win32.

Ejemplo de código

En este ejemplo de código se muestra cómo recuperar una Microsoft.UI.Windowing.AppWindow desde una ventana de WinUI 3 mediante la propiedad Microsoft.UI.Xaml.Window.AppWindow. Para usar el ejemplo, crea un nuevo proyecto Aplicación en blanco, Empaquetado (WinUI 3 en escritorio) y pega el código.

Para obtener más información sobre cómo trabajar con AppWindow, consulta el ejemplo de la galería de ventanas.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow = this.AppWindow;

    if (appWindow != null)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = this->AppWindow();

    if (appWindow)
    {
        // With a non-null AppWindow object, you can call its methods
        // to manipulate the window. As an example, let's change the title
        // text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Ejemplo de código para versiones de SDK de Aplicaciones para Windows anteriores a la versión 1.3 (u otros marcos de aplicaciones de escritorio)

La propiedad Microsoft.UI.Xaml.Window.AppWindow (usada en el ejemplo de código anterior) está disponible en SDK de Aplicaciones para Windows versión 1.3 y posteriores. Para versiones anteriores, puedes usar el ejemplo de código funcionalmente equivalente en esta sección.

C#. Los contenedores de .NET para las funciones de interoperabilidad de ventanas se implementan como métodos de la clase Microsoft.UI.Win32Interop. Consulta también Llamada a las API de interoperabilidad desde una aplicación con .NET.

C++. Las funciones de interoperabilidad se definen en el archivo de encabezado winrt/Microsoft.ui.interop.h.

En la sección Ejemplo de código a continuación se muestra el código fuente real; pero esta es la receta para recuperar un objeto AppWindow dado una ventana existente:

  1. Recupera el HWND del objeto de ventana existente (para el marco de trabajo de la interfaz de usuario), si aún no lo tienes.
  2. Pasa ese HWND a la función de interoperabilidad GetWindowIdFromWindow para recuperar un WindowId.
  3. Pasa ese WindowId al método estático AppWindow.GetFromWindowId para recuperar la AppWindow.
// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    var hWnd =
        WinRT.Interop.WindowNative.GetWindowHandle(this);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft.UI.WindowId windowId =
        Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow =
        Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);

    if (appWindow != null)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include "microsoft.ui.xaml.window.h" // For the IWindowNative interface.
#include <winrt/Microsoft.UI.Interop.h> // For the WindowId struct and the GetWindowIdFromWindow function.
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    auto windowNative{ this->m_inner.as<::IWindowNative>() };
    HWND hWnd{ 0 };
    windowNative->get_WindowHandle(&hWnd);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft::UI::WindowId windowId = 
        Microsoft::UI::GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = 
        Microsoft::UI::Windowing::AppWindow::GetFromWindowId(windowId);

    if (appWindow)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Limitaciones

  • AppWindow es una API de WinUI 3. Esto significa que solo está disponible para las aplicaciones de escritorio (empaquetadas y sin empaquetar); y no está disponible para aplicaciones para UWP.
  • Actualmente, el SDK de Aplicaciones para Windows no proporciona métodos para adjuntar contenido del marco de interfaz de usuario a AppWindow. Consulta la sección Ejemplo de código.
  • La personalización de la barra de título se admite en Windows 11 y versiones posteriores, y en Windows 10 para la versión 1.2 y posteriores del SDK de Aplicaciones para Windows. Para más información, consulta Personalización de la barra de título.