Gerenciar janelas de aplicativos (SDK de Aplicativos Windows)

  • Artigo

Esta seção contém uma seção Exemplo de código.

O SDK de Aplicativos do Windows fornece a classe Microsoft.UI.Windowing.AppWindow fácil de usar. AppWindow é independente de estrutura e está disponível para todos os aplicativos do Windows, incluindo Win32, WPF e WinForms. Você pode contrastar a natureza independente de estrutura do AppWindow com Microsoft.UI.Xaml.Window, que é a classe de janela especificamente para a estrutura WinUI 3. AppWindow também é uma evolução do Windows.UI.WindowManagement.AppWindow da Plataforma Universal do Windows (UWP).

A versão do SDK de Aplicativos do Windows do Microsoft.UI.Windowing.AppWindow não depende de padrões assíncronos e fornece feedback imediato ao seu aplicativo sobre se as chamadas da API foram bem-sucedidas.

Consulte também Instalar ferramentas para o SDK de Aplicativos do Windows, Criar seu primeiro projeto WinUI 3 e Usar o SDK de Aplicativos do Windows em um projeto existente.

A classe AppWindow

Microsoft.UI.Windowing.AppWindow é uma API de janelas de alto nível que permite cenários de janelas fáceis de usar. O AppWindow se integra bem com a UI/UX do Windows e com outros aplicativos.

AppWindow representa uma abstração de alto nível de um contêiner gerenciado pelo sistema para o conteúdo de um aplicativo. Esse é o contêiner no qual o conteúdo está hospedado e representa a entidade com a qual os usuários interagem quando redimensionam e movem seu aplicativo na tela. Se você estiver familiarizado com o Win32, AppWindow pode ser vista como uma abstração de alto nível do HWND. Se você estiver familiarizado com a UWP, a janela do aplicativo pode ser vista como um substituto para CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Para a versão do SDK de Aplicativos do Windows do Microsoft.UI.Window.AppWindow, estamos dando suporte apenas a HWNDs de nível superior. Há um mapeamento 1:1 entre uma AppWindow e um HWND de nível superior.

O tempo de vida de um objeto AppWindow e de um HWND é o mesmo, a AppWindow está disponível imediatamente após a criação da janela e é destruído quando a janela é fechada.

A classe AppWindowPresenter e subclasses

Cada AppWindow tem um AppWindowPresenter (apresentador) aplicado a ele. Se você for um desenvolvedor de UWP que trabalhou com Windows.UI.WindowManagement.AppWindow, isso será familiar, mesmo que não seja um mapeamento 1:1 de funcionalidade e comportamento. Consulte também Migração de funcionalidade de janelas.

Como um novo conceito para o modelo de aplicativo do Win32, um apresentador é semelhante (mas não é o mesmo que) uma combinação de estado e estilos de janela. Alguns apresentadores também têm comportamentos de interface do usuário/experiência do usuário definidos neles que não são inspecionáveis a partir de propriedades clássicas de estado e estilo da janela (como uma barra de título oculta automaticamente).

Por padrão, um apresentador é criado pelo sistema e aplicado a uma AppWindow no momento da criação. No SDK de Aplicativos do Windows 1.0, na área de trabalho do Windows, o tipo de apresentador é OverlappedPresenter, que é uma subclasse de AppWindowPresenter. Não há necessidade de seu aplicativo ocultá-lo, nem de manter uma referência a ele para voltar ao apresentador padrão para uma janela depois de ter aplicado outro apresentador. Isso ocorre porque o sistema mantém a mesma instância desse apresentador durante o tempo de vida do AppWindow para o qual ele foi criado, e seu aplicativo pode reaplicá-lo chamando o método AppWindow.SetPresenter com AppWindowPresenterKind.Default como parâmetro.

Um apresentador pode ser aplicado a apenas uma única janela de cada vez. Tentar aplicar o mesmo apresentador a uma segunda janela gera uma exceção. Isso significa que se você tiver várias janelas e quiser alternar cada uma para um modo de apresentação específico, precisará criar vários apresentadores do mesmo tipo e, em seguida, aplicar cada um à sua própria janela.

Alguns apresentadores têm funcionalidade que permite que um usuário faça alterações fora do controle do aplicativo. Quando essa alteração acontece, seu aplicativo é notificado por um evento AppWindow.Changed na AppWindow afetada, com a propriedade AppWindowChangedEventArgs.DidPresenterChange definida como true. Seu aplicativo deve inspecionar a propriedade do apresentador aplicado para ver o que mudou.

O apresentador aplicado é um objeto dinâmico. Uma alteração em qualquer propriedade do objeto AppWindow.Presenter entra em vigor imediatamente.

Um apresentador não pode ser destruído enquanto é aplicado a uma janela. Para destruir um objeto de apresentador, primeiro aplique um objeto de apresentador diferente à janela. Dessa forma, o apresentador que você pretende destruir é removido da janela. Você pode fazer isso aplicando outro apresentador específico à janela ou chamando o método AppWindow.SetPresenter com AppWindowPresenterKind.Default como um argumento, que reaplicará o apresentador padrão criado pelo sistema à janela. Se acontecer de você manter uma referência ao apresentador criado pelo sistema para a janela, ela será válida neste ponto (ou seja, a instância que foi criada primeiro para a janela será reaplicada).

Apresentadores disponíveis

Esses apresentadores derivados do AppWindowPresenter são fornecidos e estão disponíveis em todas as versões do sistema operacional com suporte.

  • CompactOverlayPresenter. Cria uma janela sempre visível de um tamanho fixo, com uma proporção de 16:9 para permitir experiências semelhantes a picture-in-picture.
  • FullScreenPresenter. Permite que uma janela entre em uma experiência de tela cheia.
  • OverlappedPresenter. O apresentador padrão criado pelo sistema, que permite que você solicite e reaja para minimizar/maximizar/restaurar operações e alterações de estado.

Estrutura da IU e interoperabilidade HWND

A classe AppWindow está disponível para qualquerHWND de nível superior em seu aplicativo. Isso significa que, quando você estiver trabalhando com uma estrutura de interface do usuário da área de trabalho (incluindo WinUI 3), poderá continuar a usar o ponto de entrada dessa estrutura para criar uma janela e anexar seu conteúdo. E depois de criar uma janela com essa estrutura de interface do usuário, você pode usar as funções de interoperabilidade de janela (veja abaixo) fornecidas no SDK de Aplicativos do Windows para acessar o AppWindow correspondente e seus métodos, propriedades e eventos.

Alguns dos benefícios de usar AppWindow (mesmo ao trabalhar com uma estrutura de interface do usuário) são:

  • Fácil personalização da barra de título; que, por padrão, mantém a interface do usuário do Windows 11 (cantos arredondados, menu suspenso de grupo de ajustes).
  • Experiências de sobreposição em tela cheia compactas (picture-in-picture) fornecidas pelo sistema.
  • Superfície da API de Windows Runtime (WinRT) para alguns dos principais conceitos de janelas do Win32.

Exemplo de código

Este exemplo de código demonstra como recuperar um Microsoft.UI.Windowing.AppWindow de uma janela WinUI 3 usando a propriedade Microsoft.UI.Xaml.Window.AppWindow. Para usar o exemplo, crie um novo projeto de Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) e cole o código.

Para obter detalhes adicionais sobre como trabalhar com AppWindow, consulte o exemplo de galeria de janelas.

// 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!");
    }
}

Exemplo de código para versões do SDK de Aplicativos do Windows anteriores a 1.3 (ou outras estruturas de aplicativos da área de trabalho)

A propriedade Microsoft.UI.Xaml.Window.AppWindow (usada no exemplo de código acima) está disponível no SDK de Aplicativos do Windows versão 1.3 e posteriores. Para versões anteriores, você pode usar o exemplo de código com funcionalidade equivalente nesta seção.

C#. Os wrappers do .NET para as funções de interoperabilidade de janelas são implementados como métodos da classe Microsoft.UI.Win32Interop. Consulte também Chamar APIs de interoperabilidade com um aplicativo .NET.

C++. As funções de interoperabilidade são definidas no arquivo de cabeçalho winrt/Microsoft.ui.interop.h.

A seção Exemplo de código abaixo mostra o código-fonte real, mas aqui está a receita para recuperar um objeto AppWindow dada uma janela existente:

  1. Recupere o HWND para seu objeto de janela existente (para sua estrutura de interface do usuário), se você ainda não o tiver.
  2. Passe esse HWND para a função de interoperabilidade GetWindowIdFromWindow para recuperar um WindowId.
  3. Passe esse WindowId para o método estático AppWindow.GetFromWindowId para recuperar o 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!");
    }
}

Limitações

  • AppWindow é uma API WinUI 3. Isso significa que ele está disponível apenas para aplicativos de desktop (empacotados e não empacotados) e não está disponível para aplicativos UWP.
  • No momento, o SDK de Aplicativos do Windows não fornece métodos para anexar conteúdo da estrutura da interface do usuário a um AppWindow. Mas veja a seção Exemplo de código.
  • A personalização da barra de título é suportada no Windows 11 e posterior; e no Windows 10 para a versão 1.2 e posterior do SDK de Aplicativos do Windows. Para obter detalhes, consulte Personalização da barra de título.