Migração da funcionalidade de janelas

Este tópico contém orientações relacionadas ao gerenciamento de janelas, incluindo a migração do ApplicationView da UWP/CoreWindow ou AppWindow para o SDK do Aplicativo do Windows Microsoft.UI.Windowing.AppWindow .

APIs importantes

• Microsoft.UI.Windowing.AppWindow
• propriedade Windows.UI.Core.CoreWindow.Dispatcher
• propriedade Microsoft.UI.Window.DispatcherQueue
• Microsoft.UI.Input.InputKeyboardSource.GetKeyStateForCurrentThread método

Resumo das diferenças de API e/ou recursos

O SDK de Aplicações Windows fornece uma classe Microsoft.UI.Windowing.AppWindow baseada no modelo HWND do Win32. Essa classe AppWindow é a versão da SDK de Aplicações Windows do ApplicationView/CoreWindow e AppWindow.

Tirar partido das APIs de janelas do SDK de Aplicações Windows significa que vais migrar o teu código UWP para usar o modelo Win32. Para mais informações sobre o SDK de Aplicações Windows AppWindow, veja Gerir as janelas da app.

Tipos de janelas no UWP versus o SDK de Aplicações Windows

Em um aplicativo UWP, você pode hospedar o conteúdo da janela usando ApplicationView/CoreWindow ou AppWindow. O trabalho de migração desse código para o SDK de Aplicações Windows depende de qual desses dois modelos de janelas a sua aplicação UWP utiliza. Se estiveres familiarizado com o da UWPWindows.UI.WindowManagement.AppWindow, poderás ver semelhanças entre isso e Microsoft.UI.Windowing.AppWindow.

Tipos de janela UWP

• Windows. UI. ViewManagement.ApplicationView/Windows. UI. Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida a sequência da interface do utilizador e a janela que a aplicação usa para exibir conteúdo. As aplicações UWP que usam AppWindow terão menos trabalho a fazer do que as aplicações ApplicationView/CoreWindow para migrar para a AppWindow do SDK de Aplicações Windows.

Tipo de janela do SDK de Aplicações Windows

• Microsoft.UI.Windowing.AppWindow é a abstração de alto nível de um contêiner gerenciado pelo sistema do conteúdo de um aplicativo.

Tenha em mente que as diferenças nos modelos de janelas entre UWP e Win32 significam que não existe um mapeamento direto 1:1 entre a surface da API UWP e a surface da API do SDK de Aplicações Windows. Mesmo para nomes de classe e membros que transferir da UWP (refletido nas tabelas de mapeamento deste tópico), o comportamento também pode ser diferente.

Ecrãs iniciais

Ao contrário dos aplicativos UWP, os aplicativos Win32 não mostram, por padrão, uma tela inicial na inicialização. Os aplicativos UWP que dependem desse recurso para sua experiência de inicialização podem optar por implementar uma transição personalizada para sua primeira janela de aplicativo.

Criar, mostrar, fechar e destruir uma janela

O tempo de vida de um Microsoft.UI.Windowing.AppWindow é o mesmo de um HWND; o que significa que o objeto AppWindow está disponível imediatamente após a janela ter sido criada e é destruído quando a janela é fechada.

Criar e mostrar

AppWindow.Create cria uma janela de aplicativo com a configuração padrão. Criar e mostrar uma janela só é necessário para cenários em que você não está trabalhando com uma estrutura de interface do usuário. Se você estiver migrando seu aplicativo UWP para uma estrutura de interface do usuário compatível com Win32, ainda poderá acessar seu objeto AppWindow de uma janela já criada usando os métodos de interoperabilidade de janelas.

Fechar

Na UWP, ApplicationView.TryConsolidateAsync é o equivalente programático do usuário que inicia um gesto de fechar. Esse conceito de de consolidação de (no modelo de janelas ApplicationViewCoreWindow da UWP) não existe no Win32. O Win32 não requer que as janelas existam em threads separados. Replicar o ApplicationView da UWP/o modelo de janela CoreWindow exigiria que o desenvolvedor criasse um novo thread e criasse uma nova janela lá. No modelo Win32, o comportamento padrão do sistema é Close>Hide>Destroy.

Personalização básica de janelas

À medida que faz a migração do UWP para o SDK de Aplicações Windows, pode contar com a mesma experiência do seu AppWindow. Mas, se necessário, você pode alterar o padrão Microsoft.UI.Windowing.AppWindow para experiências de janela personalizadas. Consulte Microsoft.UI.Windowing.AppWindow para obter mais informações sobre como personalizar suas janelas.

Redimensionar uma janela

Posicionar uma janela

Título da janela

Sobreposição compacta e ecrã inteiro

As aplicações que entram em overlay compacto, ou em ecrã inteiro, devem aproveitar o SDK de Aplicações Windows AppWindowPresenter. Se você estiver familiarizado com a UWP AppWindow, talvez já esteja familiarizado com o conceito de apresentadores.

Não existe um mapeamento 1:1 das funcionalidades e comportamentos dos apresentadores de janelas de aplicações UWP para os apresentadores de janelas de aplicações do SDK de Aplicações Windows. Se tiver uma aplicação UWP ApplicationView/CoreWindow, ainda pode ter experiências de sobreposição compacta (picture-in-picture) ou de janelas em ecrã completo na sua aplicação, mas o conceito de apresentadores pode ser novo para si. Para obter mais informações sobre apresentadores de janelas de aplicação, consulte Apresentadores. Por padrão, um apresentador sobreposto é aplicado a um AppWindow no momento da criação. CompactOverlay e FullScreen são os únicos apresentadores disponíveis, além do padrão.

Sobreposição compacta

Se usou o ApplicationViewMode ou o AppWindowPresentationKind do UWP para apresentar uma janela de sobreposição compacta, então deve usar a sobreposição compacta AppWindowPresenterKind. O Microsoft.UI.Windowing.CompactOverlayPresenter suporta apenas três tamanhos de janela fixos em uma proporção de 16:9 e não pode ser redimensionado pelo usuário. Em vez de ApplicationView.TryEnterViewModeAsync ou AppWindowPresenter.RequestPresentation, deve usar AppWindow.SetPresenter para alterar a apresentação da AppWindow.

Ecrã inteiro

Se usou as classes ApplicationViewWindowingMode ou AppWindowPresentationKind da UWP para apresentar uma janela em ecrã inteiro, então deve usar a aplicação em ecrã inteiro ( AppWindowPresenterKind). O SDK de Aplicações Windows suporta apenas a experiência de ecrã inteiro mais restritiva (ou seja, quando FullScreen é IsExclusive). Para ApplicationView/CoreWindow, pode utilizar o ApplicationView.ExitFullScreenMode para retirar a aplicação do modo de ecrã completo. Ao usar apresentadores, pode-se tirar um aplicativo da tela inteira definindo o apresentador de volta para sobreposição/padrão usando AppWindow.SetPresenter.

Para mais detalhes sobre como trabalhar com apresentadores de janelas de aplicações, consulte o exemplo da galeria Windowing. Ele demonstra como alternar diferentes estados do apresentador da janela do aplicativo.

Barra de título personalizada

Se seu aplicativo usa uma barra de título padrão, não há trabalho adicional na barra de título necessário quando você migra para o Win32. Se, por outro lado, a sua aplicação UWP tiver uma barra de título personalizada, então é possível recriar os seguintes cenários na sua aplicação SDK de Aplicações Windows.

1. Personalizar a barra de título desenhada pelo sistema
2. Barra de título personalizada desenhada por aplicativo

O código que utiliza as classes UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar e AppWindowTitleBar migra para usar a classe SDK de Aplicações Windows Microsoft.UI.Windowing.AppWindowTitleBar.

Personalizar a barra de título desenhada pelo sistema

Aqui está uma tabela das APIs de personalização de cores.

Estas APIs SDK de Aplicações Windows destinam-se a uma personalização adicional da barra de título desenhada pelo sistema, além da API AppWindow.Title.

• AppWindow.SetIcon. Define a imagem da barra de título e do ícone da barra de tarefas usando um identificador hIcon ou um caminho de cadeia de caracteres para um recurso ou um arquivo.
• AppWindowTitleBar.IconShowOptions. Obtém ou define um valor que especifica como o ícone da janela é exibido na barra de título. Suporta dois valores atualmente: HideIconAndSystemMenu e ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Redefine a barra de título atual de volta para as configurações padrão da janela.

Barra de título personalizada desenhada por aplicativo (personalização completa)

Se você estiver migrando para usar AppWindowTitleBar, recomendamos que marque AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar as seguintes APIs de barra de título personalizadas.

Estas APIs do SDK de Aplicações Windows destinam-se a personalizar totalmente a barra de título.

• AppWindowTitleBar.SetDragRectangles. Define as regiões de arrasto para a janela.
• AppWindowTitleBar.ResetToDefault. Redefine a barra de título atual de volta para as configurações padrão da janela.

Estas APIs UWP AppWindow não têm mapeamento direto 1:1 para uma API SDK de Aplicações Windows.

• AppWindowTitleBarVisibility. Define constantes que especificam a visibilidade preferida de um AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Recupera o modo de visibilidade preferido para a barra de título.
• AppWindowTitleBar.SetPreferredVisibility. Define o modo de visibilidade preferido para a barra de título.

Para mais detalhes sobre como trabalhar com AppWindowTitleBar, consulte o exemplo da galeria Windowing. Ele demonstra como criar uma barra de título de cor personalizada e como desenhar uma barra de título personalizada.

Tratamento de eventos

Se o seu aplicativo UWP usa o evento AppWindow.Changed, pode migrar esse código para o evento Microsoft.UI.Windowing.AppWindow.Changed.

Evento de alteração de tamanho

Ao migrar o código de manipulação de eventos de alteração de tamanho, deve mudar para usar a propriedade SDK de Aplicações Windows AppWindowChangedEventArgs.DidSizeChange. O valor é true se o tamanho da janela do aplicativo mudou, caso contrário, é false.

MainPage e MainWindow

Quando cria um novo projeto UWP no Visual Studio, o modelo de projeto fornece-lhe uma classe MainPage. Para seu aplicativo, você pode ter renomeado essa classe (e/ou adicionado mais páginas e controles de usuário). O modelo de projeto também lhe fornece código de navegação nos métodos da classe App.

Quando criar um novo projeto SDK de Aplicações Windows no Visual Studio, o modelo de projeto fornece-lhe uma classe MainWindow (do tipo Microsoft.UI.Xaml.Window), mas não existe Page. E o modelo do projeto não fornece nenhum código de navegação.

No entanto, tens a opção de adicionar páginas e controlos de utilizador ao teu SDK de Aplicações Windows project. Por exemplo, pode adicionar um novo item de página ao project (WinUI>Blank Page (WinUI)) e nomeá-lo MainPage.xaml, ou outro nome. Isso acrescentaria ao teu project uma nova classe de tipo Microsoft.UI.Xaml.Controls.Page. Depois, para informações sobre como adicionar código de navegação ao project, veja Preciso implementar a navegação de página?.

Para aplicações suficientemente simples do SDK de Aplicações Windows, não é necessário criar páginas ou controlos de utilizador, e podes copiar a marcação XAML e o code-behind para MainWindow. Mas para obter informações sobre exceções a esse fluxo de trabalho, consulte Visual State Manager e Page.Resources.

Altere CoreWindow.Dispatcher para Window.DispatcherQueue

Alguns casos de uso da classe Windows.UI.Core.CoreWindow do UWP migram para a Microsoft.UI.Xaml.Window do SDK de Aplicações do Windows.

Por exemplo, se estiveres a usar a propriedade Windows.UI.Core.CoreWindow.Dispatcher na tua aplicação UWP, a solução não é já migrar para a propriedade Microsoft.UI.Xaml.Window.Dispatcher (que sempre retorna null). Em vez disso, migre para a propriedade Microsoft.UI.Xaml.Window.DispatcherQueue, que retorna um Microsoft.UI.Dispatching.DispatcherQueue.

Para obter mais informações e exemplos de código, consulte alterar Windows.UI.Core.CoreDispatcher para Microsoft.UI.Dispatching.DispatcherQueue.

Teclas modificadoras e estado do teclado

No UWP, deteta o estado das teclas modificadoras (Ctrl, Shift, Alt) chamando CoreWindow.GetForCurrentThread(). GetKeyState. No SDK de Aplicações Windows, CoreWindow não é suportado para aplicações de ambiente de trabalho. Em vez disso, use Microsoft.UI.Input.InputKeyboardSource.GetKeyStateForCurrentThread, que fornece a mesma funcionalidade sem necessitar de uma referência de janela.

UWP

using Windows.System;
using Windows.UI.Core;

var ctrlState = CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Control);
bool isControlPressed = (ctrlState & CoreVirtualKeyStates.Down) == CoreVirtualKeyStates.Down;

SDK de aplicativos do Windows

using Windows.System;
using Windows.UI.Core;
using Microsoft.UI.Input;

var ctrlState = InputKeyboardSource.GetKeyStateForCurrentThread(VirtualKey.Control);
bool isControlPressed = (ctrlState & CoreVirtualKeyStates.Down) == CoreVirtualKeyStates.Down;

O GetKeyStateForCurrentThread método é estático no InputKeyboardSource, por isso não precisas de referência à janela nem a qualquer objeto de entrada. Podes chamá-lo de qualquer lugar no thread da interface, incluindo dentro de handlers de eventos como PointerPressed ou Click, para verificar se uma tecla modificadora está pressionada.

Tópicos relacionados

• SDK de Aplicações Windows e versões suportadas para Windows
• Migrar sua funcionalidade de threading