Alkalmazásablakok kezelése

A Windows App SDK biztosítja a Microsoft.UI.Windowing.AppWindow osztályt, amely a HWND magas szintű absztrakcióját jelöli. Az alkalmazásban egy 1:1-es leképezés található egy AppWindow és egy legfelső szintű HWND között. AppWindow és annak kapcsolódó osztályai olyan API-kat biztosítanak, amelyekkel az alkalmazás felső szintű ablakainak számos aspektusát kezelheti anélkül, hogy közvetlenül el kellene érnie a HWND-t.

Megjegyzés:

Ez a cikk bemutatja, hogyan használhat AppWindow API-kat az alkalmazásban. Előfeltételként javasoljuk, hogy olvassa el és ismerje meg a AppWindow információkat a Windowing áttekintésében a WinUI 3 és Windows App SDK esetében, amely akkor alkalmazható, ha WinUI-t vagy más felhasználói felületi keretrendszert használ.

• Fontos API-k: AppWindow osztály, átfedésben lévőpresenter osztály

Nyissa meg a WinUI 3 Katalógus alkalmazást, és tekintse meg AppWindow működés közben

A WinUI 3 Katalógus alkalmazás interaktív példákat tartalmaz a WinUI vezérlőire és funkcióira. Kérje le az alkalmazást a Microsoft Áruházból vagy keresse meg a forráskódot a GitHub webhelyen.

A AppWindow API-kat bármely olyan felhasználói felületi keretrendszerrel használhatja, amelyet a Windows App SDK támogat – WinUI, WPF, WinForms vagy Win32. AppWindow Az API-k a keretrendszerspecifikus ablakos API-k mellett működnek:

• XAML Window
• WPF Window
• Windows Forms Form
• Win32 ablakos API-k, MFC Windows

Az API-k általában a következő célra használhatók AppWindow :

• Kezelheti az alkalmazás ablakának méretét és pozícióját.

• Az ablak címének, ikonjának és címsorszínének kezelése; vagy hozzon létre egy teljesen egyéni címsort az AppWindowTitleBar API-kkal.

  További információkért és példákért lásd a címsor testreszabását .

• Az ablak megjelenésének és viselkedésének kezelése AppWindowPresenter-származtatott API-kkal.

Reagálás a változásokra AppWindow

A változásokra az AppWindow egyetlen módosított esemény kezelésével válaszolhat, majd az esemény args (AppWindowChangedEventArgs) ellenőrzésével állapíthatja meg, hogy milyen típusú változás történt. Ha az önt érdeklő módosítás megtörtént, reagálhat rá. A lehetséges változások közé tartozik a pozíció, a méret, az előadó, a láthatóság és a z-order.

Íme egy példa egy AppWindow.Megváltozott eseménykezelő.

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    // ConfigText and SizeText are TextBox controls defined in XAML for the page.
    if (args.DidPresenterChange == true)
    {
        ConfigText.Text = sender.Presenter.Kind.ToString();
    }

    if (args.DidSizeChange == true)
    {
        SizeText.Text = sender.Size.Width.ToString() + ", " + sender.Size.Height.ToString();
    }
}

Window méret és elhelyezés

Az AppWindow osztály számos tulajdonsággal és módszerrel rendelkezik az ablak méretének és elhelyezésének kezeléséhez.

Kategória	Tulajdonságok
Írásvédett tulajdonságok	Pozíció, Méret, Ügyfélméret
Events	Módosítva (DidPositionChange, DidSizeChange)
Méret- és elhelyezési módszerek	Áthelyezés, Átméretezés, ResizeClient, MoveAndResize
Z-order módszerek	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Új ablakméret megadásához hívja meg az Átméretezés parancsot.

Ebben a példában a kód a MainWindow.xaml.cs helyen van, így a Window.AppWindow tulajdonság használatával lekérheti a AppWindow példányt.

public MainWindow()
{
    InitializeComponent();
    AppWindow.Resize(new Windows.Graphics.SizeInt32(1200, 800));
}

Az Áthelyezés metódus meghívásával módosíthatja az ablak pozícióját.

Ez a példa a képernyő közepére helyezi az ablakot, amikor a felhasználó egy gombra kattint.

Ez egy Page osztály kódfájljában fordul elő, így nem férhet hozzá automatikusan az Window vagy AppWindow objektumokhoz. Néhány lehetősége van a AppWindow megszerzésére.

• Ha az Window hivatkozást tart, ahogy az a Aktuális ablak nyomon követése vagy a Window példányok nyomon követése című részekben le van írva, lekérheti a Window-t, majd megszerezheti a AppWindow tulajdonságot.
• Vagy meghívhatja a statikusAppWindow GetFromWindowId metódust a AppWindow példány lekéréséhez, ahogyan itt látható. (Lásd : A vizualizációelemeket üzemeltető ablak meghatározása.)

private void MoveWindowButton_Click(object sender, RoutedEventArgs e)
{
    AppWindow appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    RectInt32? area = DisplayArea.GetFromWindowId(appWindow.Id, DisplayAreaFallback.Nearest)?.WorkArea;
    if (area == null) return;
    appWindow.Move(new PointInt32((area.Value.Width - appWindow.Size.Width) / 2, (area.Value.Height - appWindow.Size.Height) / 2));
}

Az AppWindowPresenter osztály és alosztályok

Mindegyikhez van alkalmazva egy AppWindowAppWindowPresenter (előadó). Az előadót a rendszer hozza létre, és a AppWindow létrehozásakor alkalmazza. Az AppWindowPresenter minden alosztálya egy előre definiált konfigurációt biztosít, amely megfelel az ablak céljának. Ezek az AppWindowPresenter-alapú előadók rendelkezésre állnak, és az operációs rendszer összes támogatott verziójában elérhetők.

• CompactOverlayPresenter

  Rögzített méretű , mindig felülnézetes ablakot konfigurál 16:9-es képaránysal, hogy képről képre hasonlító élményt biztosíthasson. Alapértelmezés szerint az InitialSizeCompactOverlaySize.Small, de módosíthatja Medium vagy Large értékre. Hívhatja a AppWindow.Resize funkciót is a 16:9-es képarány felülbírálásához, és állítsa be az ablakot a kívánt méretre.

• FullScreenPresenter

  Egy ablakot úgy konfigurál, hogy teljes képernyős élményt biztosítson a videónézéshez. Az ablak nem rendelkezik szegélyrel vagy címsorral, és elrejti a rendszer tálcáját.

• OverlappedPresenter

  A szabványos ablakkonfiguráció, amely alapértelmezés szerint címsorral és átméretező nyilakkal ellátott szegélyt biztosít, kicsinyítés/nagyítás/visszaállítás gombokkal.

Megjegyzés:

A Win32-alkalmazásmodell új koncepciójaként az előadó az ablakállapot és a stílusok kombinációjához hasonló (de nem ugyanaz). Egyes előadók olyan viselkedéseket is meghatároznak bennük, amelyek nem vizsgálhatók meg klasszikus ablakállapot- és stílustulajdonságokból (például egy automatikusan elrejtett címsorból).

Az alapértelmezett előadó

A(z) AppWindow létrehozásakor alkalmazott alapértelmezett előadó az OverlappedPresenter egy példánya, amely alapértelmezett tulajdonságbeállításokkal rendelkezik. Az ablak alapértelmezett bemutatójára való visszatéréshez nincs szükség arra, hogy hivatkozást tartsunk fenn rá, miután egy másik bemutatót alkalmaztunk. Ennek az az oka, hogy a rendszer a presenter ugyanazon példányát megtartja a AppWindow teljes élettartama alatt, amelyre létrehozták; és újra alkalmazhatja a AppWindow.SetPresenter metódus meghívásával az AppWindowPresenterKind.Default paraméterrel.

Fontos

A SetPresenter(AppWindowPresenterKind.Default) hívása mindig újra alkalmazza az alapértelmezett prezentáló példányt, amely a AppWindow-tel jön létre. Ha egy másik előadót hoz létre és alkalmaz, és később újra alkalmazni szeretné, meg kell őriznie az előadóra mutató hivatkozást.

Az alapértelmezett előadói példányra mutató hivatkozást is lekérhet, és módosíthatja azt. Ha új előadót alkalmazott, először győződjön meg arról, hogy az alapértelmezett előadó van alkalmazva, az itt látható módon:

appWindow.SetPresenter(AppWindowPresenterKind.Default);
OverlappedPresenter defaultPresenter = (OverlappedPresenter)appWindow.Presenter;
defaultPresenter.IsMaximizable = false;
defaultPresenter.IsMinimizable = false;

Az OverlappedPresenter módosítása

Az Átfedésben lévő előadó egy rugalmas előadó, amelyet többféleképpen konfigurálhat.

A Create* metódusokkal létrehozhat egy átfedésben lévő előadót alapértelmezett tulajdonságbeállításokkal, vagy egy olyan előadót, amely egy adott használatra előre konfigurált tulajdonságbeállításokkal rendelkezik.

Ez a táblázat bemutatja, hogyan vannak beállítva a konfigurációs tulajdonságok, amikor átfedésben lévőPresenter objektumot hoz létre az egyes metódusokból.

Ingatlan	Create	CreateForContextMenu	CreateForDialog	CreateForToolWindow
HasBorder	true	true	true	true
HasTitleBar	true	false	true	true
IsAlwaysOnTop	false	false	false	false
IsMaximizable	true	false	false	true
IsMinimizable (Minimálható-e)	true	false	false	true
IsModal	false	false	false	false
IsResizable	true	false	false	true

Az alkalmazott előadó egy élő objektum. A AppWindow.Presenter objektum bármely tulajdonságának módosítása azonnal érvénybe lép. Nincsenek értesítési események ezekről a változásokról, de bármikor ellenőrizheti az aktuális értékek jellemzőit.

A HasBorder és a HasTitleBar tulajdonságok írásvédettek. Ezeket az értékeket a SetBorderAndTitleBar metódus ()SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar) meghívásával állíthatja be. OverlappedPresenter nem rendelkezhet szegély nélküli címsorral. Vagyis ha a hasTitleBar paraméter az true, akkor a hasBorder paraméternek is meg kell lennie true. Ellenkező esetben a rendszer kivételt küld ezzel az üzenettel:

The parameter is incorrect.
Invalid combination: Border=false, TitleBar=true.

Állítsa be a IsMaximizable értékét false-ra, hogy elrejtse a maximalizálás gombot az eszköztáron. Ezt akkor javasoljuk, ha beállítja a PreferredMaximumHeightPreferredMaximumWidth tulajdonságokat, mivel ezek a tulajdonságok még a teljes állapotban is korlátozzák az ablakméretet. Ez nem érinti a Maximalizálás metódus hívásait.

Az IsMinimizable beállítását false értékre állítva elrejtheti a kicsinyítés gombot az eszköztáron. Ez nem érinti a Minimize metódus hívásait.

Az IsResizablefalse beállításával elrejtheti az átméretező vezérlőket, és megakadályozhatja, hogy a felhasználó átméretezze az ablakot. Ez nem befolyásolja a AppWindow.Resize metódus hívásokat.

Az IsAlwaysOnTop beállításával true ezt az ablakot a többi ablak fölé állíthatja. Ha bármelyik AppWindow.MoveInZOrder* metódust meghívja, azok akkor is módosítják az ablak z-sorrendjét, még akkor is, ha ez a tulajdonság true.

Állítsa be a PreferredMaximumHeight és a PreferredMaximumWidth beállítást, hogy korlátozza a felhasználó számára az ablak maximális méretét. Javasoljuk, hogy a maximális mérettulajdonságok beállítása esetén állítsa be IsMaximizablefalse a beállításokat, mivel ezek a tulajdonságok még a teljes méretben is korlátozzák az ablakméretet. Ezek a tulajdonságok a AppWindow.Resize hívásokat is befolyásolják; az ablak méretét nem lehet nagyobbra méretezni a megadott maximális magasságnál és szélességnél.

A PreferredMinimumHeight és a PreferredMinimumWidth beállításával állítsa be azt a minimális méretet, amelybe a felhasználó az ablakot zsugorítja. Ezek a tulajdonságok hatással vannak a AppWindow.Resize függvény hívásaira is; az ablak mérete nem lehet kisebb a megadott minimális magasságnál és szélességnél.

Modális ablakok

Az IsModaltrue beállításával modális ablakot hozhat létre. A modális ablak egy külön ablak, amely letiltja a tulajdonosi ablakkal való interakciót, amíg be nem zárja. Modális ablak létrehozásához azonban be kell állítania a tulajdonosi ablakot is; ellenkező esetben a rendszer kivételt küld ezzel az üzenettel:

The parameter is incorrect.

The window should have an owner when IsModal=true.

A WinUI-alkalmazások tulajdonosi ablakának beállításához Win32-interopra van szükség. További információkért és példakódért tekintse meg a AppWindow WinUI 3 Katalógus mintaalkalmazás lapját.

• A WinUI 3 Katalógus alkalmazás elindítása
• Nyissa meg a ModalWindow.xaml.cs fájlt a GitHubon

Előadó alkalmazása

Az előadók egyszerre csak egyetlen ablakra alkalmazhatók. Ha megpróbálja ugyanazt a prezentert egy második ablakra alkalmazni, az kivételt dob. Ez azt jelenti, hogy ha több ablaka van, és mindegyiket egy adott bemutatómódra szeretné váltani, akkor több azonos típusú előadót kell létrehoznia, majd mindegyiket a saját ablakára kell alkalmaznia.

Amikor új előadó kerül alkalmazásra (a AppWindow.Presenter tulajdonság megváltozik), az alkalmazás értesítést kap egy AppWindow.Changed eseményen keresztül az érintett AppWindow-hoz kötve, mely során az AppWindowChangedEventArgs.DidPresenterChange tulajdonság értéke true-re van állítva.

Jótanács

Ha módosított előadót alkalmaz, és engedélyezi az előadók közötti váltást, mindenképpen őrizze meg a módosított előadóra mutató hivatkozást, hogy az újra alkalmazható legyen a AppWindow.

Ez a példa bemutatja, hogyan kell végrehajtani a következőket:

• Használja a AppWindow.Prezentáló tulajdonságot az aktuális prezentáló megszerzéséhez.
• Az AppWindowPresenter.Kind tulajdonság segítségével ellenőrizheti, hogy milyen konfiguráció van jelenleg alkalmazva.
• Használja a AppWindow.SetPresenter-t az aktuális konfiguráció megváltoztatásához.

Itt egy megjelenítőt hozunk létre, módosítunk és alkalmazunk az ablak konstruktorában.

OverlappedPresenter presenter = OverlappedPresenter.Create();
presenter.PreferredMinimumWidth = 420;
presenter.PreferredMinimumHeight = 550;
AppWindow.SetPresenter(presenter);

A oldalon, amely az ablak tartalmát jeleníti meg, hivatkozást kaphat az AppWindow és az alkalmazott előadóra.

AppWindow appWindow;
OverlappedPresenter modifiedPresenter;

private void AppWindowPage_Loaded(object sender, RoutedEventArgs e)
{
    appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    modifiedPresenter = (OverlappedPresenter)appWindow.Presenter;

    appWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        // ConfigText is a TextBox control defined in XAML for the page.
        ConfigText.Text = appWindow.Presenter.Kind.ToString();
    }
}

private void CompactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.CompactOverlay)
    {
        appWindow.SetPresenter(CompactOverlayPresenter.Create());
        fullScreenButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

private void FullScreenButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.FullScreen)
    {
        appWindow.SetPresenter(FullScreenPresenter.Create());
        compactOverlayButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

UI-keretrendszer és HWND interop

Az AppWindow osztály minden felső szintű HWND-hez elérhető az alkalmazásban. Ez azt jelenti, hogy ha asztali felhasználói felületi keretrendszerrel dolgozik (beleértve a WinUI-t is), továbbra is használhatja a keretrendszer belépési pontját egy ablak létrehozásához és a tartalom csatolásához. Miután létrehozott egy ablakot ezzel a felhasználói felületi keretrendszerrel, használhatja a Windows App SDK ablakközi függvényeit (lásd alább) a megfelelő AppWindow és metódusai, tulajdonságai és eseményei eléréséhez.

A AppWindow használatának néhány előnye (még akkor is, ha felhasználói felület keretrendszerrel dolgozva) a következők:

• Egyszerű címsor testreszabása; amely alapértelmezés szerint fenntartja a Windows 11 felhasználói felületet (lekerekített sarkok, illesztőcsoport-úszó).
• Rendszer által biztosított teljes képernyős és kompakt átfedési (kép a képben) felület.
• Windows Runtime (WinRT) API-felület néhány alapvető Win32-es ablakkészítési fogalomhoz.

Szerezze be a AppWindow az 1.3 előtti Windows App SDK verzióihoz (vagy más asztali alkalmazás-keretrendszerekhez)

A Window.AppWindow tulajdonság Windows App SDK 1.3-es és újabb verziójában érhető el. A korábbi verziók esetében a jelen szakaszban található, funkcionálisan egyenértékű kód példáját használhatja.

C#. .NET ablakközi függvény burkolóit a Microsoft.UI.Win32Interop osztály metódusaként implementáljuk. Lásd még: A .NET alkalmazásközi API-k hívása.

C++. Az interop függvények a winrt/Microsoft.ui.interop.h fejlécfájlban vannak definiálva.

Az alábbi kód példaszakasza a tényleges forráskódot jeleníti meg; itt található a módszer egy AppWindow objektum lekéréséhez egy meglévő ablak alapján:

1. Kérje le a HWND-t a meglévő ablakobjektumhoz (a felhasználói felületi keretrendszerhez), ha még nem rendelkezik vele.
2. Adja át a HWND-t a GetWindowIdFromWindow interop függvénynek a WindowId lekéréséhez.
3. Adja át a WindowId azonosítót a statikus , GetFromWindowId metódusnak a lekéréséhez.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 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 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 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 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!");
    }
}

További példákért, hogyan lehet dolgozni AppWindow elemmel, nézze meg az Ablakgaléria példát.

Korlátozások

A Windows App SDK jelenleg nem biztosít módszereket a felhasználói felületi keretrendszer tartalmának AppWindow való csatolásához.

Kapcsolódó témakörök

• Ablakkezelés áttekintése
• Címsor testreszabása
• Windowing-funkciók migrálása
• A .NET alkalmazásközi API-k hívása
• Ablakfogópont (HWND) lekérése
• Ablakkezelési galéria minta