WinUI と Windows App SDK のウィンドウの概要

WinUI アプリのウィンドウ機能は、XAML Window クラスと AppWindow クラスの組み合わせによって提供されます。どちらも Win32 HWND モデルに基づいています。

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

XAML Window

アプリでは、ウィンドウ オブジェクトは、プログラム コード内のウィンドウを表す Microsoft.UI.Xaml.Window クラス (または派生クラス) のインスタンスです。 コンストラクターを呼び出して直接作成します。 XAML Window では、アプリのコンテンツをアタッチし、アプリのウィンドウのライフサイクルを管理します。

HWND

アプリケーション ウィンドウは、Windows オペレーティング システムによって作成され、Win32 ウィンドウ オブジェクトによって表されます。 これは、コンテンツがホストされるシステム管理コンテナーであり、ユーザーが画面上でアプリのサイズを変更して移動するときに操作するエンティティを表します。 (詳細については、Win32 ドキュメントの「Windowsについて」を参照してください)。

アプリケーション ウィンドウ Windows 作成した後、作成関数はウィンドウを一意に識別する window handle (HWND) を返します。 window handleには HWND データ型がありますが、C# では IntPtr として表示されます。 これは、OS によって描画され、存在するときにシステム リソースを消費するウィンドウに対応する内部の Windows データ構造への不透明なハンドルです。

HWND は、XAML Window オブジェクトの後に作成されます。通常は Window.Activate メソッドが呼び出される際に作成されます。

AppWindow

Windows App SDK は、Microsoft.UI.Windowing.AppWindow クラスを通じて追加のウィンドウ機能を提供します。 AppWindow は、HWND の高度な抽象化を表します。 アプリの AppWindow と最上位の HWND の間には、1 対 1 のマッピングがあります。 AppWindow および関連するクラスには、HWND に直接アクセスする必要なく、アプリのトップレベル ウィンドウのさまざまな側面を管理できる API が用意されています。

AppWindow オブジェクトと HWND の有効期間は同じです。AppWindowはウィンドウが作成された直後に使用でき、ウィンドウが閉じられると破棄されます。

ウィンドウ化 API の図

この図は、アプリでウィンドウを管理するために使用するクラスと API の関係と、ウィンドウ管理の各部分を担当するクラスを示しています。 場合によっては、 ExtendsContentIntoTitleBarのように、API は他の UI フレームワークで使用できるようにするための AppWindow のメンバーですが、便宜上、 Window クラスでも公開されます。 この図は包括的ではありませんが、最も一般的に使用される API を示しています。

Window/AppWindow API の比較

アプリの UI フレームワークとして WinUI 3 XAML を使用する場合は、 Window API と AppWindow API の両方を使用できます。 Windows App SDK 1.4 以降では、Window.AppWindow プロパティを使用して、既存の XAML ウィンドウからAppWindow オブジェクトを取得できます。 この AppWindow オブジェクトを使用すると、追加のウィンドウ管理 API にアクセスできます。

有効期間管理

Visual Studio で新しい WinUI プロジェクトを作成すると、プロジェクト テンプレートには MainWindow クラスが用意されています。これは Windowのサブクラスです。 アプリに必要なウィンドウが 1 つだけの場合は、これですべて必要になります。 追加のウィンドウを作成および管理する方法と、必要な理由については、「 アプリに複数のウィンドウを表示する」を参照してください。

AppWindow クラスには、新しいウィンドウを作成および破棄するための API があります。ただし、WinUI アプリの場合は、作成するウィンドウにコンテンツをアタッチする API がないため、実際にはこれを行いません。 代わりに、システムによって作成され、XAML AppWindowと HWND に関連付けられているWindowのインスタンスを取得します。 WinUI 1.4 以降では、 Window.AppWindow プロパティを使用して、 AppWindowのインスタンスを取得できます。 他のケースでは、AppWindow.GetFromWindowId メソッドを使用してAppWindow インスタンスを取得できます。 詳細については、「 アプリ ウィンドウの管理 」を参照してください。

Content

Window。Content プロパティは、アプリコンテンツを表示するウィンドウに添付する場所です。 これは XAML またはコードで行うことができます。

タイトル、アイコン、タイトル バー

アプリのタイトル バーをさまざまな角度に変更できます。タイトルとアイコンの設定、色の変更、またはタイトル バーをカスタム アプリ コンテンツに完全に置き換えます。

コード例を含むタイトル バー API の使用については、「 タイトル バーのカスタマイズ」を参照してください。

サイズと位置

アプリの UI 内で、Window.Bounds プロパティと SizeChanged イベントを使用して、ウィンドウ サイズが変更されたときに要素の移動などの管理を行います。 XAML では、実際の物理ピクセルではなく effective pixels (epx) が使用されます。 Effective pixels は仮想測定単位であり、画面密度に関係なく、レイアウトの寸法と間隔を表すために使用されます。

AppWindow一方、基本的な測定単位は物理Windowである座標系を使用します。 ウィンドウのサイズを変更したり、画面上の他の何かに関連して移動したりするなどのウィンドウ操作には、 AppWindow API を使用します。

場合によっては、他のクラスの 1 つのクラスの測定値を使用する必要がある場合があります。その場合は、 effective pixels ピクセルとデバイス ピクセルの間で変換する必要があります。 たとえば、カスタム タイトル バーでドラッグ領域を設定する場合は、測定値を変換する必要があります。 XamlRoot.RasterizationScale を使用して測定値を変換する方法の例については、タイトル バーのカスタマイズに関する記事の対話型コンテンツセクションを参照してください。

外観と動作

XAML Window API は、一般に、バックグラウンドなどのアプリ コンテンツの外観を担当します。 SystemBackdrop の詳細については、「マイカまたはアクリル素材を適用する」を参照してください。

AppWindow API は、ウィンドウの クライアント以外 の部分と、 Windows OS とのアプリの対話を担当します。

現在のウィンドウを追跡する

Current プロパティは WinUI アプリではサポートされていませんが、アプリ内の他の場所からWindow API にアクセスすることが必要な場合があります。 たとえば、Window 境界の取得が必要になる場合や、Window のコードから .SizeChanged イベントの処理が必要になる場合があります。 この場合、Window クラスのパブリック静的プロパティを使用して、Current プロパティと同様の方法でAppへのアクセスを提供できます。

これを行うには、次に示すように、App クラスの Window 宣言を変更します。

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

次に、アプリ内の他の場所から Window にアクセスするには、次のように App.Windowを使用します。

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

関連トピック

• アプリ ウィンドウの管理
• ウィンドウ機能の移行
• .NET アプリから相互運用機能 API を呼び出す
• window handle (HWND) を取得する
• ウィンドウ ギャラリー サンプル