Migration des fonctionnalités de fenêtre

Cette rubrique contient des conseils relatifs à la gestion des fenêtres, notamment la migration de l’ApplicationView/CoreWindow ou AppWindow d’UWP vers le Microsoft.UI.Windowing.AppWindow du SDK d’application Windows.

API importantes

• Microsoft.UI.Windowing.AppWindow
• Propriété Windows.UI.Core.CoreWindow.Dispatcher
• Propriété Microsoft.UI.Window.DispatcherQueue

Résumé des différences d’API et/ou de fonctionnalités

Le SDK d’application Windows fournit une classe Microsoft.UI.Windowing.AppWindow basée sur le modèle Win32 HWND. Cette classe AppWindow est la version du SDK d’application Windows d’ApplicationView/CoreWindow et AppWindow d’UWP.

Pour tirer parti des API de fenêtrage du SDK d’application Windows, vous serez amené à migrer votre code UWP pour utiliser le modèle Win32. Pour plus d’informations sur l’AppWindow du SDK d’application Windows, consultez Gérer les fenêtres d’application.

Types de fenêtres dans UWP par rapport au SDK d’application Windows

Dans une application UWP, vous pouvez héberger du contenu de fenêtre en utilisant ApplicationView/CoreWindow ou AppWindow. Le travail impliqué dans la migration de ce code vers le SDK d’application Windows dépend de l’un de ces deux modèles de fenêtrage que votre application UWP utilise. Si vous êtes familiarisé avec le Windows.UI.WindowManagement.AppWindow d’UWP, vous pouvez voir des similitudes entre celui-ci et Microsoft.UI.Windowing.AppWindow.

Types de fenêtres UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow regroupe le thread d’interface utilisateur et la fenêtre que l’application utilise pour afficher le contenu. Les applications UWP qui utilisent AppWindow ont moins de travail à faire que les applications ApplicationView/CoreWindow pour migrer vers l’AppWindow du SDK d’application Windows.

Type de fenêtre du SDK d’application Windows

• Microsoft.UI.Windowing.AppWindow est l’abstraction de haut niveau d’un conteneur géré par le système du contenu d’une application.

N’oubliez pas qu’en raison des différences de modèles de fenêtrage entre UWP et Win32, il n’y a pas de mappage 1:1 direct entre la surface de l’API UWP et la surface de l’API du SDK d’application Windows. Même pour les noms de classes et de membres qui sont effectivement repris d’UWP (comme le montrent les tableaux de correspondance de cette rubrique), le comportement peut également différer.

Écrans de démarrage

Contrairement aux applications UWP, les applications Win32 n’affichent pas par défaut d’écran de démarrage au lancement. Les applications UWP qui s’appuient sur cette fonctionnalité pour leur expérience de lancement peuvent choisir d’implémenter une transition personnalisée vers la première fenêtre d’application.

Créer, afficher, fermer et détruire une fenêtre

La durée de vie d’un Microsoft.UI.Windowing.AppWindow est la même que pour un HWND. Cela signifie que l’objet AppWindow est disponible immédiatement après la création de la fenêtre et est détruit quand la fenêtre est fermée.

Créer et afficher

AppWindow.Create crée une fenêtre d’application avec la configuration par défaut. La création et l’affichage d’une fenêtre sont uniquement nécessaires pour les scénarios où vous n’utilisez pas d’infrastructure d’interface utilisateur. Si vous migrez votre application UWP vers une infrastructure d’interface utilisateur compatible avec Win32, vous pouvez toujours atteindre votre objet AppWindow à partir d’une fenêtre déjà créée en utilisant les méthodes d’interopérabilité de fenêtrage.

Fermer

Dans UWP, ApplicationView.TryConsolidateAsync est l’équivalent programmatique du lancement du mouvement de fermeture par l’utilisateur. Ce concept de regroupement (dans le modèle de fenêtrage ApplicationView/CoreWindow d’UWP) n’existe pas dans Win32. Win32 n’exige pas que les fenêtres existent dans des threads distincts. Pour répliquer le modèle de fenêtrage ApplicationView/CoreWindow d’UWP, le développeur doit créer un thread et y créer une fenêtre. Sous le modèle Win32, le comportement système par défaut est Fermer>Masquer>Détruire.

Personnalisation de la fenêtre de base

Quand vous migrez d’UWP vers le SDK d’application Windows, vous pouvez vous attendre à la même expérience à partir de votre AppWindow par défaut. Toutefois, si nécessaire, vous pouvez changer le Microsoft.UI.Windowing.AppWindow par défaut pour des expériences de fenêtrage personnalisées. Pour plus d’informations sur la personnalisation de vos fenêtres, consultez Microsoft.UI.Windowing.AppWindow .

Redimensionnement d’une fenêtre

Positionnement d’une fenêtre

Titre de fenêtre

Superposition compacte et plein écran

Les applications qui entrent en superposition compacte, ou en plein écran, doivent tirer parti de l’AppWindowPresenter du SDK d’application Windows. Si vous connaissez l’AppWindow d’UWP, vous connaissez peut-être déjà le concept des présentateurs.

Il n’existe pas de mappage 1:1 des fonctionnalités et du comportement entre les présentateurs de fenêtre d’application UWP et les présentateurs de fenêtre d’application du SDK d’application Windows. Si vous avez une application UWP ApplicationView/CoreWindow, vous pouvez toujours avoir une superposition compacte (incrustation) ou des expériences de fenêtrage en plein écran dans votre application, mais le concept de présentateurs peut être nouveau pour vous. Pour plus d’informations sur les présentateurs de fenêtre d’application, consultez Présentateurs. Par défaut, un présentateur superposé est appliqué à un AppWindow au moment de la création. CompactOverlay et FullScreen sont les seuls présentateurs disponibles, à l’exception de celui par défaut.

Superposition compacte

Si vous avez utilisé ApplicationViewMode ou AppWindowPresentionKind d’UWP pour présenter une fenêtre de superposition compacte, vous devez utiliser la superposition compacte AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter ne prend en charge que trois tailles de fenêtre fixes avec des proportions de 16:9 et ne peut pas être redimensionné par l’utilisateur. Au lieu d’ApplicationViewMode.TryEnterViewModeAsync ou AppWindowPresenterKind.RequestPresentation, vous devez utiliser AppWindow.SetPresenter pour changer la présentation de l’AppWindow.

Plein écran

Si vous avez utilisé les classes ApplicationViewWindowingMode ou AppWindowPresentionKind d’UWP pour présenter une fenêtre plein écran, vous devez utiliser l’AppWindowPresenterKind en plein écran. Le SDK d’application Windows prend uniquement en charge l’expérience plein écran la plus restrictive (c’est-à-dire, quand FullScreen a la valeur IsExclusive). Pour ApplicationView/CoreWindow, vous pouvez utiliser ApplicationView.ExitFullScreenMode pour sortir l’application du mode plein écran. Quand vous utilisez des présentateurs, vous pouvez retirer une application du mode plein écran en rétablissant le présentateur à l’état superposé/par défaut avec AppWindow.SetPresenter.

Pour plus d’informations sur l’utilisation des présentateurs de fenêtres d’application, consultez l’exemple de galerie de fenêtrages. Il montre comment activer/désactiver différents états du présentateur de fenêtre d’application.

Barre de titre personnalisée

Si votre application utilise une barre de titre par défaut, aucune tâche de barre de titre supplémentaire n’est nécessaire lors de la migration vers Win32. En revanche, si votre application UWP dispose d’une barre de titre personnalisée, il est possible de recréer les scénarios suivants dans votre application de SDK d’application Windows.

1. Personnaliser la barre de titre dessinée par le système
2. Barre de titre personnalisée dessinée par l’application

Le code qui utilise les classes ApplicationViewTitleBar, CoreApplicationViewTitleBar et AppWindowTitleBar d’UWP est migré au moyen de la classe Microsoft.UI.Windowing.AppWindowTitleBar du SDK d’application Windows.

Personnaliser la barre de titre dessinée par le système

Voici un tableau des API de personnalisation des couleurs.

Ces API du SDK d’application Windows permettent de personnaliser davantage la barre de titre dessinée par le système en plus de l’API AppWindow.Title.

• AppWindow.SetIcon. Définit la barre de titre et l’image de l’icône de la barre des tâches au moyen d’un handle hIcon ou d’un chemin de chaîne vers une ressource ou un fichier.
• AppWindowTitleBar.IconShowOptions. Obtient ou définit une valeur qui spécifie le mode d’affichage de l’icône de fenêtre dans la barre de titre. Prend en charge deux valeurs : HideIconAndSystemMenu et ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Réinitialise la barre de titre actuelle selon les paramètres par défaut de la fenêtre.

Barre de titre personnalisée dessinée par l’application (personnalisation complète)

Si vous effectuez une migration vers AppWindowTitleBar, nous vous recommandons de vérifier AppWindowTitleBar.IsCustomizationSupported dans votre code avant d’appeler les API de barre de titre personnalisée suivantes.

Ces API du SDK d’application Windows sont destinées à la personnalisation complète de la barre de titre.

• AppWindowTitleBar.SetDragRectangles. Définit les régions de glissement pour la fenêtre.
• AppWindowTitleBar.ResetToDefault. Réinitialise la barre de titre actuelle selon les paramètres par défaut de la fenêtre.

Ces API AppWindow UWP n’ont pas de mappage 1:1 direct avec une API du SDK d’application Windows.

• AppWindowTitleBarVisibility. Définit des constantes qui spécifient la visibilité préférée d’un AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Récupère le mode de visibilité préféré pour la barre de titre.
• AppWindowTitleBar.SetPreferredVisibility. Définit le mode de visibilité préféré pour la barre de titre.

Pour plus d’informations sur l’utilisation d’AppWindowTitleBar, consultez l’exemple de galerie de fenêtrages. Il montre comment créer une barre de titre de couleur personnalisée et comment dessiner une barre de titre personnalisée.

Gestion des événements

Si votre application UWP utilise l’événement AppWindow.Changed, vous pouvez migrer ce code vers l’événement Microsoft.UI.Windowing.AppWindow.Changed.

Événement de changement de taille

Lors de la migration d’un code de gestion des événements de changement de taille, vous devez basculer vers l’utilisation de la propriété AppWindowChangedEventArgs.DidSizeChange du SDK d’application Windows. La valeur est true si la taille de la fenêtre d’application a changé, false sinon.

MainPage et MainWindow

Quand vous créez un projet UWP dans Visual Studio, le modèle de projet vous fournit une classe MainPage. Pour votre application, vous avez peut-être renommé cette classe (et/ou ajouté d’autres pages et contrôles utilisateur). Le modèle de projet vous fournit également du code de navigation dans les méthodes de la classe App.

Quand vous créez un projet de SDK d’application Windows dans Visual Studio, le modèle de projet vous fournit une classe MainWindow (de type Microsoft.UI.Xaml.Window), mais aucune Page. En outre, le modèle de projet ne fournit aucun code de navigation.

Toutefois, vous avez la possibilité d’ajouter des pages et des contrôles utilisateur à votre projet de SDK d’application Windows. Par exemple, vous pouvez ajouter un nouvel élément de page au projet (WinUI>Page vierge (WinUI 3)) et le nommer MainPage.xaml ou un autre nom. Cela ajouterait à votre projet une nouvelle classe de type Microsoft.UI.Xaml.Controls.Page. Ensuite, pour plus d’informations sur l’ajout de code de navigation au projet, consultez Dois-je implémenter une navigation de page ?.

Pour les applications de SDK d’application Windows qui sont assez simples, vous n’avez pas besoin de créer des pages ou des contrôles utilisateur, et vous pouvez copier votre balisage XAML et votre code-behind dans MainWindow. Toutefois, pour plus d’informations sur les exceptions à ce workflow, consultez Gestionnaire d’état visuel et Page.Resources.

Remplacer CoreWindow.Dispatcher par Window.DispatcherQueue

Certains cas d’usage de la classe Windows.UI.Core.CoreWindow d’UWP effectuent une migration vers le Microsoft.UI.Xaml.Window du SDK d’application Windows.

Par exemple, si vous utilisez la propriété Windows.UI.Core.CoreWindow.Dispatcher dans votre application UWP, la solution n’est pas de migrer vers la propriété Microsoft.UI.Xaml.Window.Dispatcher (qui retourne toujours null). Au lieu de cela, migrez vers la propriété Microsoft.UI.Xaml.Window.DispatcherQueue, qui retourne un Microsoft.UI.Dispatching.DispatcherQueue.

Pour plus d’informations et des exemples de code, consultez Remplacer Windows.UI.Core.CoreDispatcher par Microsoft.UI.Dispatching.DispatcherQueue.

Rubriques connexes

• SDK d'application Windows et versions de Windows prises en charge
• Migrer votre fonctionnalité de threading