Migración de la funcionalidad de ventanas

Este tema contiene instrucciones relacionadas con la administración de ventanas, incluida la migración desde ApplicationView/CoreWindow o AppWindow de UWP al SDK de aplicaciones para Windows Microsoft.UI.Windowing.AppWindow.

API importantes

• microsoft.UI.Windowing.AppWindow
• Propiedad Windows.UI.Core.CoreWindow.Dispatcher
• Propiedad Microsoft.UI.Window.DispatcherQueue

Resumen de las API y/o diferencias en las características

El Windows App SDK proporciona una clase Microsoft.UI.Windowing.AppWindow basada en el modelo HWND de Win32. Esa clase AppWindow es la versión del Windows App SDK de ApplicationView, CoreWindow y AppWindow de UWP.

Para aprovechar las ventajas de las API de ventanas de Windows App SDK significa que migrarás el código de UWP para usar el modelo Win32. Para obtener más información sobre Windows App SDK AppWindow, consulta Administrar windows.

Tipos de ventana en UWP frente a la Windows App SDK

En una aplicación UWP, puedes alojar contenido de ventana mediante ApplicationView/CoreWindow, o AppWindow. El trabajo implicado en la migración de ese código a la Windows App SDK depende de cuál de esos dos modelos de ventana usa la aplicación para UWP. Si estás familiarizado con Windows.UI.WindowManagement.AppWindow de UWP, es posible que veas similitudes entre esta y Microsoft.UI.Windowing.AppWindow.

Tipos de ventana de UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida el subproceso de la interfaz de usuario y la ventana que usa la aplicación para mostrar contenido. Las aplicaciones UWP que usan AppWindow tendrán menos trabajo que hacer que las aplicaciones ApplicationView/CoreWindow para migrar a AppWindow del Windows App SDK.

tipo de ventana Windows App SDK

• Microsoft.UI.Windowing.AppWindow es la abstracción de alto nivel de un contenedor administrado por el sistema del contenido de una aplicación.

Ten en cuenta que las diferencias en los modelos de ventanas entre UWP y Win32 significan que no hay una asignación directa de 1:1 entre la superficie de la API de UWP y la superficie de la API de Windows App SDK. Incluso para los nombres de clase y miembros que se transfieren de UWP (reflejados en las tablas de asignación de este tema), el comportamiento también puede diferir.

Pantallas de presentación

A diferencia de las aplicaciones para UWP, las aplicaciones Win32 no muestran de forma predeterminada una pantalla de presentación en el inicio. Las aplicaciones para UWP que dependen de esta característica para su experiencia de inicio pueden optar por implementar una transición personalizada a su primera ventana de la aplicación.

Crear, mostrar, cerrar y destruir una ventana

La duración de microsoft.UI.Windowing.AppWindow es la misma que para un HWND, lo que significa que el objeto AppWindow está disponible inmediatamente después de crear la ventana y se destruye cuando se cierra la ventana.

Crear y mostrar

AppWindow.Create crea una ventana de aplicación con la configuración predeterminada. Crear y mostrar una ventana solo es necesario para escenarios en los que no se trabaja con un marco de interfaz de usuario. Si vas a migrar tu aplicación para UWP a un marco de interfaz de usuario compatible con Win32, puedes acceder al objeto AppWindow desde una ventana ya creada mediante los métodos de interoperabilidad de ventanas.

Cerrar

En UWP, ApplicationView.TryConsolidateAsync es el equivalente mediante programación del usuario que inicia un gesto de cierre. Este concepto de consolidación (en el modelo de ventanas de ApplicationView/CoreWindow de UWP) no existe en Win32. Win32 no requiere que las ventanas existan en subprocesos independientes. La replicación del modelo de ventanas de UWPApplicationView/CoreWindow requeriría que el desarrollador cree un nuevo subproceso y cree una nueva ventana allí. En el modelo Win32, el comportamiento predeterminado del sistema es Cerrar>Ocultar>Destruir.

Personalización de ventana básica

A medida que migre de UWP a Windows App SDK, puede esperar la misma experiencia de la AppWindow predeterminada. Pero si es necesario, puede cambiar el valor predeterminado Microsoft.UI.Windowing.AppWindow para experiencias de ventana personalizadas. Consulta Microsoft.UI.Windowing.AppWindow para obtener más información sobre cómo personalizar las ventanas.

Cambio de tamaño de una ventana

Posicionamiento de una ventana

Título de la ventana

Superposición compacta y pantalla completa

Las aplicaciones que entran en superposición compacta o pantalla completa deben aprovechar el Windows App SDK AppWindowPresenter. Si estás familiarizado con el AppWindow de UWP, es posible que ya estés familiarizado con el concepto de presentadores.

No existe una correspondencia directa de funcionalidad y comportamiento entre los presentadores de ventanas de aplicaciones UWP y los de Windows App SDK. Si tienes una aplicación UWP ApplicationView/CoreWindow, puedes tener experiencias de superposición compacta (imagen en imagen) o ventanas de pantalla completa en tu aplicación, pero es posible que el concepto de presentadores sea nuevo para ti. Para obtener más información sobre los presentadores de ventanas de aplicaciones, consulte Moderadores. De forma predeterminada, un presentador superpuesto se aplica a un AppWindow en el momento de la creación. CompactOverlay y FullScreen son los únicos moderadores disponibles, aparte de los predeterminados.

Superposición compacta

Si usaste ApplicationViewMode de UWP o AppWindowPresentionKind para presentar una ventana de superposición compacta, debes usar la superposición compacta AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter solo admite tres tamaños fijos de ventana con una relación de aspecto de 16:9 y el usuario no puede cambiar el tamaño. En lugar de ApplicationViewMode.TryEnterViewModeAsync o AppWindowPresenterKind.RequestPresentation, debe usar AppWindow.SetPresenter para cambiar la presentación de AppWindow.

Pantalla completa

Si usaste las clases ApplicationViewWindowingMode o AppWindowPresentionKind de UWP para presentar una ventana de pantalla completa, debes usar appWindowPresenterKind de pantalla completa. El Windows App SDK solo admite la experiencia de pantalla completa más restrictiva (es decir, cuando FullScreen es IsExclusive). Para ApplicationView/CoreWindow, puedes usar ApplicationView.ExitFullScreenMode para sacar la aplicación de pantalla completa. Al usar presentadores, puede quitar una aplicación de la pantalla completa configurando el presentador de nuevo a su estado superpuesto/predeterminado mediante AppWindow.SetPresenter.

Para obtener más detalles sobre cómo trabajar con presentadores de ventanas de aplicaciones, consulte el ejemplo de la galería Windowing. Demuestra cómo alternar diferentes estados del presentador de ventanas de la aplicación.

Barra de título personalizada

Si la aplicación usa una barra de título predeterminada, no se necesita ningún trabajo adicional de barra de título al migrar a Win32. Si, por otro lado, tu aplicación UWP tiene una barra de título personalizada, entonces es posible recrear los siguientes escenarios en tu aplicación de Windows App SDK.

1. Personalizar la barra de título dibujada por el sistema
2. Barra de título personalizada dibujada por la aplicación

Código que usa las clases de UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar y AppWindowTitleBar migra al uso de la clase Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar.

Personalizar la barra de título dibujada por el sistema

Esta es una tabla de las API de personalización de colores.

Estas API de Windows App SDK son para personalizar aún más la barra de título dibujada por el sistema, además de la API AppWindow.Title.

• AppWindow.SetIcon. Establece la imagen de la barra de título y del icono de la barra de tareas mediante un identificador hIcon o una ruta de acceso de cadena a un recurso o a un archivo.
• AppWindowTitleBar.IconShowOptions. Obtiene o establece un valor que especifica cómo se muestra el icono de ventana en la barra de título. Admite dos valores actualmente: HideIconAndSystemMenu y ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Restablece la barra de título actual a la configuración predeterminada de la ventana.

Barra de título personalizada dibujada por la aplicación (personalización completa)

Si va a migrar al uso de AppWindowTitleBar, se recomienda comprobar AppWindowTitleBar.IsCustomizationSupported en el código antes de llamar a las siguientes API de barra de título personalizada.

Estas API de Windows App SDK son para personalizar la barra de título completa.

• AppWindowTitleBar.SetDragRectangles. Establece las regiones de arrastre de la ventana.
• AppWindowTitleBar.ResetToDefault. Restablece la barra de título actual a la configuración predeterminada de la ventana.

Estas API de UWP AppWindow no tienen una asignación directa uno a uno a una API de Windows App SDK.

• AppWindowTitleBarVisibility. Define constantes que especifican la visibilidad preferida de una appWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Recupera el modo de visibilidad preferido para la barra de título.
• AppWindowTitleBar.SetPreferredVisibility. Establece el modo de visibilidad preferido para la barra de título.

Para obtener más información sobre cómo trabajar con AppWindowTitleBar, consulte el ejemplo de la galería Windowing. Muestra cómo crear una barra de título de color personalizada y cómo dibujar una barra de título personalizada.

Control de eventos

Si la aplicación para UWP usa el evento AppWindow.Changed, puedes migrar ese código al evento Microsoft.UI.Windowing.AppWindow.Changed.

Evento de cambio de tamaño

Al migrar el código de manejo de eventos de cambio de tamaño, debe utilizar la propiedad Windows App SDK AppWindowChangedEventArgs.DidSizeChange. El valor es true si el tamaño de la ventana de la aplicación ha cambiado; de lo contrario, es false.

MainPage y MainWindow

Cuando creas una nueva project para UWP en Visual Studio, la plantilla de project te proporciona una clase MainPage. Para la aplicación, es posible que haya cambiado el nombre de esa clase (o haya agregado más páginas y controles de usuario). La plantilla de proyecto también proporciona código de navegación en los métodos de la clase App.

Al crear un nuevo proyecto de SDK para aplicaciones de Windows en Visual Studio, la plantilla del proyecto proporciona una clase MainWindow (de tipo Microsoft.UI.Xaml.Window), pero no incluye una Page. Y la plantilla project no proporciona ningún código de navegación.

Sin embargo, tiene la opción de agregar páginas y controles de usuario a su proyecto de Windows App SDK. Por ejemplo, puede agregar un nuevo elemento de página al project (WinUI>Blank Page (WinUI)) y asignarle el nombre MainPage.xaml, o algún otro nombre. Esto agregaría a la project una nueva clase de tipo Microsoft.UI.Xaml.Controls.Page. A continuación, para obtener información sobre cómo agregar código de navegación al proyecto, consulta ¿Necesito implementar la navegación de página?.

Para aplicaciones de Windows App SDK lo suficientemente simples, no necesitas crear páginas ni controles de usuario, y puedes copiar tu marcado XAML y el code-behind en MainWindow. Pero para obtener información sobre las excepciones a ese flujo de trabajo, vea Visual State Manager y Page.Resources.

Cambie el CoreWindow.Dispatcher a el Window.DispatcherQueue

Algunos casos de uso de la clase Windows.UI.Core.CoreWindow de UWP migran a la clase Microsoft.UI.Xaml.Window del Windows App SDK.

Por ejemplo, si usas la propiedad Windows.UI.Core.CoreWindow.Dispatcher en tu aplicación para UWP, la solución es no migrar a la propiedad Microsoft.UI.Xaml.Window.Dispatcher (que siempre retorna null). En su lugar, migre a la propiedad Microsoft.UI.Xaml.Window.DispatcherQueue, que devuelve un Microsoft.UI.Dispatching.DispatcherQueue.

Para obtener más información y ejemplos de código, consulta Cambiar Windows.UI.Core.CoreDispatcher a Microsoft.UI.Dispatching.DispatcherQueue.

Temas relacionados

• Windows App SDK y versiones de Windows compatibles
• Migración de la funcionalidad de subprocesos