アプリ ウィンドウの管理

Windows アプリ SDKは、HWND の高度な抽象化を表す Microsoft.UI.Windowing.AppWindow クラスを提供します。 アプリの と最上位の HWND の間には、1 対 1 のマッピングがあります。 とそれに関連するクラスは、HWND を直接accessすることなく、アプリのトップレベル ウィンドウのさまざまな側面を管理できる API を提供します。

WinUI 3 ギャラリー アイコン

WinUI 3 ギャラリー アプリには、WinUI コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを取得するか、GitHub でソース コードを参照します。

Windows アプリ SDKがサポートする任意の UI フレームワーク (WinUI、WPF、WinForms、Win32) で、AppWindow API を使用できます。 API は、フレームワーク固有のウィンドウ API と共に機能します。

• Xaml
• WPF Window
• Windows フォーム フォーム
• Win32 ウィンドウ API、MFC Windows

通常、 API は次の用途に使用します。

• アプリのウィンドウのサイズと位置を管理します。

• ウィンドウのタイトル、アイコン、タイトル バーの色を管理します。または、 AppWindowTitleBar API を使用して完全にカスタムのタイトル バーを作成します。

  詳細と例については、「 タイトル バーのカスタマイズ 」を参照してください。

• AppWindowPresenter から派生した API を使用して、ウィンドウの外観と動作を管理します。

の変更に対応する

1 つの イベントを処理し、イベント引数 (AppWindowChangedEventArgs) を調べて、発生した変更の種類を確認することで、への変更に応答します。 関心のある変更が発生した場合は、それに対応できます。 潜在的な変更には、位置、サイズ、発表者、可視性、z オーダーが含まれます。

.Changed イベント ハンドラーの例を次に示します。

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

サイズと配置

クラスには、ウィンドウのサイズと配置を管理するために使用できるいくつかのプロパティとメソッドがあります。

[ サイズ変更] を呼び出して、新しいウィンドウ サイズを指定します。

この例では、コードは であるため、 . プロパティを使用して インスタンスを取得できます。

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

Move メソッドを呼び出して、ウィンドウの位置を変更します。

次の使用例は、ユーザーがボタンをクリックしたときにウィンドウを画面の中央に移動します。

これは、Page クラスのコード ファイルで発生するため、 または オブジェクトへのaccessは自動的に行われません。 を取得するには、いくつかのオプションがあります。

• 「」または「のする」の説明に従ってへの参照を保持している場合は、を取得し、 プロパティからを取得できます。
• または、ここで示すように、静的.GetFromWindowId メソッドを呼び出して、 インスタンスを取得できます。 ( ビジュアル要素をホストしているウィンドウの決定を参照してください)。

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 クラスとサブクラス

各にはAppWindowPresenter（プレゼンター）が適用されています。 プレゼンターはシステムによって作成され、 の作成時に適用されます。 AppWindowPresenter の各サブクラスには、ウィンドウの目的に適した定義済みの構成が用意されています。 これらの AppWindowPresenter から派生した発表者が提供され、サポートされているすべての OS バージョンで使用できます。

• CompactOverlayPresenter

  画面の縦横比が16:9で固定サイズの常に最前面ウィンドウを構成して、ピクチャインピクチャのようなエクスペリエンスを可能にします。 既定では、 InitialSize は CompactOverlaySize.Small ですが、 または に変更できます。 を呼び出すこともできます。サイズを変更して 16:9 の縦横比をオーバーライドし、ウィンドウを任意のサイズにします。

• FullScreenPresenter

  ビデオの視聴に適した全画面表示エクスペリエンスを提供するようにウィンドウを構成します。 ウィンドウに罫線またはタイトル バーがないため、システム タスク バーが非表示になります。

• オーバーラップドプレゼンター

  標準のウィンドウ構成では、既定では、サイズ変更ハンドルを含む境界線と、最小化/最大化/復元ボタンを含むタイトル バーが提供されます。

既定の発表者

の作成時に適用される既定の発表者は、既定のプロパティ設定を持つ OverlappedPresenter のインスタンスです。 別の発表者を適用した後、ウィンドウの既定の発表者に戻るために参照を保持する必要はありません。 これは、システムがのライフタイム中、このプレゼンターの同じインスタンスを保持するためであり、.SetPresenterメソッドをAppWindowPresenterKind.Defaultをパラメーターとして呼び出すことで再適用できます。

また、既定の発表者インスタンスへの参照を取得して変更することもできます。 新しい発表者を適用した場合は、次に示すように、最初に既定の発表者が適用されていることを確認します。

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

OverlappedPresenter を変更する

OverlappedPresenter は、さまざまな方法で構成できる柔軟な発表者です。

* メソッドを使用すると、既定のプロパティ設定、または特定の用途用に事前に構成されたプロパティ設定を持つ重複する発表者を作成できます。

次の表は、各メソッドから OverlappedPresenter オブジェクトを作成するときの構成プロパティの設定方法を示しています。

適用されたプレゼンターはライブ オブジェクトです。 のPresenterオブジェクトの任意のプロパティに対する変更はすぐに有効になります。 これらの変更を通知するイベントはありませんが、現在の値のプロパティはいつでも確認できます。

HasBorder プロパティと HasTitleBar プロパティは読み取り専用です。 これらの値は 、SetBorderAndTitleBar メソッド () を呼び出すことによって設定できます。 OverlappedPresenter は、罫線のないタイトル バーを持つことはできません。 つまり、 パラメーターが されている場合は、 パラメーターも する必要があります。 それ以外の場合は、次のメッセージで例外がスローされます。

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

ツールバーの最大化ボタンを非表示にするには、 IsMaximizable を に設定します。 プロパティまたはプロパティを設定する場合は、ウィンドウ サイズが最大化された状態でも制約されるため、これを行うことをお勧めします。 これは、 Maximize メソッドの呼び出しには影響しません。

IsMinimizable を に設定すると、ツールバーの最小化ボタンが非表示になります。 これは 、Minimize メソッドの呼び出しには影響しません。

IsResizable を に設定すると、サイズ変更コントロールが非表示になり、ユーザーがウィンドウのサイズを変更できなくなります。 これは、 メソッドの呼び出しには影響しません。

IsAlwaysOnTop を に設定すると、このウィンドウが他のウィンドウの上に表示されます。 メソッドのいずれかを呼び出しても、このプロパティがされている場合でも、ウィンドウの z オーダーを変更するために有効になります。

PreferredMaximumHeight と PreferredMaximumWidth を設定して、ユーザーがウィンドウを拡大できる最大サイズを制限します。 最大サイズのプロパティを設定する場合は、 を に設定することをお勧めします。これらのプロパティは、最大化された状態でもウィンドウ サイズを制限するためです。 これらのプロパティは、の呼び出しにも影響します。サイズ変更;ウィンドウのサイズは、指定された最大の高さと幅を超えるサイズに変更されません。

PreferredMinimumHeight と PreferredMinimumWidth を設定して、ユーザーがウィンドウを縮小できる最小サイズを設定します。 これらのプロパティは、の呼び出しにも影響します。サイズ変更;ウィンドウのサイズは、指定された最小の高さと幅よりも小さくされません。

モーダル ウィンドウ

IsModal を に設定すると、モーダル ウィンドウを作成できます。 モーダル ウィンドウは、ウィンドウが閉じられるまで 、その所有者ウィンドウ との対話をブロックする別のウィンドウです。 ただし、モーダル ウィンドウを作成するには、所有者ウィンドウも設定する必要があります。それ以外の場合は、次のメッセージで例外がスローされます。

The parameter is incorrect.

The window should have an owner when IsModal=true.

WinUI アプリで所有者ウィンドウを設定するには、Win32 相互運用機能が必要です。 詳細とコード例については、WinUI 3 ギャラリー サンプル アプリの ページを参照してください。

• WinUI 3 ギャラリー アプリを起動する
• GitHub

プレゼンターを適用する

プレゼンターは、一度に 1 つのウィンドウにのみ適用できます。 2 番目のウィンドウに同じ発表者を適用しようとすると、例外が発生します。 これは、複数のウィンドウがあり、それぞれを特定のプレゼンテーション モードに切り替える必要がある場合に、同じ種類の複数のプレゼンターを作成し、それぞれを独自のウィンドウに適用する必要があるということです。

新しいプレゼンターが適用されたとき (.Presenter プロパティが変更されたとき)、影響を受けたにおいて、 イベントによりアプリに通知され、AppWindowChangedEventArgs.DidPresenterChange プロパティが に設定されます。

この例では、次の方法を示します。

• .Presenter プロパティを使用して現在のプレゼンターを取得します。
• AppWindowPresenter.Kind プロパティを使用して、現在適用されている構成の種類を確認します。
• .SetPresenterを呼び出して、現在の構成を変更します。

ここでは、ウィンドウのコンストラクターでプレゼンターが作成され、変更され、適用されます。

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

ウィンドウコンテンツである ページ では、 と適用された発表者への参照を取得できます。

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 フレームワークと HWND の相互運用性

クラスは、アプリ内の任意の最上位 HWND で使用できます。 つまり、デスクトップ UI フレームワーク (WinUI を含む) を使用している場合は、そのフレームワークのエントリ ポイントを引き続き使用してウィンドウを作成し、そのコンテンツを添付できます。 また、その UI フレームワークを使用してウィンドウを作成したら、Windows アプリ SDKで提供されているウィンドウ相互運用機能 (下記参照) を使用して、対応する AppWindow とそのメソッド、プロパティ、およびイベントにアクセスできます。

(UI フレームワークを使用する場合でも) を使用する利点の一部は次のとおりです。

• 簡単なタイトルバーのカスタマイズ。既定では、Windows 11 UI (角丸み、スナップ グループポップアップ) が維持されます。
• システムが提供する全画面表示およびコンパクトオーバーレイ（ピクチャー・イン・ピクチャー）機能。
• Win32 ウィンドウの主要な概念の一部に対応する Windows ランタイム (WinRT) API サーフェス。

1.3 より前のバージョンのWindows アプリ SDK (または他のデスクトップ アプリ フレームワーク) のAppWindowを取得する

Window.AppWindow プロパティは、バージョン 1.3 以降Windows アプリ SDK使用できます。 以前のバージョンでは、このセクションの機能的に同等のコード例を使用できます。

C#. ウィンドウ相互運用機能の.NETラッパーは、Microsoft.UI.Win32Interop クラスのメソッドとして実装されます。 .NET アプリから Call 相互運用 API を呼び出すも参照してください。

C++。 相互運用機能は、 winrt/Microsoft.ui.interop.h ヘッダー ファイルで定義されています。

次のコード例セクションは、実際のソース コードを示しています。しかし、既存のウィンドウを指定して オブジェクトを取得するためのレシピを次に示します。

1. 既存のウィンドウ オブジェクト (UI フレームワーク用) の HWND を取得します (まだない場合)。
2. その HWND を GetWindowIdFromWindow 相互運用関数に渡して 、WindowId を取得します。
3. その WindowId を静的メソッド.GetFromWindowIdに渡してを取得します。

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

の操作方法の他の例については、Windowing ギャラリーのサンプルを参照してください。

制限事項

Windows アプリ SDKでは現在、UI フレームワークコンテンツをAppWindowにアタッチするためのメソッドは提供されていません。

関連トピック

• ウィンドウの概要
• タイトル バーのカスタマイズ
• ウィンドウ機能の移行
• .NET アプリから相互運用 API を呼び出します
• ウィンドウ ハンドル (HWND) を取得する
• ウィンドウ ギャラリーのサンプル