Migrazione della funzionalità di windowing.

Questo argomento contiene indicazioni relative alla gestione delle finestre, inclusa la migrazione da ApplicationView/CoreWindow o AppWindow della piattaforma UWP a Microsoft.UI.Windowing.AppWindow di Windows App SDK.

API importanti

• Microsoft.UI.Windowing.AppWindow
• Proprietà Windows.UI.Core.CoreWindow.Dispatcher
• Proprietà Microsoft.UI.Window.DispatcherQueue.

Riepilogo delle differenze tra API e/o funzionalità

Windows App SDK fornisce una classe Microsoft.UI.Windowing.AppWindow basata sul modello HWND di Win32. Quella classe AppWindow class è la versione Windows App SDK di ApplicationView/CoreWindow e AppWindow della piattaforma UWP.

Sfruttare le API di windowing di Windows App SDK significa che verrà eseguita la migrazione del codice UWP per utilizzare il modello Win32. Per altre informazioni su AppWindow di Windows App SDK, vedere Gestire le finestre delle app.

Differenze tra tipi di finestra nella piattaforma UWP e in Windows App SDK

In un'app UWP, è possibile ospitare contenuti della finestra utilizzando ApplicationView/CoreWindow o AppWindow. Il lavoro necessario alla migrazione di quel codice a Windows App SDK dipende da quale di questi due modelli di windowing è utilizzato dall'app UWP. Se si ha familiarità con Windows.UI.WindowManagement.AppWindow di UWP, allora si potrebbero riscontrare somiglianze con Microsoft.UI.Windowing.AppWindow.

Tipi di finestra UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida il thread dell'interfaccia utente e la finestra utilizzata dall'app per visualizzare i contenuti. Le app UWS che utilizzano AppWindow avranno meno lavoro da fare rispetto alle app ApplicationView/CoreWindow per eseguire la migrazione ad AppWindow di Windows App SDK.

Tipo di finestra Windows App SDK

• Microsoft.UI.Windowing.AppWindow è il livello di astrazione generale di un container gestito dal sistema dei contenuti di un'app.

Tenere presente che le differenze nei modelli di windowing tra UWP e Win32 indicano che non c'è un mapping 1:1 diretto tra la superficie dell'API UWP e quella dell'API Windows App SDK. Anche per nomi di classe e membro che vengono trasferiti dalla piattaforma UWP (riflessi nelle tabelle di mapping di questo argomento), il comportamento può variare.

Schermate iniziali

A differenza delle app UWP, le app Win32 non mostrano una schermata iniziale all'avvio per impostazione predefinita. Le app UWS che si affidano a questa funzionalità per l'esperienza di avvio possono scegliere di implementare una transizione personalizzata alla prima finestra di app.

Creare, mostrare, chiudere e distruggere una finestra

La durata di una Microsoft.UI.Windowing.AppWindow è la stessa di una HWND; significa che l'oggetto AppWindow è disponibile immediatamente dopo la creazione della finestra e viene distrutto una volta chiusa la finestra.

Creazione e visualizzazione

AppWindow.Create crea una finestra dell'app con la configurazione predefinita. Creare e visualizzare una finestra è necessario solo negli scenari in cui non si lavora con un framework dell'interfaccia utente. Se si esegue la mgrazione dell'app UWP a un framework dell'interfaccia utente compatibile con Win32, è comunque possibile raggiungere l'oggetto AppWindow da una finestra già creata usando i metodi di interoperabilità di windowing.

Chiusura

Nella piattaforma UWP, ApplicationView.TryConsolidateAsync a livello di codice è l'equivalente dell'utente che avvia un movimento di chiusura. Questo concetto di consolidamento (nel modello di windowing ApplicationView/CoreWindow della piattaforma UWP) non esiste in Win32. Win32 non richiede l'esistenza di finestre in thread separati. Replicare il modello di windowing ApplicationView/CoreWindow della piattaforma UWP richiederebbe allo sviluppatore la creazione di un nuovo thread contenente una nuova finestra. Nel modello Win32, il comportamento predefinito del sistema è Chiudi>Nascondi>Distruggi.

Personalizzazione della finestra di base

Quando si esegue la migrazione da UWP a Windows App SDK, si può prevedere la stessa esperienza dalla AppWindowpredefinita. Ma se occorre è possibile cambiare la Microsoft.UI.Windowing.AppWindow predefinita per esperienze di windowing personalizzate. Vedere Microsoft.UI.Windowing.AppWindow per altre informazioni su come personalizzare le finestre.

Ridimensionamento di una finestra

Posizionamento di una finestra

Titolo finestra

Sovrapposizione compatta e schermo intero

Le app che entrano in modalità sovrapposizione compatta o a schermo interno devono sfruttare AppWindowPresenter di Windows App SDK. Se si ha familiarità con AppWindow della piattaforma UWP, si potrebbe già avere familiarità con il concetto di presenter.

Non c'è un mapping 1:1 di funzionalità e comportamento dai presenter di finestre di app UWP a quelli Windows App SDK. Se si dispone di un'app UWP ApplicationView/CoreWindow. è possibile avere comunque esperienze di windowing a sovrapposizione compatta (picture-in-picture) o a schermo intero nell'app, ma il concetto di presenter sarà una novità. Per altre informazioni sui presenter di finestre di app, vedere Presenter. Per impostazione predefinita, un presenter sovrapposto si applica a una AppWindow al momento della creazione. CompactOverlay e FullScreen sono i soli presenter disponibili, a parte quelli predefiniti.

Sovrapposizione compatta

Se si è utilizzato ApplicationViewMode o AppWindowPresentionKind per presentare una finestra a sovrapposizione compatta, allora occorre utilizzare AppWindowPresenterKind a sovrapposizione compatta. Il Microsoft.UI.Windowing.CompactOverlayPresenter supporta solo tre dimensioni di finestra fisse in formato 16:9 e non può essere ridimensionato dall'utente. Invece di ApplicationViewMode.TryEnterViewModeAsync o AppWindowPresenterKind.RequestPresentation, occorre utilizzare AppWindow.SetPresenter per cambiare la presentazione della AppWindow.

Schermo intero

Se si sono utilizzate le classi ApplicationViewWindowingMode o AppWindowPresentionKind per presentare una finestra a schermo intero, allora occorre utilizzare AppWindowPresenterKind a schermo intero. Windows App SDK supporta solo l'esperienza a schermo intero più restrittiva (cioè quando FullScreen è IsExclusive). Per ApplicationView/CoreWindow, è possibile utilizzare ApplicationView.ExitFullScreenMode per far uscire l'app dalla modalità schermo intero. Quando si usano i presenter, è possibile far uscire un'app dalla modalità schermo intero riportando il presenter alla modalità sovrapposta/predefinita utilizzando AppWindow.SetPresenter.

Per maggiori dettagli su come lavorare con i presenter di finestre dell'app, vedi la Galleria di esempi di windowing. Dimostra come attivare diversi stati del presenter di finestre di app.

Barra del titolo personalizzata

Se l'app utilizza una barra del titolo predefinita, non serve intervenire ulteriormente sulla barra del titolo durante la migrazione a Win32. Se però l'app UWP ha una barra del titolo personalizzata, allora è possibile ricreare i seguenti scenari nell'app Windows App SDK.

1. Personalizzare la barra del titolo disegnata dal sistema
2. Barra del titolo personalizzata disegnata dall'app

Il codice che utilizza le classi UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar e AppWindowTitleBar esegue la migrazione all'utilizzo della classe Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar.

Personalizzare la barra del titolo disegnata dal sistema

Di seguito una tabella delle API per la personalizzazione dei colori.

Queste API di Windows App SDK servono a personalizzare ulteriormente la barra del titolo disegnata dal sistema in aggiunta all'API AppWindow.Title.

• AppWindow.SetIcon. Imposta l'icona della barra del titolo e della barra delle applicazioni usando un gestore hIcon o un percorso di stringa su una risorsa o su un file.
• AppWindowTitleBar.IconShowOptions. Riceve o imposta un valore che specifica in che modo l'icona della finestra viene visualizzata nella barra del titolo. Al momento supporta due valori:HideIconAndSystemMenu e ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Ripristina l'attuale barra del titolo alle impostazioni predefinite della finestra.

Barra del titolo personalizzata disegnata dall'app (personalizzazione completa)

Se si sta eseguendo la migrazione all'utilizzo di AppWindowTitleBar, consigliamo di verificare AppWindowTitleBar.IsCustomizationSupported nel codice prima di chiamare le seguenti API di personalizzazione della barra del titolo.

Queste API Windows App SDK servono a personalizzare completamente la barra del titolo.

• AppWindowTitleBar.SetDragRectangles. Imposta le aree di trascinamento per la finestra.
• AppWindowTitleBar.ResetToDefault. Ripristina l'attuale barra del titolo alle impostazioni predefinite della finestra.

Queste API AppWindow della piattaforma UWP non hanno un mapping 1:1 diretto a un'API Windows App SDK.

• AppWindowTitleBarVisibility. Definisce costanti che specificano la visibilità preferita di una AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Recupera la modalità di visibilità preferita per la barra del titolo.
• AppWindowTitleBar.SetPreferredVisibility. Imposta la modalità preferita di visibilità per la barra del titolo.

Per maggiori dettagli su come lavorare con AppWindowTitleBar, vedere la Galleria di esempi di windowing. Dimostra come creare una barra del titolo a colori personalizzata e come disegnare una barra del titolo personalizzata.

Gestione degli eventi

Se l'app UWP utilizza l'evento AppWindow.Changed, è possibile eseguire la migrazione di quel codice all'evento Microsoft.UI.Windowing.AppWindow.Changed.

Evento di modifica delle dimensioni

Quando si esegue la migrazione del codice di gestione dell'evento di modifica delle dimensioni, occorre passare a utilizzare la proprietà AppWindowChangedEventArgs.DidSizeChange di Windows App SDK. Il valore è true se le dimensioni della finestra dell'app sono cambiate, altrimenti è false.

MainPage e MainWindow

Quando si crea un nuovo progetto UWP in Visual Studio, il modello di progetto fornisce una classe MainPage. Per l'app, quella classe potrebbe essere stata rinominata (e/o aggiunti altre pagine e controlli utente). Il modello di progetto fornisce anche il codice di spostamento nei metodi della classe App.

Quando si crea un nuovo progetto Windows App SDK in Visual Studio, il modello di progetto fornisce una classe MainWindow (di tipo Microsoft.UI.Xaml.Window), ma nessuna Pagina. E il modello di progetto non fornisce alcun codice di spostamento.

Esiste comunque l'opzione di aggiungere pagine e controlli utente al progetto Windows App SDK. Ad esempio è possibile aggiungere un nuovo elemento pagina al progetto (WinUI>Pagina bianca (WinUI 3)) e denominarlo MainPage.xaml o con un altro nome. Questa operazione aggiunge al progetto una nuova classe di tipo Microsoft.UI.Xaml.Controls.Page. Quindi, per informazioni su come aggiungere il codice di spostamento, vedere Devo implementare lo spostamento nella pagina?.

Per le app Windows App SDK sufficientemente semplici, non occorre creare pagine o controlli utente ed è possibile copiare il markup XAML e il code-behind nella MainWindow. Ma per informazioni sulle eccezioni di quel flusso di lavoro, vedere Visual State Manager e Page.Resources.

Modificare CoreWindow.Dispatcher in Window.DispatcherQueue

Alcuni casi d'uso per la classe Windows.UI.Core.CoreWindow della piattaforma UWP eseguono la migrazione nella Microsoft.UI.Xaml.Windowdi Windows App SDK.

Ad esempio, se si utilizza la proprietà Windows.UI.Core.CoreWindow.Dispatcher nell'app UWP, la soluzione non è quella di eseguire la migrazione alla proprietà Microsoft.UI.Xaml.Window.Dispatcher (che restituisce sempre null). Occorre invece eseguire la migrazione alla proprietà Microsoft.UI.Xaml.Window.DispatcherQueue, che restituisce una Microsoft.UI.Dispatching.DispatcherQueue.

Per altre informazioni ed esempi di codice, vedere Modificare Windows.UI.Core.CoreDispatcher in Microsoft.UI.Dispatching.DispatcherQueue.

Argomenti correlati

• SDK per app di Windows e versioni di Windows supportate
• Migrazione della funzionalità di threading