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 Windows App SDK fournit une classe Microsoft.UI.Windowing.AppWindow basée sur le modèle HWND Win32. Cette classe AppWindow est la version du Windows App SDK des éléments ApplicationView, CoreWindow et AppWindow de l'UWP.

Pour tirer parti des API de fenêtrage Windows App SDK, vous allez migrer votre code UWP pour utiliser le modèle Win32. Pour plus d’informations sur Windows App SDK AppWindow, consultez Manage app windows.

Types de fenêtres dans UWP et Windows App SDK

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 l’Windows App SDK dépend des 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 auront moins de travail à faire pour migrer que les applications ApplicationView/CoreWindow vers Windows App SDK AppWindow.

type de fenêtre Windows App SDK

• 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 que les différences entre les modèles de fenêtrage entre UWP et Win32 signifient qu'il n'existe pas de mappage direct 1:1 entre l'API UWP surface et l'API Windows App SDK surface. 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

Lorsque vous migrez de UWP vers le Windows App SDK, 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 dans une superposition compacte ou en plein écran doivent tirer parti de la Windows App SDK AppWindowPresenter. 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 des présentateurs de fenêtres d'application UWP aux présentateurs de fenêtres d'application du Windows App SDK. Si vous avez une application UWP ApplicationView/CoreWindow, vous pouvez toujours avoir une fenêtre flottante compacte (picture-in-picture) ou des expériences de gestion de fenêtres 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 Windows App SDK prend uniquement en charge l’expérience en plein écran la plus restrictive (autrement dit, quand FullScreen est 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être d’application, consultez l’exemple de la galerie Windowing. 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. Si, en revanche, votre application UWP a une barre de titre personnalisée, il est possible de recréer les scénarios suivants dans votre application Windows App SDK.

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

Code qui utilise le ApplicationViewTitleBar, CoreApplicationViewTitleBar, et AppWindowTitleBar migre vers la classe Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar.

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

Voici un tableau des API de personnalisation des couleurs.

Ces API Windows App SDK sont destinées à une personnalisation supplémentaire de 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 Windows App SDK 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 UWP AppWindow n’ont aucun mappage direct 1:1 à une API Windows App SDK.

• Visibilité de la Barre de Titre de la Fenêtre de l'Application. 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 de AppWindowTitleBar, consultez l’exemple de galerie Windowing. 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 du code de gestion des événements de changement de taille, vous devez basculer vers la propriété Windows App SDK AppWindowChangedEventArgs.DidSizeChange. La valeur est true si la taille de la fenêtre d’application a changé, false sinon.

MainPage et MainWindow

Lorsque vous créez une project UWP dans Visual Studio, le modèle project 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 project vous fournit également du code de navigation dans les méthodes de la classe App.

Lorsque vous créez une Windows App SDK project dans Visual Studio, le modèle project vous fournit une classe MainWindow (de type Microsoft.UI.Xaml.Window), mais aucune Page. Et 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 Windows App SDK project. Par exemple, vous pouvez ajouter un nouvel élément de page à l’project (WinUI>Blank Page (WinUI)), puis le nommer MainPage.xaml ou un autre nom. Cela ajouterait à votre project 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 Ai-je besoin d’implémenter la navigation de page ?.

Pour des applications Windows App SDK suffisamment simples, vous n'avez pas besoin de créer des pages ou des contrôles utilisateur, et vous pouvez copier votre code XAML et 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 UWP Windows.UI.Core.CoreWindow migrent vers la classe Windows App SDK Microsoft.UI.Xaml.Window.

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

• Windows App SDK et versions Windows prises en charge
• Migrer votre fonctionnalité de threading