Gérer les fenêtres d’application (SDK d'application Windows)

  • Article

Cette rubrique contient une section Exemple de code.

Le SDK d'application Windows fournit la classe Microsoft.UI.Windowing.AppWindow, simple d'utilisation. AppWindow est indépendant du cadre de travail et est disponible pour toutes les applications Windows, y compris Win32, WPF et WinForms. Vous pouvez comparer la nature indépendant du cadre de travail d'AppWindow à Microsoft.UI.Xaml.Window, qui est la classe de fenêtre spécifique au cadre WinUI 3. AppWindow est également une évolution de Windows.UI.WindowManagement.AppWindow de la plateforme Windows universelle (UWP).

La version SDK d'application Windows de Microsoft.UI.Windowing.AppWindow ne repose pas sur des modèles asynchrones et fournit à votre application un retour d’expérience immédiat sur la réussite des appels d'API.

Bien démarrer avec WinUI et utiliser le Kit de développement logiciel (SDK) d’application Windows dans un projet existant.

La classe AppWindow

Microsoft.UI.Windowing.AppWindow est une API de fenêtrage de haut niveau qui permet des scénarios de fenêtrage simple d'utilisation. AppWindow s'intègre bien à l'IU de Windows et à d'autres applications.

AppWindow représente une abstraction de haut niveau d'un conteneur géré par le système pour le contenu d'une application. Il s'agit du conteneur dans lequel votre contenu est hébergé et qui représente l'entité avec laquelle les utilisateurs interagissent lorsqu'ils redimensionnent et déplacent votre application à l'écran. Si vous connaissez Win32, la fenêtre d'application peut être considérée comme une abstraction de haut niveau du HWND. Si vous connaissez UWP, la fenêtre d’application peut être considérée comme un remplacement de CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Pour la version du SDK d'application Windows de Microsoft.UI.Windowing.AppWindow, nous ne prenons en charge que les HWND de premier niveau. Il existe un mappage 1:1 entre une AppWindow et un HWND de premier niveau.

La durée de vie d'un objet AppWindow et d'un HWND est la même : l'AppWindow est disponible immédiatement après la création de la fenêtre et il est détruit lorsque la fenêtre est fermée.

La classe AppWindowPresenter et ses sous-classes

Chaque AppWindow a un AppWindowPresenter (présentateur) qui lui est appliqué. Si vous êtes un développeur UWP qui a travaillé avec Windows.UI.WindowManagement.AppWindow, cela vous sera familier, même s'il ne s'agit pas d'un mappage 1:1 de la fonctionnalité et du comportement. Consultez également Migration de la fonctionnalité de fenêtrage.

En tant que nouveau concept pour le modèle d'application Win32, un présentateur est semblable à (mais pas identique à) une combinaison d’état de fenêtre et de styles. Certains présentateurs définissent également des comportements UI/UX qui ne peuvent pas être inspectés à partir des propriétés classiques d'état et de style de la fenêtre (par exemple, une barre de titre qui se masque automatiquement).

Par défaut, un présentateur est créé par le système et appliqué à une AppWindow au moment de sa création. Dans le SDK d'application Windows 1.0, sur le bureau Windows, le type de présentateur est OverlappedPresenter, qui est une sous-classe de AppWindowPresenter. Il n'est pas nécessaire que votre application le conserve, ni qu'elle y fasse référence pour revenir au présentateur par défaut d'une fenêtre après avoir appliqué un autre présentateur. En effet, le système conserve la même instance de ce présentateur pendant toute la durée de vie de l'AppWindow pour laquelle elle a été créée ; votre application peut la réappliquer en appelant la méthode AppWindow.SetPresenter avec AppWindowPresenterKind.Default comme paramètre.

Un présentateur ne peut être appliqué qu’à une seule fenêtre à la fois. Essayer d’appliquer le même présentateur à une deuxième fenêtre lève une exception. Cela signifie que si vous disposez de plusieurs fenêtres et que vous souhaitez faire passer chacune d'entre elles dans un mode de présentation spécifique, vous devez créer plusieurs présentateurs du même type, puis appliquer chacun d'entre eux à sa propre fenêtre.

Certains présentateurs disposent de fonctionnalités qui permettent à un utilisateur d’apporter des modifications en dehors du contrôle de votre application. Lorsqu’une telle modification se produit, votre application est avertie par un événement AppWindow.Changed sur l’AppWindow affecté, avec le jeu de propriétés AppWindowChangedEventArgs.DidPresenterChange défini sur true. Votre application doit ensuite inspecter la propriété du présentateur appliqué pour voir ce qui a changé.

Le présentateur appliqué est un objet en direct. Une modification apportée à n’importe quelle propriété de l’objet AppWindow.Presenter prend effet immédiatement.

Un présentateur ne peut pas être détruit lorsqu’il est appliqué à une fenêtre. Pour détruire un objet présentateur, appliquez d’abord un autre objet présentateur à la fenêtre ; ainsi, le présentateur que vous envisagez de détruire est supprimé de la fenêtre. Vous pouvez le faire en appliquant un autre présentateur spécifique à la fenêtre, ou en appelant la méthode AppWindow.SetPresenter avec AppWindowPresenterKind.Default comme argument, qui réapplique le présentateur créé par le système par défaut à la fenêtre. Si vous avez dû conserver une référence au présentateur créé par le système pour la fenêtre, il sera valide à ce stade (autrement dit, l’instance qui a été créée pour la première fois pour la fenêtre est réappliquée).

Présentateurs disponibles

Ces présentateurs dérivés d’AppWindowPresenter sont fournis et sont disponibles sur toutes les versions de système d’exploitation prises en charge.

  • CompactOverlayPresenter. Crée une fenêtre toujours visible de taille fixe, avec un format 16:9 pour permettre des expériences de type image dans l'image.
  • FullScreenPresenter. Permet à une fenêtre d’accéder à une expérience en plein écran.
  • OverlappedPresenter. Présentateur par défaut créé par le système, qui vous permet de demander et de réagir pour réduire/agrandir/restaurer les opérations et les modifications d’état.

Infrastructure d’interface utilisateur et interopérabilité HWND

La classe AppWindow est disponible pour n’importe quel HWND de niveau supérieur dans votre application. Cela signifie que lorsque vous travaillez avec une infrastructure d’interface utilisateur de bureau (y compris WinUI 3), vous pouvez continuer à utiliser le point d'entrée de cette interface pour créer une fenêtre et y attacher son contenu. Une fois que vous avez créé une fenêtre avec cette infrastructure d’interface utilisateur, vous pouvez utiliser les fonctions d'interopérabilité de fenêtrage (voir ci-dessous) fournies dans SDK d'application Windows pour accéder à l’AppWindow correspondante et à ses méthodes, propriétés et événements.

Certains des avantages de l’utilisation d’AppWindow (même quand vous utilisez une infrastructure d’interface utilisateur) sont les suivants :

  • Personnalisation de la barre de titre facile ; qui gère par défaut l’interface utilisateur Windows 11 (coins arrondis, contrôle suspendu du groupe d’ancrage).
  • Expériences de superposition plein écran et compact fournies par le système (image dans l'image).
  • Surface de l’API Windows Runtime (WinRT) pour certains des principaux cœurs de fenêtrage Win32.

Exemple de code

Cet exemple de code montre comment récupérer un Microsoft.UI.Windowing.AppWindow à partir d’une fenêtre WinUI 3 à l’aide de la propriété Microsoft.UI.Xaml.Window.AppWindow. Pour utiliser l’exemple, créez un projet Application vide, Empaquetée (WinUI 3 dans le bureau) et collez le code.

Pour plus de détails sur la façon de travailler avec AppWindow, consultez l'exemple de galerie des fenêtres.

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

Exemple de code pour les versions SDK d'application Windows antérieures à la version 1.3 (ou à d’autres infrastructures d’application bureautique)

La propriété Microsoft.UI.Xaml.Window.AppWindow (utilisée dans l’exemple de code ci-dessus) est disponible dans la version SDK d'application Windows 1.3 et ultérieure. Pour les versions antérieures, vous pouvez utiliser l’exemple de code équivalent en termes de fonctionnalités dans cette section.

C#. Les wrappers .NET pour les fonctions d’interopérabilité de fenêtrage sont implémentés en tant que méthodes de la classe Microsoft.UI.Win32Interop. Consultez également Appeler des API interop à partir d'une application .NET.

C++. Les fonctions d’interopérabilité sont définies dans le fichier d'en-tête winrt/Microsoft.ui.interop.h.

La section Exemple de code ci-dessous montre le code source réel ; mais voici la recette permettant de récupérer un objet AppWindow en fonction d’une fenêtre existante :

  1. Récupérez le HWND pour votre objet de fenêtre existant (pour votre infrastructure d’interface utilisateur), si vous ne l’avez pas déjà.
  2. Passez ce HWND à la fonction d’interopérabilité GetWindowIdFromWindow pour récupérer un WindowId..
  3. Transmettez ce WindowId à la méthode Statique AppWindow.GetFromWindowId pour récupérer l’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!");
    }
}

Limites

  • AppWindow est une API WinUI 3. Cela signifie qu’elle est disponible uniquement pour les applications bureautique (empaquetées et non empaquetées) ; et n’est pas disponible pour les applications UWP.
  • Le SDK d'application Windows ne fournit actuellement pas de méthodes permettant d’attacher du contenu d’infrastructure d’interface utilisateur à un AppWindow. Mais consultez la section Exemple de code.
  • La personnalisation de la barre de titre est prise en charge dans Windows 11 et versions ultérieures ; et dans Windows 10 pour la version 1.2 et ultérieure du SDK d'application Windows. Pour plus de détails, consultez Personnalisation de la barre de titre.