Uygulama pencerelerini yönetme

Windows Uygulama SDK'sı, HWND'nin üst düzey soyutlamasını temsil eden Microsoft.UI.Windowing.AppWindow sınıfını sağlar. Uygulamanızdaki bir AppWindow ile en üst düzey HWND arasında 1:1 eşlemesi vardır. AppWindow ve ilgili sınıfları, HWND'ye doğrudan erişmeye gerek kalmadan uygulamanızın üst düzey pencerelerinin birçok yönünü yönetmenize olanak sağlayan API'ler sağlar.

Uyarı

Bu makalede, AppWindow API'lerin uygulamanızda nasıl kullanılacağı gösterilmektedir. Önkoşul olarak, WinUI veya başka bir UI çerçevesi kullanmanız fark etmeksizin geçerli olan AppWindow makalesindeki bilgileri okumanızı ve anlamanızı öneririz.

• Önemli API'ler: AppWindow sınıf, OverlappedPresenter sınıfı

WinUI 3 Galeri uygulamasını açın ve AppWindow'i iş başında görün

WinUI 3 Galeri uygulaması çoğu WinUI 3 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alın

API'leri Windows Uygulama SDK'sının desteklediği herhangi bir UI çerçevesiyle kullanabilirsiniz AppWindow : WinUI 3, WPF, WinForms veya Win32. AppWindow API'ler çerçeveye özgü pencereleme API'leri ile birlikte çalışır:

• XAML Window
• WPF Window
• Windows Forms Formu
• Win32 pencereleme API'leri, MFC Windows

Api'leri genellikle aşağıdakiler için kullanırsınız AppWindow :

• Uygulamanızın penceresinin boyutunu ve konumunu yönetin.

• Pencere başlığını, simgesini ve başlık çubuğu rengini yönetme; veya AppWindowTitleBar API'leri ile tamamen özel bir başlık çubuğu oluşturun.

  Daha fazla bilgi ve örnek için bkz. Başlık çubuğu özelleştirmesi .

• AppWindowPresenter tarafından türetilen API'ler ile pencerenin görünümünü ve davranışını yönetin.

Değişikliklere AppWindow yanıt ver

değişikliklerine AppWindow , Changed olayını işleyerek ve ardından ne tür bir değişiklik olduğunu belirlemek için olay bağımsız değişkenlerini (AppWindowChangedEventArgs) denetleyerek yanıt verirsiniz. İlgilendiğiniz değişiklik gerçekleştiyse, bu değişikliği yanıtlayabilirsiniz. Olası değişiklikler konum, boyut, sunucu, görünürlük ve z sırasıdır.

Aşağıda AppWindow.Changed olayı için bir olay işleyicisi örneği verilmiştir.

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 boyut ve yerleştirme

sınıfı, AppWindow pencerenin boyutunu ve yerleşimini yönetmek için kullanabileceğiniz çeşitli özelliklere ve yöntemlere sahiptir.

Kategori	Özellikler
Salt okunur özellikler	Konum, Boyut, İstemciBoyutu
Events	Değiştirildi (DidPositionChange, DidSizeChange)
Boyut ve konum yöntemleri	Taşı, Yeniden Boyutlandır, ResizeClient, MoveAndResize
Z sırası yöntemleri	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Yeni bir pencere boyutu belirtmek için Resize çağrısı yapın.

Bu örnekte, kod MainWindow.xaml.cs içindedir, bu nedenle Window.AppWindow özelliğini kullanarak AppWindow örneğini alabilirsiniz.

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

Pencerenin konumunu değiştirmek için Move yöntemini çağırın.

Bu örnek, kullanıcı bir düğmeye tıkladığında pencereyi ekranda ortalanacak şekilde taşır.

Bu, Page sınıfının kod dosyasında oluşur, bu nedenle Window veya AppWindow nesnelerine otomatik olarak erişiminiz olmaz. AppWindow almak için birkaç seçeneğiniz vardır.

• Eğer Window'ya bir başvuru tutarsanız, Geçerli pencereyi izleme veya Window örneklerini izleme bölümünde açıklandığı gibi, Window öğesini alabilir ve ardından AppWindow özelliğinden Window alabilirsiniz.
• Alternatif olarak, burada gösterildiği gibi AppWindow.GetFromWindowId statik yöntemini çağırarak AppWindow örneğini alabilirsiniz. (Bkz . Görsel öğe barındıran pencereyi belirleme.)

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));
}

AppWindowPresenter sınıfı ve alt sınıfları

Her AppWindow birinde bir AppWindowPresenter (sunum arayüzü) uygulanır. Sistem tarafından bir gösterici oluşturulur ve oluşturma anında bir AppWindow bileşene uygulanır. AppWindowPresenter'ın her alt sınıfı, pencerenin amacına uygun önceden tanımlanmış bir yapılandırma sağlar. Bu AppWindowPresenter türetilmiş sunum biçimleri sağlanır ve bunlar desteklenen tüm işletim sistemi sürümlerinde mevcuttur.

• CompactOverlayPresenter

  Resim içinde resim benzeri deneyimlere olanak sağlamak için 16:9 en boy oranıyla sabit boyutta her zaman üstte olan bir pencere yapılandırılır. Varsayılan olarak InitialSizeCompactOverlaySize.Small şeklindedir, ancak bunu Medium veya Large olarak değiştirebilirsiniz. öğesini de çağırabilirsiniz AppWindow. 16:9 en boy oranını geçersiz kılmak için yeniden boyutlandırın ve pencereyi istediğiniz boyutta yapın.

• FullScreenPresenter

  Video izlemeye uygun tam ekran deneyimi sağlamak için bir pencere yapılandırılır. Pencerede kenarlık veya başlık çubuğu yoktur ve sistem görev çubuğunu gizler.

• ÇakışanÖner

  Varsayılan olarak yeniden boyutlandırma tutamaçlarına sahip bir kenarlık ve simge durumuna küçültme/büyütme/geri yükleme düğmeleri içeren bir başlık çubuğu sağlayan standart pencere yapılandırması.

Uyarı

Win32 uygulama modeline yeni bir kavram olarak, bir sunum, pencere durumu ve stillerinin bir kombinasyonuna benzer ama aynı şey değildir. Bazı sunum düzenleyicileri, klasik pencere durumunun ve stil özelliklerinin sınırları dışındaki (otomatik gizlenen başlık çubuğu gibi) kontrol edilemeyen davranışlara da sahiptir.

Varsayılan sunum yapan kişi

Oluşturulduğunda uygulanan AppWindow varsayılan sunucu, varsayılan özellik ayarlarına sahip bir OverlappedPresenter örneğidir. Başka bir sunum kontrolcüsü uyguladıktan sonra bir pencere için varsayılan sunum kontrolcüsüne geri dönmek amacıyla başvuruyu tutmanıza gerek yoktur. Bunun nedeni, sistemin bu sunucunun oluşturulduğu AppWindow için yaşam süresi boyunca aynı örneği tutmasıdır; ve AppWindow parametresiyle .SetPresenter yöntemini çağırarak onu yeniden uygulayabilirsiniz.

Önemli

SetPresenter(AppWindowPresenterKind.Default) çağrısı, AppWindow ile oluşturulan varsayılan sunucu örneğini tekrar uygular. Başka bir sunumcu oluşturup uyguladıysanız ve daha sonra yeniden uygulamak istiyorsanız, sunumcunuza referansını saklamanız gerekir.

Ayrıca varsayılan sunumcu örneğine başvuru alabilir ve bunu değiştirebilirsiniz. Yeni bir sunucu uyguladıysanız, önce burada gösterildiği gibi varsayılan sunucunun uygulandığından emin olun:

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

ÖrtüşenÖnericiyi Değiştirme

OverlappedPresenter, çeşitli yollarla yapılandırabileceğiniz esnek bir sunucudur.

Create* yöntemleri, varsayılan özellik ayarlarına sahip çakışmalı bir sunumcu veya belirli bir kullanım için önceden yapılandırılmış özellik ayarlarına sahip bir sunumcu oluşturmanıza olanak tanır.

Bu tabloda, her yöntemden bir OverlappedPresenter nesnesi oluşturduğunuzda yapılandırma özelliklerinin nasıl ayarlandığı gösterilir.

Mülkiyet	Create	CreateForContextMenu	CreateForDialog	CreateForToolWindow
HasBorder	true	true	true	true
HasTitleBar	true	false	true	true
IsAlwaysOnTop	false	false	false	false
MaksimizeEdilebilirMi	true	false	false	true
IsMinimizable	true	false	false	true
IsModal	false	false	false	false
IsResizable	true	false	false	true

Etkin sunum nesnesi canlı bir nesnedir. AppWindow.Presenter nesnesinin herhangi bir özelliği değiştirildiğinde, değişiklik anında etkili olur. Bu değişiklikleri size bildirecek olay yoktur, ancak geçerli değerlerin özelliklerini istediğiniz zaman de kontrol edebilirsiniz.

HasBorder ve HasTitleBar özellikleri salt okunur durumdadır. SetBorderAndTitleBar yöntemini (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)) çağırarak bu değerleri ayarlayabilirsiniz. Örtüşen Presenter, kenarlık olmadan bir başlık çubuğuna sahip olamaz. Eğer hasTitleBar parametresi true ise, o zaman hasBorder parametresi de true olmalıdır. Aksi takdirde, şu iletiyle bir özel durum oluşturulur:

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

Araç çubuğundaki büyütme düğmesini gizlemek için IsMaximizablefalse olarak ayarlayın. PreferredMaximumHeight veya PreferredMaximumWidth özelliklerini ayarlarsanız, bu özellikler pencere boyutunu ekranı kaplamış durumda bile kısıtladığı için bunu yapmanızı öneririz. Bu, Maximize yöntemine yapılan çağrıları etkilemez.

Araç çubuğundaki küçültme düğmesini gizlemek için IsMinimizablefalse olarak ayarlayın. Bu, Minimize yöntemine yapılan çağrıları etkilemez.

Yeniden boyutlandırma denetimlerini gizlemek ve kullanıcının pencereyi yeniden boyutlandırmasını önlemek için olarak ayarlayın. Bu, AppWindow.Resize yöntemine yapılan çağrıları etkilemez.

Bu pencereyi diğer pencerelerin üzerinde tutmak için IsAlwaysOnToptrue olarak ayarlayın. Yöntemlerden herhangi birini AppWindow.MoveInZOrder* çağırırsanız, bu özellik olsa bile pencerenin z sırasını değiştirmek için etkili olmaya truedevam eder.

Kullanıcının pencereyi genişletebileceği boyut üst sınırını kısıtlamak için PreferredMaximumHeight ve PreferredMaximumWidth'i ayarlayın. IsMaximizable öğesini false olarak ayarlamanızı öneririz, eğer maksimum boyut özelliklerini ayarladıysanız; bu özellikler ekran tamamen kaplandığında bile pencere boyutunu kısıtlar. Bu özellikler, AppWindow.Resize çağrılarını da etkiler; pencere, belirtilen en yüksek yükseklik ve genişliği aşacak şekilde yeniden boyutlandırılamaz.

Kullanıcının pencereyi küçültebileceği en düşük boyutu ayarlamak için PreferredMinimumHeight ve PreferredMinimumWidth değerlerini ayarlayın. Bu özellikler, AppWindow.Resize çağrılarını da etkiler; pencere, belirtilen minimum yükseklik ve genişlikten daha küçük olacak şekilde yeniden boyutlandırılmaz.

Modal pencereler

IsModal ayarını true olarak ayarlayarak bir modal pencere oluşturabilirsiniz. Modal pencere, kapatılana kadar sahip penceresi ile etkileşimi engelleyen ayrı bir penceredir. Ancak, modül pencere oluşturmak için sahip pencereyi de ayarlamanız gerekir; aksi takdirde, şu iletiyle bir hata oluşur:

The parameter is incorrect.

The window should have an owner when IsModal=true.

WinUI uygulamasında sahip pencere ayarlamak için Win32 interoperabilite gerekir. Daha fazla bilgi ve örnek kod için WinUI Galerisi örnek uygulamasındaki sayfaya bakın AppWindow .

• WinUI Galeri uygulamasını başlatma
• GitHub'da ModalWindow.xaml.cs açma

Sunumcu uygula

Sunum aracı bir defada yalnızca tek bir pencereye uygulanabilir. Aynı sunum aracını ikinci bir pencereye uygulamaya çalışmak istisna oluşturur. Başka bir deyişle, birden çok pencereniz varsa ve her birini belirli bir sunu moduna geçirmek istiyorsanız, aynı türden birden çok sunucu oluşturmanız ve ardından her birini kendi penceresine uygulamanız gerekir.

Yeni bir sunum yapan uygulandığında (AppWindow.Presenter özelliği değişir), bu durum uygulamanız üzerinde etkili olan AppWindow ile olayı aracılığıyla sizin tarafınıza bildirilir; AppWindow özelliği olarak ayarlanmıştır.

İpucu

Değiştirilmiş bir gösterici uygular ve göstericiler arasında değişim yapılmasına izin verirseniz, bu değiştirilen göstericiyi AppWindow'a yeniden uygulayabilmek için bir başvuru sakladığınızdan emin olun.

Bu örnekte aşağıdakilerin nasıl yapılacağını gösterilmektedir:

• Kullanın AppWindow.Presenter özelliğini geçerli sunucuyu almak için.
• Şu anda ne tür bir yapılandırma uygulandığını denetlemek için AppWindowPresenter.Kind özelliğini kullanın.
• AppWindowSetPresenter işlevini çağırarak geçerli yapılandırmayı değiştirin.

Burada, pencere oluşturucusunda bir sunumcu oluşturulur, değiştirilir ve uygulanır.

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

Pencere içeriği olan Sayfada ve uygulanan sunucuya AppWindow başvuru alabilirsiniz.

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 framework ve HWND etkileşimi

sınıfı AppWindow , uygulamanızdaki herhangi bir üst düzey HWND için kullanılabilir. Başka bir deyişle, bir masaüstü kullanıcı arabirimi çerçevesiyle (WinUI 3 dahil) çalışırken, bir pencere oluşturmak ve içeriğini eklemek için bu çerçevenin giriş noktasını kullanmaya devam edebilirsiniz. Bu kullanıcı arabirimi çerçevesiyle bir pencere oluşturduktan sonra, Windows Uygulama SDK'sında sağlanan pencere oluşturma birlikte çalışma işlevlerini (aşağıya bakın) kullanarak ilgili AppWindow yöntemlere, özelliklere ve olaylara erişebilirsiniz.

Kullanmanın AppWindow avantajlarından bazıları (ui çerçevesiyle çalışırken bile) şunlardır:

• Kolay başlık çubuğu özelleştirmesi; varsayılan olarak Windows 11 kullanıcı arabirimini korur (yuvarlatılmış köşeler, tutturulmuş grup açılır menüsü).
• Sistem tarafından sağlanan tam ekran ve kompakt katman (resim içinde resim) deneyimleri.
• Windows Runtime (WinRT) API'si, bazı temel Win32 pencereleme kavramları için bir kapsam sağlar.

Windows Uygulama SDK'sının veya diğer masaüstü uygulama çerçevelerinin 1.3 öncesi sürümlerini AppWindow edinin

Window.AppWindow özelliği Windows Uygulama SDK'sı sürüm 1.3 ve sonraki sürümlerde kullanılabilir. Önceki sürümler için bu bölümdeki işlevsel olarak eşdeğer kod örneğini kullanabilirsiniz.

C#. Pencereleme birlikte çalışma işlevleri için .NET sarmalayıcıları , Microsoft.UI.Win32Interop sınıfının yöntemleri olarak uygulanır. Ayrıca bkz. bir .NET uygulamasından birlikte çalışma API'lerini çağırma.

C++. Interop işlevleri winrt/Microsoft.ui.interop.h başlık dosyasında tanımlanır.

Aşağıdaki kod örneği bölümünde gerçek kaynak kodu gösterilmektedir; ancak mevcut bir pencere verilen bir AppWindow nesneyi alma tarifi aşağıda verilmiştir:

1. Mevcut pencere nesneniz (UI çerçeveniz için) için HWND'yi (henüz sahip değilseniz) alın.
2. HWND'yi GetWindowIdFromWindow birlikte çalışma işlevine bir WindowId almak için geçirin.
3. Bu WindowId değerini statik AppWindow.GetFromWindowId yöntemine geçirerek AppWindow'yi almak için kullanın.

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

ile AppWindowçalışma hakkında daha fazla örnek için bkz. Pencereleme galerisi örneği.

Sınırlamalar

Windows Uygulama SDK'sı şu anda bir AppWindowkullanıcı arabirimi çerçevesi içeriği eklemek için yöntemler sağlamaz.

İlgili konular

• Pencereye genel bakış
• Başlık çubuğu özelleştirme
• Pencereleme işlevselliğinin taşınması
• Bir .NET uygulamasından birlikte çalışma API'lerini çağırın
• Bir pencere tutamağını (HWND) alın
• Pencereleme galerisi örneği