ウィンドウ機能の移行

このトピックでは、UWP の ApplicationView/CoreWindow または AppWindow から Windows App SDK の Microsoft.UI.Windowing.AppWindow への移行を含め、ウィンドウ管理に関連するガイダンスを示します。

重要な API

• Microsoft.UI.Windowing.AppWindow
• Windows.UI.Core.CoreWindow.Dispatcher プロパティ
• Microsoft.UI.Window.DispatcherQueue プロパティ

API と機能の違いの概要

Windows App SDK には、Win32 HWND モデルをベースにした Microsoft.UI.Windowing.AppWindow クラスが用意されています。 その AppWindow クラスは、UWP の ApplicationView/CoreWindow および AppWindow の Windows App SDK バージョンです。

Windows App SDK ウィンドウ設定 API を利用するには、Win32 モデルを使用するように UWP コードを移行する必要があります。 Windows App SDK の AppWindow の詳細については、「アプリ ウィンドウの管理」を参照してください。

UWP と Windows App SDK のウィンドウの種類

UWP アプリでは、ApplicationView/CoreWindow、または AppWindow を使用してウィンドウ コンテンツをホストすることができます。 そのコードを Windows App SDK に移行するために必要な作業は、それら 2 つのウィンドウ モデルのうち、どちらを UWP アプリで使用しているかによって異なります。 UWP の Windows.UI.WindowManagement.AppWindow を使い慣れている場合は、それと Microsoft.UI.Windowing.AppWindow の間に類似点があることがわかるでしょう。

UWP のウィンドウの種類

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow。
• Windows.UI.WindowManagement.AppWindow。 AppWindow は、UI スレッドと、アプリでコンテンツの表示に使用するウィンドウを統合します。 AppWindow を使用している UWP アプリは、ApplicationView/CoreWindow のアプリよりも、Windows App SDK AppWindow への移行のために必要な作業が少なくて済みます。

Windows App SDK のウィンドウの種類

• Microsoft.UI.Windowing.AppWindow は、アプリのコンテンツのシステム マネージド コンテナーを表す高水準の抽象化です。

UWP と Win32 のウィンドウ モデルの違いとして、UWP API サーフェスと Windows App SDK API サーフェスの間には直接的な 1 対 1 の対応がないことに注意してください。 UWP から "引き継がれた" クラス名とメンバー名 (このトピックの対応表に反映されています) の場合でも、動作が異なる場合があります。

スプラッシュ画面

Win32 アプリでは、UWP アプリとは異なり、既定では起動時にスプラッシュ スクリーンが表示されません。 起動エクスペリエンスがこの機能に依存する UWP アプリの場合、最初のアプリ ウィンドウへのカスタム切り替えの実装を選択できます。

ウィンドウの作成、表示、閉じる、破棄

Microsoft.UI.Windowing.AppWindow の有効期間は、HWND の場合と同じです。つまり、AppWindow オブジェクトは、ウィンドウが作成された直後に使用可能になり、ウィンドウが閉じられたときに破棄されます。

作成と表示

AppWindow.Create は、既定の構成を使用してアプリ ウィンドウを作成します。 ウィンドウの作成と表示は、UI フレームワークを使用していないシナリオの場合にのみ必要です。 UWP アプリを Win32 と互換性のある UI フレームワークに移行する場合には、ウィンドウ相互運用メソッドを使用すれば、既に作成済みのウィンドウから引き続き AppWindow オブジェクトにアクセスできます。

閉じる

UWP では、ApplicationView.TryConsolidateAsync は、ユーザーが閉じるジェスチャを開始するのとプログラム的に同等です。 "統合" というこの概念 (UWP の ApplicationView/CoreWindow ウィンドウ モデル) は、Win32 には存在しません。 Win32 では、ウィンドウが分離スレッドに存在する必要はありません。 UWP の ApplicationView/CoreWindow ウィンドウ モデルを再現するには、開発者は新しいスレッドを作成し、そこで新しいウィンドウを作成する必要があります。 Win32 モデルの場合、既定のシステム動作は閉じる>非表示>破棄です。

ウィンドウの基本的なカスタマイズ

UWP から Windows App SDK に移行するときは、既定の AppWindow で同じエクスペリエンスを想定できます。 ただし必要に応じて、カスタマイズされたウィンドウ エクスペリエンスのために既定の Microsoft.UI.Windowing.AppWindow を変更できます。 ウィンドウをカスタマイズする方法の詳細については、「Microsoft.UI.Windowing.AppWindow」を参照してください。

ウィンドウのサイズ変更

ウィンドウの配置

ウィンドウのタイトル

コンパクト オーバーレイと全画面

コンパクト オーバーレイまたは全画面への切り替えを行うアプリでは、Windows App SDK の AppWindowPresenter を活用すると便利です。 UWP の AppWindow を使い慣れている場合は、既にプレゼンターの概念をご存じかもしれません。

UWP アプリ ウィンドウのプレゼンターと Windows App SDK アプリ ウィンドウのプレゼンターは、機能と動作が 1 対 1 に対応していません。 UWP ApplicationView/CoreWindow アプリを使用している場合、アプリでコンパクト オーバーレイ (ピクチャ イン ピクチャ) または全画面ウィンドウ エクスペリエンスを引き続き提供できますが、プレゼンターの概念はおそらく初めて知るものでしょう。 アプリ ウィンドウのプレゼンターの詳細については、「プレゼンター」を参照してください。 既定では、重複するプレゼンターが作成時に AppWindow に適用されます。 CompactOverlay と FullScreen は、既定のもの以外で使用可能な唯一のプレゼンターです。

コンパクト オーバーレイ

UWP の ApplicationViewMode または AppWindowPresentionKind を使用してコンパクト オーバーレイ ウィンドウを表示していた場合は、コンパクト オーバーレイの AppWindowPresenterKind を使用する必要があります。 Microsoft.UI.Windowing.CompactOverlayPresenter は、縦横比 16:9 の 3 つの固定ウィンドウ サイズのみをサポートしており、ユーザーはサイズを変更できません。 AppWindow の表示を変更するには、ApplicationViewMode.TryEnterViewModeAsync または AppWindowPresenterKind.RequestPresentation ではなく、AppWindow.SetPresenter を使用する必要があります。

全画面

UWP の ApplicationViewWindowingMode または AppWindowPresentionKind クラスを使用して全画面ウィンドウを表示していた場合は、全画面の AppWindowPresenterKind を使用する必要があります。 Windows App SDK は、最も制限の厳しい全画面エクスペリエンス (つまり、FullScreen が IsExclusive の場合) のみをサポートしています。 ApplicationView/CoreWindow の場合は、ApplicationView.ExitFullScreenMode を使用してアプリの全画面表示を解除することができます。 プレゼンターを使用する場合は、アプリの全画面表示を解除するには、AppWindow.SetPresenter を使用して、プレゼンターの設定をオーバーラップまたは既定に戻します。

アプリ ウィンドウのプレゼンターを操作する方法の詳細については、「ウィンドウ ギャラリーのサンプル」を参照してください。 さまざまなアプリ ウィンドウ プレゼンターの状態を切り替える方法を示しています。

カスタム タイトル バー

アプリで既定のタイトル バーを使用している場合は、Win32 に移行するときに、タイトル バーに関する追加の作業は必要ありません。 一方、UWP アプリでカスタム タイトル バーを使用している場合は、Windows App SDK アプリで次のシナリオを再作成することができます。

1. システムによって表示されるタイトル バーをカスタマイズする
2. アプリで表示するカスタム タイトル バー

UWP の ApplicationViewTitleBar、CoreApplicationViewTitleBar、AppWindowTitleBar クラスを使用しているコードは、Windows App SDK の Microsoft.UI.Windowing.AppWindowTitleBar クラスを使用するように移行します。

システムによって表示されるタイトル バーをカスタマイズする

色のカスタマイズ API の表を次に示します。

次の Windows App SDK API は、AppWindow.Title API に加えて、システムによって表示されるタイトル バーをさらにカスタマイズするためのものです。

• AppWindow.SetIcon。 hIcon ハンドルを使用するか、リソースまたはファイルへの文字列パスを使用して、タイトル バーとタスク バーのアイコン画像を設定します。
• AppWindowTitleBar.IconShowOptions。 ウィンドウ アイコンをタイトル バーにどのように表示するかを指定する値を取得または設定します。 現在サポートされている値は、HideIconAndSystemMenu と ShowIconAndSystemMenu の 2 つです。
• AppWindowTitleBar.ResetToDefault。 現在のタイトル バーをウィンドウの既定の設定に戻します。

アプリで表示するカスタム タイトル バー (完全なカスタマイズ)

移行して AppWindowTitleBar を使用する場合は、コードで次のカスタム タイトル バー API を呼び出す前に、AppWindowTitleBar.IsCustomizationSupported を確認することをお勧めします。

これらの Windows App SDK API は、タイトル バーの完全なカスタマイズ用です。

• AppWindowTitleBar.SetDragRectangles。 ウィンドウのドラッグ領域を設定します。
• AppWindowTitleBar.ResetToDefault。 現在のタイトル バーをウィンドウの既定の設定に戻します。

これらの UWP AppWindow API は、Windows App SDK API と 1 対 1 で直接対応はしていません。

• AppWindowTitleBarVisibility。 AppWindowTitleBar の優先の表示を指定する定数を定義します。
• AppWindowTitleBar.GetPreferredVisibility。 タイトル バーの優先表示モードを取得します。
• AppWindowTitleBar.SetPreferredVisibility。 タイトル バーの優先表示モードを設定します。

AppWindowTitleBar を使用した作業の詳細については、「ウィンドウ ギャラリーのサンプル」を参照してください。 それには、カスタム色のタイトル バーを作成する方法と、カスタム タイトル バーを表示する方法が示されています。

イベント処理

UWP アプリで AppWindow.Changed イベントを使用している場合は、そのコードを Microsoft.UI.Windowing.AppWindow.Changed イベントに移行できます。

サイズ変更イベント

サイズ変更イベント処理コードを移行する場合は、Windows App SDK の AppWindowChangedEventArgs.DidSizeChange プロパティを使用するように切り替える必要があります。 値は、アプリ ウィンドウのサイズが変更された場合は true、それ以外の場合は false です。

MainPage と MainWindow

Visual Studio で新しい UWP プロジェクトを作成するとき、プロジェクト テンプレートに MainPage クラスが用意されています。 アプリでは、そのクラスの名前を変更している可能性があります (また、ページとユーザー コントロールを追加した可能性があります)。 プロジェクト テンプレートには、App クラスのメソッドにナビゲーション コードも用意されています。

Visual Studio で新しい Windows App SDK プロジェクトを作成すると、プロジェクト テンプレートには MainWindow クラス (Microsoft.UI.Xaml.Window 型) が用意されていますが、Page はありません。 また、プロジェクト テンプレートにはナビゲーション コードが用意されていません。

ただし、Windows App SDK プロジェクトにページとユーザー コントロールを追加することもできます。 たとえば、プロジェクトに新しいページ項目を追加して (WinUI>空白のページ (WinUI 3))、MainPage.xaml という名前や他の名前を付けることができます。 そうすると、Microsoft.UI.Xaml.Controls.Page 型の新しいクラスがプロジェクトに追加されます。 それから、プロジェクトへのナビゲーション コードの追加に関する情報について「ページ ナビゲーションを実装する必要がありますか」を参照してください。

Windows Apps SDK アプリが十分にシンプルな場合、ページやユーザー コントロールを作成する必要はなく、XAML マークアップと分離コードを MainWindow にコピーできます。 ただし、そのワークフローの例外については、「ビジュアル状態マネージャーと Page.Resources」を参照してください。

CoreWindow.Dispatcher を DispatcherQueue に変更する

UWP の Windows.UI.Core.CoreWindow クラスの一部のユース ケースは、Windows App SDK の Microsoft.UI.Xaml.Window に移行します。

たとえば、UWP アプリで Windows.UI.Core.CoreWindow.Dispatcher プロパティを使用している場合、解決策は Microsoft.UI.Xaml.Window.Dispatcher プロパティ (常に null が返される) に移行することでは "ありません"。 代わりに、Microsoft.UI.Xaml.Window.DispatcherQueue プロパティに移行します。これにより、Microsoft.UI.Dispatching.DispatcherQueue が返されます。

詳細とコード例については、「Windows.UI.Core.CoreDispatcher を Microsoft.UI.Dispatching.DispatcherQueue に変更する」を参照してください。

関連トピック

• Windows App SDK およびサポートされている Windows リリース
• スレッド機能の移行