C++/WinRT を使用して XAML コントロールを作成する

[アーティクル]
07/09/2024

この記事では、C++/WinRT で WinUI 3 のテンプレート化された XAML コントロールを作成する手順について説明します。テンプレート化されたコントロールは Microsoft.UI.Xaml.Controls.Control から継承され、XAML コントロールテンプレートを使用してカスタマイズできる視覚的な構造と視覚的な動作を持っています。この記事では、記事「C++/WinRT による XAML カスタム (テンプレート化) コントロール」と同じシナリオについて説明しますが、WinUI 3 を使用するように調整されています。

前提条件

WinUI の概要
C++/WinRT Visual Studio Extension (VSIX) の最新版をダウンロードしてインストールします。

空のアプリを作成する (BgLabelControlApp)

まず、Microsoft Visual Studio で、新しいプロジェクトを作成します。 [Create a new project] ダイアログで、[空のアプリ (UWP 内の WinUI)] プロジェクトテンプレートを選択します。このとき、必ず C++ 言語バージョンを選択します。プロジェクト名を "BgLabelControlApp" に設定して、ファイル名が次の例のコードと一致するようにします。 [ターゲットバージョン] を Windows 10 バージョン 1903 (ビルド 18362) に、[最小バージョン] を Windows 10 バージョン 1803 (ビルド 17134) に設定します。このチュートリアルは、 [Blank App, Packaged (WinUI in Desktop)](空のアプリ、パッケージ (デスクトップの WinUI)) プロジェクトテンプレートを使用して作成するデスクトップアプリでも有効です。BgLabelControlApp (デスクトップ) のすべての手順は必ず実行してください。

空のアプリプロジェクトテンプレート

テンプレートコントロールをアプリに追加する

テンプレートコントロールを追加するには、ツールバーの [プロジェクト] メニューをクリックするか、ソリューションエクスプローラーでプロジェクトを右クリックし、[新しい項目の追加] を選択します。 [Visual C++]->[WinUI] の下で、[カスタムコントロール (WinUI)] テンプレートを選択します。新しいコントロールに "BgLabelControl" という名前を指定し、[追加] をクリックします。これにより、3 つの新しいファイルがプロジェクトに追加されます。 BgLabelControl.h はコントロールの宣言を含むヘッダーで、BgLabelControl.cpp にはこのコントロールの C++/WinRT 実装が含まれています。 BgLabelControl.idl は、コントロールをランタイムクラスとしてインスタンス化できるようにするインターフェイス定義ファイルです。

BgLabelControl カスタムコントロールクラスを実装する

以下の手順で、ランタイムクラスを実装するために、プロジェクトディレクトリ内の BgLabelControl.idl、BgLabelControl.h、BgLabelControl.cpp ファイルのコードを更新します。

テンプレートコントロールクラスは XAML マークアップからインスタンス化されます。そのため、ランタイムクラスになります。完成したプロジェクトをビルドすると、MIDL コンパイラ (midl.exe) により BgLabelControl.idl ファイルを使用してコントロールの Windows ランタイムメタデータファイル (.winmd) が生成されます。これが、コンポーネントのコンシューマーによって参照されます。ランタイムクラスの作成の詳細については、「C++/WinRT での API の作成」をご覧ください。

ここで作成しているテンプレートコントロールでは、コントロールのラベルとして使用される文字列である、1 つのプロパティが公開されます。 BgLabelControl.idl の内容を次のコードに置き換えます。

// BgLabelControl.idl
namespace BgLabelControlApp
{
    runtimeclass BgLabelControl : Microsoft.UI.Xaml.Controls.Control
    {
        BgLabelControl();
        static Microsoft.UI.Xaml.DependencyProperty LabelProperty{ get; };
        String Label;
    }
}

上記の一覧は、依存関係プロパティ (DP) を宣言するときに従うパターンを示しています。各 DP には 2 つの部分があります。まず、DependencyProperty 型の読み取り専用の静的プロパティを宣言します。名前は、お使いの DP に Property を加えたものになります。実装ではこの静的プロパティを使用します。次に、DP の型と名前持つ読み取りおよび書き込みインスタンスプロパティを宣言します。 (DP ではなく) 添付プロパティを作成する場合は、「カスタム添付プロパティ」のコード例を参照してください。

上記のコードで参照されている XAML クラスは、Microsoft.UI.Xaml 名前空間に存在していることに注意してください。これによってこれらは Windows.UI.XAML 名前空間に定義される UWP XAML コントロールではなく、WinUI コントロールとして区別されます。

BgLabelControl.h の内容を次のコードに置き換えます。

// BgLabelControl.h
#pragma once
#include "BgLabelControl.g.h"

namespace winrt::BgLabelControlApp::implementation
{
    struct BgLabelControl : BgLabelControlT<BgLabelControl>
    {
        BgLabelControl() { DefaultStyleKey(winrt::box_value(L"BgLabelControlApp.BgLabelControl")); }

        winrt::hstring Label()
        {
            return winrt::unbox_value<winrt::hstring>(GetValue(m_labelProperty));
        }

        void Label(winrt::hstring const& value)
        {
            SetValue(m_labelProperty, winrt::box_value(value));
        }

        static Microsoft::UI::Xaml::DependencyProperty LabelProperty() { return m_labelProperty; }

        static void OnLabelChanged(Microsoft::UI::Xaml::DependencyObject const&, Microsoft::UI::Xaml::DependencyPropertyChangedEventArgs const&);

    private:
        static Microsoft::UI::Xaml::DependencyProperty m_labelProperty;
    };
}
namespace winrt::BgLabelControlApp::factory_implementation
{
    struct BgLabelControl : BgLabelControlT<BgLabelControl, implementation::BgLabelControl>
    {
    };
}

上に示されているコードでは、Label プロパティと LabelProperty プロパティを実装し、依存関係プロパティの値の変更を処理するための OnLabelChanged という名前の静的イベントハンドラーを追加し、LabelProperty のバッキングフィールドを格納するためのプライベートメンバーを追加しています。ここでも、ヘッダーファイルで参照される XAML クラスは、UWP UI フレームワークによって使用される Windows.UI.Xaml 名前空間ではなく、WinUI 3 フレームワークに属する Microsoft.UI.Xaml 名前空間に存在していることに注意してください。

次に、BgLabelControl.cpp の内容を次のコードに置き換えます。

// BgLabelControl.cpp
#include "pch.h"
#include "BgLabelControl.h"
#if __has_include("BgLabelControl.g.cpp")
#include "BgLabelControl.g.cpp"
#endif

namespace winrt::BgLabelControlApp::implementation
{
    Microsoft::UI::Xaml::DependencyProperty BgLabelControl::m_labelProperty =
        Microsoft::UI::Xaml::DependencyProperty::Register(
            L"Label",
            winrt::xaml_typename<winrt::hstring>(),
            winrt::xaml_typename<BgLabelControlApp::BgLabelControl>(),
            Microsoft::UI::Xaml::PropertyMetadata{ winrt::box_value(L"default label"), Microsoft::UI::Xaml::PropertyChangedCallback{ &BgLabelControl::OnLabelChanged } }
    );

    void BgLabelControl::OnLabelChanged(Microsoft::UI::Xaml::DependencyObject const& d, Microsoft::UI::Xaml::DependencyPropertyChangedEventArgs const& /* e */)
    {
        if (BgLabelControlApp::BgLabelControl theControl{ d.try_as<BgLabelControlApp::BgLabelControl>() })
        {
            // Call members of the projected type via theControl.

            BgLabelControlApp::implementation::BgLabelControl* ptr{ winrt::get_self<BgLabelControlApp::implementation::BgLabelControl>(theControl) };
            // Call members of the implementation type via ptr.
        }
    }
}

このチュートリアルでは OnLabelChanged コールバックは使用しませんが、プロパティ変更コールバックを使用して依存関係プロパティを登録する方法を確認できるようにするためにこれが用意されています。 OnLabelChanged の実装では、投影された基本型から投影された派生型を取得する方法も示しています (ここでは、投影された基本型は DependencyObject です)。また、プロジェクションが実行された型を実装する型へのポインターを取得する方法を示しています。その 2 番目の操作は、当然ながら、プロジェクションが実行された型を実装するプロジェクト (つまり、ランタイムクラスを実装するプロジェクト) でのみ可能です。

WinUI 3 プロジェクトテンプレートに既定で含まれていない xaml_typename 関数は、Windows.UI.Xaml.Interop 名前空間によって提供されます。この名前空間に関連付けられているヘッダーファイルを含めるために、プロジェクトのプリコンパイル済みヘッダーファイル pch.h に 1 行追加します。

// pch.h
...
#include <winrt/Windows.UI.Xaml.Interop.h>
...

BgLabelControl の既定のスタイルを定義する

そのコンストラクター内で、BgLabelControl によってそれ自体の既定のスタイルキーが設定されます。テンプレートコントロールには、コントロールのコンシューマーがスタイルやテンプレートを設定しない場合にレンダリングするために使用できる既定のコントロールテンプレートが含まれている、既定のスタイルを指定する必要があります。このセクションでは、既定のスタイルを含むマークアップファイルをプロジェクトに追加します。

(ソリューションエクスプローラーで) [すべてのファイルを表示] がまだオンになっていることを確認します。プロジェクトノードで、新しいフォルダー (フィルターではなくフォルダー) を作成し、"Themes" という名前を付けます。 Themes の下に、種類が [Visual C++]>[WinUI]>[リソースディレクトリ (WinUI)] である新しい項目を追加し、"Generic.xaml" という名前を付けます。 XAML フレームワークでテンプレートコントロールの既定のスタイルを検出するために、フォルダーとファイルの名前をこのようにする必要があります。 Generic.xaml の既定のコンテンツを削除し、以下のマークアップを貼り付けます。

<!-- \Themes\Generic.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:BgLabelControlApp">

    <Style TargetType="local:BgLabelControl" >
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="local:BgLabelControl">
                    <Grid Width="100" Height="100" Background="{TemplateBinding Background}">
                        <TextBlock HorizontalAlignment="Center" VerticalAlignment="Center" Text="{TemplateBinding Label}"/>
                    </Grid>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>

この場合、既定のスタイルに設定される唯一のプロパティはコントロールテンプレートです。テンプレートは、1 つの正方形 (背景は XAML Control 型のすべてのインスタンスに設定される Background プロパティにバインドされています) と、1 つのテキスト要素 (テキストは BgLabelControl::Label 依存関係プロパティにバインドされています) で構成されます。

メイン UI ページに BgLabelControl のインスタンスを追加する

MainWindow.xaml を開くと、メイン UI ページの XAML マークアップが含まれています。 Button 要素の直後 (StackPanel 内) に次のマークアップを追加します。

<local:BgLabelControl Background="Red" Label="Hello, World!"/>

また、MainWindow 型 (XAML マークアップと命令型コードのコンパイルの組み合わせ) で BgLabelControl テンプレートコントロール型が認識されるように、MainWindow.h に次の include ディレクティブを追加します。他の XAML ページから BgLabelControl を使用する場合は、そのページのヘッダーファイルにも同じ include ディレクティブを追加します。または、単にプリコンパイル済みヘッダーファイルに 1 つの include ディレクティブを追加します。

//MainWindow.h
...
#include "BgLabelControl.h"
...

ここでプロジェクトをビルドして実行します。既定のコントロールテンプレートが、マークアップの BgLabelControl インスタンスの背景ブラシとラベルにバインドされることがわかります。

テンプレートコントロールの結果

MeasureOverride や OnApplyTemplate などのオーバーライド可能な関数の実装

テンプレートコントロールは Control ランタイムクラスから派生し、それ自体も基本ランタイムクラスから派生します。また、派生クラスでオーバーライドできる Control、FrameworkElement、および UIElement というオーバーライド可能なメソッドがあります。この方法を示すコード例を次に示します。

// Control overrides.
void OnPointerPressed(Microsoft::UI::Xaml::Input::PointerRoutedEventArgs const& /* e */) const { ... };

// FrameworkElement overrides.
Windows::Foundation::Size MeasureOverride(Windows::Foundation::Size const& /* availableSize */) const { ... };
void OnApplyTemplate() const { ... };

// UIElement overrides.
Microsoft::UI::Xaml::Automation::Peers::AutomationPeer OnCreateAutomationPeer() const { ... };

オーバーライド可能な関数は、さまざまな言語プロジェクションで通常と異なる場合があります。たとえば、C# では、オーバーライド可能な関数は通常、保護された仮想関数として表示されます。 C++/WinRT では、これらは仮想でも保護対象でもありませんが、上記のように、それらをオーバーライドして独自の実装を提供できます。

テンプレートを使用せずにコントロールのソースファイルを生成する。

このセクションでは、カスタムコントロールの項目テンプレートを使用せずに、カスタムコントロールを作成するために必要なソースファイルを生成する方法について説明します。

最初に、新しい Midl ファイル (.idl) 項目をプロジェクトに追加します。 [プロジェクト] メニューで、[新しい項目の追加...] を選択し、検索ボックスに「MIDL」と入力して、.idl ファイル項目を検索します。新しいファイルに BgLabelControl.idl という名前を付けて、この記事の手順で使用される名前と同じになるようにします。 BgLabelControl.idl の既定のコンテンツを削除し、上記の手順のランタイムクラス宣言を貼り付けます。

新しい .idl ファイルを保存したら、次の手順として、Windows ランタイムメタデータファイル (.winmd) と、テンプレートコントロールを実装するために使用する実装ファイル (.cpp と .h) のスタブを生成します。これらのファイルは、ソリューションをビルドすることで生成します。これにより、MIDL コンパイラ (midl.exe) によって、作成した .idl ファイルがコンパイルされます。ソリューションは正常にビルドされず、Visual Studio によって出力ウィンドウにビルドエラーが表示されますが、必要なファイルは生成されることに注意してください。

スタブファイルの BgLabelControl.h と BgLabelControl.cpp を \BgLabelControlApp\BgLabelControlApp\Generated Files\sources\ からプロジェクトフォルダーにコピーします。 ソリューションエクスプローラーで、[すべてのファイルを表示] がオンであることを確認します。コピーしたスタブファイルを右クリックし、[プロジェクトに含める] をクリックします。

コンパイラでは、生成されるファイルがコンパイルされないように、BgLabelControl.h と BgLabelControl.cpp の先頭に static_assert 行が置かれます。コントロールを実装するときに、プロジェクトディレクトリに配置したファイルから、これらの行を削除する必要があります。このチュートリアルでは、ファイルの内容全体を、上で示したコードで上書きすることができます。

次の方法で共有

C++/WinRT を使用して XAML コントロールを作成する

前提条件

空のアプリを作成する (BgLabelControlApp)

テンプレートコントロールをアプリに追加する

BgLabelControl カスタムコントロールクラスを実装する

BgLabelControl の既定のスタイルを定義する

メイン UI ページに BgLabelControl のインスタンスを追加する

MeasureOverride や OnApplyTemplate などのオーバーライド可能な関数の実装

テンプレートを使用せずにコントロールのソースファイルを生成する。

関連項目

その他のリソース

次の方法で共有

C++/WinRT を使用して XAML コントロールを作成する

前提条件

空のアプリを作成する (BgLabelControlApp)

テンプレート コントロールをアプリに追加する

BgLabelControl カスタム コントロール クラスを実装する

BgLabelControl の既定のスタイルを定義する

メイン UI ページに BgLabelControl のインスタンスを追加する

MeasureOverride や OnApplyTemplate などのオーバーライド可能な関数の実装

テンプレートを使用せずにコントロールのソース ファイルを生成する。

関連項目

その他のリソース

テンプレートコントロールをアプリに追加する

BgLabelControl カスタムコントロールクラスを実装する

テンプレートを使用せずにコントロールのソースファイルを生成する。