Gestisci le finestre delle app (Windows App SDK)

  • Articolo

In questo argomento è contenuta una sezione relativa alla sezione Esempio di codice.

Windows App SDK fornisce l'intuitiva classe Microsoft.UI.Windowing.AppWindow. AppWindow è indipendente dal framework e disponibile per tutte le app di Windows, tra cui Win32, WPF e WinForms. È possibile contrapporre la natura indipendente dal framework di AppWindow a Microsoft.UI.Xaml.Window, ovvero la classe della finestra specifica per il framework WinUI 3. AppWindow è anche un'evoluzione di Windows.UI.WindowManagement.AppWindow della piattaforma UWP (Universal Windows Platform).

La versione SDK per app di Windows di Microsoft.UI.Windowing.AppWindow non si basa su modelli asincroni e fornisce un feedback immediato all'app sull'esito positivo delle chiamate API.

Vedere anche Installazione degli strumenti per Windows App SDK, Creazione del primo progetto WinUI 3 e Utilizzo di Windows App SDK in un progetto esistente.

Classe AppWindow

Microsoft.UI.Windowing.AppWindow è un'API di alto livello che consente scenari di windowing facili da usare. AppWindow si integra bene con l'interfaccia utente/esperienza utente di Windows e con altre app.

AppWindow rappresenta un'astrazione di alto livello di un contenitore gestito dal sistema per il contenuto di un'app. È il contenitore in cui è ospitato il contenuto; e rappresenta l'entità con cui gli utenti interagiscono quando ridimensionano e spostano l'app sullo schermo. Se si ha familiarità con Win32, la finestra dell'app può essere considerata come un'astrazione di alto livello di HWND. Se hai familiarità con la piattaforma UWP, finestra dell'app può essere considerata una sostituzione di CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

Per la versione Windows App SDK di Microsoft.UI.Windowing.AppWindow sono supportati solo HWNDdi primo livello. Esiste un mapping 1:1 tra un oggetto AppWindow e un HWND di primo livello.

La durata di un oggetto AppWindow e di un HWND è la stessa, ovvero AppWindow è disponibile immediatamente dopo la creazione della finestra e viene eliminata definitivamente quando la finestra viene chiusa.

Classe AppWindowPresenter e sottoclassi

a ogni AppWindow viene applicato un oggetto AppWindowPresenter (relatore). Se l'utente è un developer UWP che ha lavorato con Windows.UI.WindowManagement.AppWindow, allora saprà acquisire familiarità con quest'ultimo, anche se non è un mapping 1:1 di funzionalità e comportamento. Vedere anche Migrazione delle funzionalità di windowing.

Come nuovo concetto del modello di applicazione Win32, un relatore è simile (ma non uguale a) una combinazione di stato e stili della finestra. Alcuni relatori hanno anche comportamenti di interfaccia utente/esperienza utente definiti in essi che non sono controllabili dallo stato classico della finestra e dalle proprietà di stile (ad esempio una barra del titolo nascosta automaticamente).

Per impostazione predefinita, un relatore viene creato dal sistema e applicato a un'appWindow in fase di creazione. In Windows App SDK 1.0, sul desktop di Windows, il tipo di relatore è OverlappedPresenter, che sarebbe una sottoclasse di AppWindowPresenter. Non è necessario che l'app la conservi, né mantenga un riferimento per tornare al relatore predefinito per una finestra dopo aver applicato un altro relatore. Questo perché il sistema mantiene la stessa istanza di questo relatore per tutta la durata della creazione di AppWindow per cui è stata creata e l'app può riapplicarla richiedendo il metodo AppWindow.SetPresenter con AppWindowPresenterKind.Default come parametro.

Un relatore può essere applicato a una sola finestra alla volta. Il tentativo di applicare lo stesso relatore a una seconda finestra genera un'eccezione. Ciò significa che se si dispone di più finestre e si desidera passare ciascuna di esse a una modalità di presentazione specifica, è necessario creare più relatori dello stesso tipo e applicarli ciascuno alla propria finestra.

Alcuni relatori hanno funzionalità che consentono a un utente di apportare modifiche al di fuori del proprio controllo dell'app. Quando si verifica una modifica di questo tipo, l'app riceve una notifica da un evento AppWindow.Changed sulla AppWindow interessata, con la proprietà AppWindowChangedEventArgs.DidPresenterChange impostata su true. L'app dovrebbe quindi esaminare la proprietà del relatore applicato per vedere cosa è cambiato.

Il relatore applicato è un oggetto attivo. Una modifica a qualsiasi proprietà dell'oggetto AppWindow.Presenter diventa effettiva immediatamente.

Un relatore non può essere eliminato definitivamente mentre viene applicato a una finestra. Per eliminare definitivamente un oggetto relatore, applicare prima di tutto un oggetto relatore diverso alla finestra; in questo modo, il relatore che si intende eliminare viene rimosso dalla finestra. A tale scopo, è possibile applicare un altro relatore specifico alla finestra oppure chiamando il metodo AppWindow.SetPresenter con AppWindowPresenterKind.Default come argomento, che riapplica il relatore predefinito creato dal sistema alla finestra. Se è stato fatto in modo che si mantenga un riferimento al relatore creato dal sistema per la finestra, sarà valido a questo punto, ovvero l'istanza creata per la prima volta per la finestra viene ri-applicata.

Relatori disponibili

Questi relatori derivati da AppWindowPresenter sono disponibili in tutte le versioni del sistema operativo supportate.

  • CompactOverlayPresenter. Crea una finestra sempre in primo piano di una dimensione fissa, con proporzioni di 16:9 per consentire esperienze simili alle immagini.
  • FullScreenPresenter. Consente a una finestra di accedere a un'esperienza a schermo intero.
  • OverlappedPresenter. Relatore predefinito creato dal sistema, che consente di richiedere e reagire per ridurre al minimo/ottimizzare/ripristinare le operazioni e le modifiche dello stato.

Framework dell'interfaccia utente e interoperabilità HWND

La classe AppWindow è disponibile per qualsiasiHWNDdi alto livello nella propria app. Ciò significa che quando si opera con un framework dell'interfaccia utente desktop (incluso WinUI 3), è possibile continuare a usare il punto di ingresso di quel framework per creare una finestra e allegarne il contenuto. Dopo aver creato una finestra con tale framework dell'interfaccia utente, è possibile usare le funzioni di interoperabilità del windowing (vedere di seguito) fornite in Windows App SDK per accedere alla corrispondente appWindow e ai relativi metodi, proprietà ed eventi.

Alcuni dei vantaggi dell'uso di AppWindow (anche quando si usa un framework dell'interfaccia utente) sono:

  • Personalizzazione semplice della barra del titolo; che per impostazione predefinita mantiene l'interfaccia utente di Windows 11 (angoli arrotondati, riquadro a comparsa del gruppo di snap).
  • Esperienze di sovrimpressione a schermo intero e compatta fornite dal sistema (picture-in-picture).
  • Superficie dell'API Windows Runtime (WinRT) per alcuni dei concetti principali relativi alle finestre win32.

Esempio di codice

Questo esempio di codice illustra come recuperare una finestra di Microsoft.UI.Windowing.AppWindow da una finestra WinUI 3 utilizzando la proprietà Microsoft.UI.Xaml.Window.AppWindow. Per usare l'esempio, creare un nuovo progetto App vuota, incluso nel pacchetto (WinUI 3 in Desktop) e incollare il codice.

Per altri dettagli su come usare AppWindow, vedere l'esempio della raccolta Windowing.

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

Esempio di codice per le versioni di Windows App SDK precedenti alla 1.3 (o altri framework di app desktop)

La proprietà Microsoft.UI.Xaml.Window.AppWindow (usata nell'esempio di codice precedente) è disponibile in Windows App SDK versione 1.3 e successive. Per le versioni precedenti, è possibile usare l'esempio di codice equivalente funzionalmente in questa sezione.

C#. I wrapper .NET per le funzioni di interoperabilità windowing vengono implementati come metodi della classe Microsoft.UI.Win32Interop. Vedere inoltre Chiamare le API interop da un'app .NET

C++. Le funzioni di interoperabilità sono definite nel file di intestazione winrt/Microsoft.ui.interop.h.

La sezione Esempio di codice di seguito mostra il codice sorgente effettivo, ma ecco la ricetta per recuperare un oggetto AppWindow in base a una finestra esistente:

  1. Recuperare HWND per l'oggetto finestra esistente (per il framework dell'interfaccia utente), se non è già disponibile.
  2. Passare HWND alla funzione di interoperabilità GetWindowIdFromWindow per recuperare un WindowId.
  3. Passare WindowId al metodo statico AppWindow.GetFromWindowId per recuperare 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!");
    }
}

Limiti

  • AppWindow è un'API WinUI 3. Ciò significa che è disponibile solo per le app desktop (siano esse incluse o meno per il pacchetto); e non è disponibile per le app UWP.
  • Windows App SDK non fornisce attualmente dei metodi per collegare il contenuto del framework dell'interfaccia utente a un'appWindow. Tuttavia, si veda la sezione Esempio di codice.
  • La personalizzazione della barra del titolo è supportata in Windows 11 e versioni successive; e in Windows 10 per la versione 1.2 e successive di Windows App SDK. Per altre informazioni, vedi Personalizzazione della barra del titolo.