Migração da funcionalidade de janelas

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

APIs importantes

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

Resumo das diferenças de API e/ou recursos

O Windows App SDK fornece uma classe Microsoft.UI.Windowing.AppWindow baseada no modelo HWND Win32. Essa classe AppWindow é a versão do Windows App SDK do ApplicationView/CoreWindow e AppWindow.

Para aproveitar as APIs de janela Windows App SDK significa que você migrará seu código UWP para usar o modelo Win32. Para obter mais informações sobre o Windows App SDK AppWindow, consulte Manage app windows.

Tipos de janela na UWP versus o Windows App SDK

Em um aplicativo UWP, você pode hospedar o conteúdo da janela usando ApplicationView/CoreWindow, ou AppWindow. O trabalho envolvido na migração desse código para o Windows App SDK depende de quais desses dois modelos de janelas seu aplicativo UWP usa. Se você estiver familiarizado com o Windows.UI.WindowManagement.AppWindow da UWP, poderá ver semelhanças entre ele e Microsoft.UI.Windowing.AppWindow.

Tipos de janela UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida o thread da interface do usuário e a janela que o aplicativo usa para exibir conteúdo. Os aplicativos UWP que usam AppWindow terão menos trabalho a fazer do que os aplicativos ApplicationView/CoreWindow para migrar para o Windows App SDK AppWindow.

tipo de janela Windows App SDK

• 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 janela entre UWP e Win32 significam que não há uma correspondência direta 1:1 entre a superfície da API UWP e a superfície da API do Windows App SDK. Mesmo para nomes de classe e membro que são transferidos da UWP (refletidos nas tabelas de mapeamento deste tópico), o comportamento também pode ser diferente.

Telas de carregamento

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 a primeira janela do 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 criação da janela 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 janela.

Fechar

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

Personalização básica de janela

Ao migrar da UWP para o Windows App SDK, você pode esperar a mesma experiência do AppWindow padrão. Mas, se necessário, você pode alterar o padrão Microsoft.UI.Windowing.AppWindow para experiências de janelas personalizadas. Consulte Microsoft.UI.Windowing.AppWindow para obter mais informações sobre como personalizar suas janelas.

Redimensionando uma janela

Posicionando uma janela

Título da janela

Sobreposição compacta e tela cheia

Os aplicativos que entram em modo de sobreposição compacta ou tela inteira devem utilizar o AppWindowPresenter do Windows App SDK. Se você estiver familiarizado com o UWP AppWindow, talvez já esteja familiarizado com o conceito de apresentadores.

Não há um mapeamento 1:1 da funcionalidade e do comportamento dos apresentadores da janela do aplicativo UWP para apresentadores da janela do aplicativo do Windows App SDK. Se você tiver um aplicativo UWP ApplicationView/CoreWindow , ainda poderá ter experiências de sobreposição compacta (picture-in-picture) ou janelas de tela inteira em seu aplicativo, mas o conceito de apresentadores pode ser novo para você. Para obter mais informações sobre apresentadores de janelas de aplicativos, 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 você usou o ApplicationViewMode ou AppWindowPresentionKind da UWP para apresentar uma janela de sobreposição compacta, deverá usar a sobreposição compacta AppWindowPresenterKind. O Microsoft.UI.Windowing.CompactOverlayPresenter dá suporte a apenas três tamanhos de janela fixos em uma taxa de proporção de 16:9 e não pode ser redimensionado pelo usuário. Em vez de ApplicationViewMode.TryEnterViewModeAsync ou AppWindowPresenterKind.RequestPresentation, você deve usar AppWindow.SetPresenter para alterar a apresentação do AppWindow.

Tela cheia

Se você usou as classes ApplicationViewWindowingMode ou AppWindowPresentationKind da UWP para apresentar uma janela em tela cheia, deverá usar o AppWindowPresenterKind de tela cheia. O Windows App SDK dá suporte apenas à experiência de tela inteira mais restritiva (ou seja, quando FullScreen é IsExclusive). Para ApplicationView/CoreWindow, você pode usar o ApplicationView.ExitFullScreenMode para tirar o aplicativo da tela inteira. Ao usar apresentadores, você pode tirar um aplicativo da tela inteira ajustando o apresentador para sobreposto/padrão usando AppWindow.SetPresenter.

Para obter mais detalhes sobre como trabalhar com os apresentadores da janela do aplicativo, consulte o exemplo da galeria Windowing. Ele demonstra como alternar diferentes estados de apresentador da janela do aplicativo.

Barra de título personalizada

Se o aplicativo usar uma barra de título padrão, não haverá nenhum trabalho adicional na barra de título necessário ao migrar para o Win32. Se, por outro lado, seu aplicativo UWP tiver uma barra de título personalizada, será possível recriar os cenários a seguir em seu aplicativo Windows App SDK.

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

Código que usa as classes UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar e AppWindowTitleBar migra para usar a classe da Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar.

Personalizar a barra de título desenhada pelo sistema

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

Essas APIs Windows App SDK são para personalização adicional da barra de título desenhada pelo sistema, além da API AppWindow.Title.

• AppWindow.SetIcon. Define a barra de título e a imagem do ícone da barra de tarefas usando um identificador hIcon ou um caminho de cadeia de caracteres para um recurso ou para um arquivo.
• AppWindowTitleBar.IconShowOptions. Obtém ou define um valor que especifica como o ícone da janela é exibido na barra de título. Atualmente, dá suporte a dois valores: 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 o uso de AppWindowTitleBar, recomendamos que você verifique AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar as seguintes APIs de barra de título personalizadas.

Essas APIs de Windows App SDK são para personalização completa da barra de título.

• AppWindowTitleBar.SetDragRectangles. Definir 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.

Essas APIs UWP AppWindow não têm mapeamento 1:1 direto para uma API de Windows App SDK.

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

Para obter 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.

Manipulação de eventos

Se o aplicativo UWP usar o evento AppWindow.Changed, você poderá 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, você deve alterar para utilizar a propriedade Windows App SDK AppWindowChangedEventArgs.DidSizeChange. O valor é true se o tamanho da janela do aplicativo mudou, caso contrário, é false.

Página principal e janela principal

Quando você cria um novo projeto UWP no Visual Studio, o modelo de projeto fornece 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 fornece a você código de navegação nos métodos da classe App.

Quando você cria um novo projeto do Windows App SDK no Visual Studio, o modelo de projeto fornece uma classe MainWindow (do tipo Microsoft.UI.Xaml.Window), mas nenhuma Página. E o modelo de projeto não fornece nenhum código de navegação.

No entanto, você tem a opção de adicionar páginas e controles de usuário ao seu Windows App SDK project. Por exemplo, você pode adicionar um novo item de página ao project (WinUI>Blank Page (WinUI)) e nomeá-lo MainPage.xaml ou algum outro nome. Isso adicionaria à sua project uma nova classe do tipo Microsoft.UI.Xaml.Controls.Page. Em seguida, para obter informações sobre como adicionar código de navegação ao project, consulte Do que preciso para implementar a navegação de página?.

Para aplicativos do Windows App SDK que sejam simples o suficiente, você não precisa criar páginas ou controles de usuário, basta copiar sua 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.

Alterar CoreWindow.Dispatcher para Window.DispatcherQueue

Alguns casos de uso da classe Windows.UI.Core.CoreWindow em UWP migram para a Microsoft.UI.Xaml.Window do Windows App SDK.

Por exemplo, se você estiver usando a propriedade Windows.UI.Core.CoreWindow.Dispatcher em seu aplicativo UWP, a solução não é migrar para a propriedade Microsoft.UI.Xaml.Window.Dispatcher (que sempre retorna nulo). Em vez disso, migre para a Microsoft.UI.Xaml.Window.DispatcherQueue propriedade, 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.

Tópicos relacionados

• Windows App SDK e versões do Windows com suporte
• Migrar sua funcionalidade de encadeamento