Gerenciar janelas do aplicativo

O SDK do Aplicativo do Windows fornece a classe Microsoft.UI.Windowing.AppWindow que representa uma abstração de alto nível do HWND. Há um mapeamento 1:1 entre um AppWindow e um HWND de nível superior em seu aplicativo. AppWindow e suas classes relacionadas fornecem APIs que permitem gerenciar muitos aspectos das janelas de nível superior do aplicativo sem a necessidade de acessar o HWND diretamente.

Observação

Este artigo demonstra como usar AppWindow APIs em seu aplicativo. Como pré-requisito, recomendamos que você leia e entenda as informações do AppWindow na Visão geral de janelas do WinUI e do SDK de Aplicativos do Windows, que é aplicável se você usa a WinUI ou outra estrutura de interface do usuário.

• APIs importantes: AppWindow classe, classe OverlappedPresenter

Abra o aplicativo da Galeria do WinUI 3 e veja AppWindow em ação

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub

Você pode usar AppWindow APIs com qualquer estrutura de interface do usuário compatível com o SDK de Aplicativo do Windows – WinUI 3, WPF, WinForms ou Win32. AppWindow As APIs funcionam junto com as APIs de janela específicas da estrutura:

• XAML Window
• WPF Window
• Formulário do Windows Forms
• APIs de janela Win32, Windows MFC

Normalmente, você usa AppWindow APIs para:

• Gerencie o tamanho e a posição da janela do aplicativo.

• Gerenciar o título da janela, o ícone e a cor da barra de título; ou crie uma barra de título totalmente personalizada com APIs AppWindowTitleBar .

  Consulte Personalização da barra de título para obter mais informações e exemplos.

• Gerencie a aparência e o comportamento da janela com APIs derivadas de AppWindowPresenter.

Responda às alterações do AppWindow

Você responde às alterações ao AppWindow manipulando o único evento Alterado e, posteriormente, verificando os argumentos do evento (AppWindowChangedEventArgs) para determinar que tipo de alteração ocorreu. Se a alteração na qual você está interessado aconteceu, você pode responder a ela. As alterações potenciais incluem posição, tamanho, apresentador, visibilidade e ordem z.

Aqui está um exemplo de um manipulador de eventos AppWindow.Changed.

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    // ConfigText and SizeText are TextBox controls defined in XAML for the page.
    if (args.DidPresenterChange == true)
    {
        ConfigText.Text = sender.Presenter.Kind.ToString();
    }

    if (args.DidSizeChange == true)
    {
        SizeText.Text = sender.Size.Width.ToString() + ", " + sender.Size.Height.ToString();
    }
}

Window tamanho e posicionamento

A AppWindow classe tem várias propriedades e métodos que você pode usar para gerenciar o tamanho e o posicionamento da janela.

Categoria	Propriedades
Propriedades somente leitura	Posição, tamanho, clientSize
Eventos	Alterado (MudançaDePosição, MudançaDeTamanho)
Métodos de tamanho e posição	Mover, Redimensionar, ResizeClient, MoveAndResize
Métodos de ordem Z	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Chame Redimensionar para especificar um novo tamanho de janela.

Neste exemplo, o código está dentro MainWindow.xaml.cs, para que você possa usar a Windowpropriedade .AppWindow para obter a AppWindow instância.

public MainWindow()
{
    InitializeComponent();
    AppWindow.Resize(new Windows.Graphics.SizeInt32(1200, 800));
}

Chame o método Move para alterar a posição de uma janela.

Este exemplo move a janela para ser centralizada na tela quando o usuário clica em um botão.

Isso ocorre no arquivo de código de uma classe Page, então você não tem acesso automático aos objetos Window ou AppWindow. Você tem algumas opções para obter o AppWindow.

• Se você mantiver uma referência ao Window conforme descrito em Acompanhar a janela atual ou Rastrear instâncias de Window, você poderá obter o Window e obter AppWindow da Window. Propriedade AppWindow
• Ou você pode chamar o método estático AppWindow.GetFromWindowId para obter a AppWindow instância, como mostrado aqui. (Consulte Determinando a janela que está hospedando um elemento visual.)

private void MoveWindowButton_Click(object sender, RoutedEventArgs e)
{
    AppWindow appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    RectInt32? area = DisplayArea.GetFromWindowId(appWindow.Id, DisplayAreaFallback.Nearest)?.WorkArea;
    if (area == null) return;
    appWindow.Move(new PointInt32((area.Value.Width - appWindow.Size.Width) / 2, (area.Value.Height - appWindow.Size.Height) / 2));
}

A classe AppWindowPresenter e suas subclasses

Cada AppWindow tem um AppWindowPresenter (apresentador) aplicado a ele. Um apresentador é criado pelo sistema e aplicado a um AppWindow no momento da criação. Cada sub-classe de AppWindowPresenter fornece uma configuração predefinida apropriada para a finalidade da janela. Esses apresentadores derivados do AppWindowPresenter são fornecidos e estão disponíveis em todas as versões do sistema operacional com suporte.

• CompactOverlayPresenter

  Configura 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. Por padrão, InitialSize é CompactOverlaySize.Small, mas você pode alterá-lo para Medium ou Large. Você também pode chamar AppWindow.Redimensionar para substituir a taxa de proporção 16:9 e ajustar a janela para qualquer tamanho desejado.

• FullScreenPresenter

  Configura uma janela para fornecer uma experiência de tela inteira adequada para assistir a vídeos. A janela não tem uma borda ou barra de título e oculta a barra de tarefas do sistema.

• SobrepostoPresenter

  A configuração de janela padrão, que normalmente fornece uma borda com alças de redimensionamento e uma barra de título com botões de minimizar/maximizar/restaurar.

Observação

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

O apresentador padrão

O apresentador padrão aplicado quando um AppWindow é criado é uma instância de OverlappedPresenter com configurações de propriedade padrão. Não há necessidade 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 você pode reaplicá-lo chamando o método AppWindow.SetPresenter com AppWindowPresenterKind.Default como parâmetro.

Importante

Chamar SetPresenter(AppWindowPresenterKind.Default) sempre restaura a instância padrão do apresentador que é criada com o AppWindow. Se você criar e aplicar outro apresentador e quiser reaplicá-lo mais tarde, será necessário manter uma referência ao seu apresentador.

Você também pode obter uma referência à instância padrão do apresentador e modificá-la. Se você aplicou um novo apresentador, primeiro verifique se o apresentador padrão foi aplicado, conforme mostrado aqui:

appWindow.SetPresenter(AppWindowPresenterKind.Default);
OverlappedPresenter defaultPresenter = (OverlappedPresenter)appWindow.Presenter;
defaultPresenter.IsMaximizable = false;
defaultPresenter.IsMinimizable = false;

Modificar um OverlappedPresenter

O OverlappedPresenter é um apresentador flexível que você pode configurar de várias maneiras.

Os métodos Create* permitem que você crie um apresentador sobreposto com configurações de propriedade padrão ou um com configurações de propriedade pré-configuradas para um uso específico.

Esta tabela mostra como as propriedades de configuração são definidas quando você cria um objeto OverlappedPresenter de cada método.

Propriedade	Create	CreateForContextMenu	CreateForDialog	CreateForToolWindow
HasBorder	true	true	true	true
HasTitleBar	true	false	true	true
IsAlwaysOnTop	false	false	false	false
IsMaximizable	true	false	false	true
IsMinimizable	true	false	false	true
IsModal	false	false	false	false
IsResizable	true	false	false	true

O apresentador aplicado é um objeto dinâmico. Uma alteração em qualquer propriedade do AppWindow.Presenter entra em vigor imediatamente. Não há eventos para notificá-lo dessas alterações, mas você pode verificar as propriedades dos valores atuais a qualquer momento.

As propriedades HasBorder e HasTitleBar são somente leitura. Você pode definir esses valores chamando o método SetBorderAndTitleBar (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)). Um OverlappedPresenter não pode ter uma barra de título sem uma borda. Ou seja, se o hasTitleBar parâmetro for true, o hasBorder parâmetro também deverá ser true. Caso contrário, uma exceção será gerada com esta mensagem:

The parameter is incorrect.
Invalid combination: Border=false, TitleBar=true.

Defina IsMaximizable para false ocultar o botão maximizar na barra de ferramentas. Recomendamos que você faça isso se definir as propriedades PreferredMaximumHeight ou PreferredMaximumWidth, pois essas propriedades restringem o tamanho da janela mesmo no estado maximizado. Isso não afeta as chamadas para o método Maximize .

Defina IsMinimizable para false ocultar o botão minimizar na barra de ferramentas. Isso não afeta as chamadas para o método Minimize .

Defina IsResizable para false ocultar os controles de redimensionamento e impedir que o usuário redimensione a janela. Isso não afeta as chamadas para o método AppWindowResize.

Defina IsAlwaysOnTop para true manter essa janela em cima de outras janelas. Se você chamar qualquer um dos AppWindow.MoveInZOrder* métodos, eles ainda terão efeito para alterar a ordem z da janela, mesmo que essa propriedade seja true.

Defina PreferredMaximumHeight e PreferredMaximumWidth para restringir o tamanho máximo para o qual o usuário pode esticar a janela. Recomendamos que você defina IsMaximizablefalse se definir as propriedades de tamanho máximo, pois essas propriedades restringem o tamanho da janela mesmo no estado maximizado. Essas propriedades também afetam chamadas para AppWindow. Redimensionar; a janela não será redimensionada maior que a altura e a largura máxima especificadas.

Defina PreferredMinimumHeight e PreferredMinimumWidth para definir o tamanho mínimo para o qual o usuário pode reduzir a janela. Essas propriedades também afetam chamadas para AppWindow. Redimensionar; a janela não será redimensionada menor que a altura e a largura mínimas especificadas.

Janelas modais

Você pode definir IsModal para true criar uma janela modal. Uma janela modal é uma janela separada que bloqueia a interação com a janela do proprietário até que ela seja fechada. No entanto, para criar uma janela modal, você também deve definir a janela de proprietário; caso contrário, uma exceção é gerada com esta mensagem:

The parameter is incorrect.

The window should have an owner when IsModal=true.

Para definir a janela de proprietário em um aplicativo WinUI, é necessário interoperabilidade do Win32. Para obter mais informações e código de exemplo, consulte a AppWindow página no aplicativo de exemplo da Galeria WinUI.

• Iniciar o aplicativo da Galeria do WinUI
• Abrir ModalWindow.xaml.cs no GitHub

Aplicar um apresentador

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.

Quando um novo apresentador é aplicado (a propriedade AppWindow.Presenter muda), seu aplicativo é notificado por um evento AppWindow.Changed no AppWindow afetado, com a propriedade AppWindowChangedEventArgs.DidPresenterChange definida como true.

Dica

Se você aplicar um apresentador modificado e permitir a alteração entre os apresentadores, mantenha uma referência ao apresentador modificado para que ele possa ser reaplicado ao AppWindow.

Este exemplo mostra como fazer o seguinte:

• Use a propriedade AppWindow.Presenter para obter o apresentador atual.
• Use a propriedade AppWindowPresenter.Kind para verificar que tipo de configuração está aplicada no momento.
• Chame AppWindow.SetPresenter para alterar a configuração atual.

Aqui, um apresentador é criado, modificado e aplicado no construtor da janela.

OverlappedPresenter presenter = OverlappedPresenter.Create();
presenter.PreferredMinimumWidth = 420;
presenter.PreferredMinimumHeight = 550;
AppWindow.SetPresenter(presenter);

Na Página que é o conteúdo da janela, você pode obter uma referência ao AppWindow e ao apresentador aplicado.

AppWindow appWindow;
OverlappedPresenter modifiedPresenter;

private void AppWindowPage_Loaded(object sender, RoutedEventArgs e)
{
    appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    modifiedPresenter = (OverlappedPresenter)appWindow.Presenter;

    appWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        // ConfigText is a TextBox control defined in XAML for the page.
        ConfigText.Text = appWindow.Presenter.Kind.ToString();
    }
}

private void CompactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.CompactOverlay)
    {
        appWindow.SetPresenter(CompactOverlayPresenter.Create());
        fullScreenButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

private void FullScreenButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.FullScreen)
    {
        appWindow.SetPresenter(FullScreenPresenter.Create());
        compactOverlayButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

Estrutura da IU e interoperabilidade HWND

A classe AppWindow está disponível para qualquer HWND de nível superior no 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 janelas (veja abaixo), fornecidas no SDK do Aplicativo do Windows, para acessar o AppWindow correspondente e seus métodos, propriedades e eventos.

Alguns dos benefícios do uso 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.

Obtenha a AppWindow para versões do SDK de Aplicativos do Windows anteriores a 1.3 (ou outras estruturas de aplicativos da área de trabalho)

A Windowpropriedade .AppWindow está disponível no Windows App SDK versão 1.3 e posterior. 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 janela 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 de exemplo de código abaixo mostra o código-fonte real; mas aqui está a receita para recuperar um AppWindow objeto dada uma janela existente:

1. Recupere o HWND para o objeto de janela existente (para sua estrutura de interface do usuário), caso ainda não o tenha.
2. Passe esse HWND para a função de interoperabilidade GetWindowIdFromWindow para recuperar o identificador WindowId.
3. Passe essa 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!");
    }
}

Para obter mais exemplos de como trabalhar com AppWindow, consulte o exemplo de Windowing gallery.

Limitações

Atualmente, o SDK do Aplicativo do Windows não fornece métodos para anexar o conteúdo da estrutura da interface do usuário a um AppWindow.

Tópicos relacionados

• Visão geral de janelas
• Personalização da barra de título
• Migração da funcionalidade de janela
• Chamar as APIs de interoperabilidade com um aplicativo .NET
• Recuperar um identificador de janela (HWND)
• Exemplo de galeria de janelas