このトピックは、Windows ランタイム コンポーネントと、C++/WinRT で Windows ランタイム コンポーネントを
このトピックで追加される新機能を次に示します。
- 温度計ランタイム クラスを更新して、温度が氷点下になったときにイベントを発生させます。
- 温度計ランタイム クラスを使用するコア アプリを更新して、そのイベントを処理するようにします。
注
Von Bedeutung
C++/WinRT を使用してランタイム クラスを使用および作成する方法の理解をサポートする基本的な概念と用語については、「C++/WinRT で API を使用する
ThermometerWRC と ThermometerCoreApp を作成する
コードをビルドして実行できるように、このトピックに示されている更新プログラムに従う場合は、最初の手順として、C++/WinRT を使用した Windows ランタイム コンポーネントの
イベントを発生させるために、ThermometerWRC を に更新します。
Thermometer.idl を次の一覧のように更新します。 これは、デリゲート型が単精度浮動小数点数の引数を使用して EventHandler
// Thermometer.idl
namespace ThermometerWRC
{
runtimeclass Thermometer
{
Thermometer();
void AdjustTemperature(Single deltaFahrenheit);
event Windows.Foundation.EventHandler<Single> TemperatureIsBelowFreezing;
};
}
ファイルを保存します。 プロジェクトは現在の状態ではビルドから完了しませんが、どのような場合でもビルドを実行して、\ThermometerWRC\ThermometerWRC\Generated Files\sources\Thermometer.h と Thermometer.cpp スタブ ファイルの更新バージョンを生成します。 これらのファイル内で、TemperatureIsBelowFreezing イベントのスタブ実装を確認できるようになりました。 C++/WinRT では、IDL で宣言されたイベントは、オーバーロードされた関数のセットとして実装されます (オーバーロードされた get 関数と set 関数のペアとしてプロパティを実装する方法と同様)。 1 つのオーバーロードは、登録するデリゲートを受け取り、トークン (winrt::event_token) を返します。 もう一方はトークンを受け取り、関連付けられているデリゲートの登録を取り消します。
ここで、Thermometer.h と Thermometer.cppを開き、の温度計 ランタイム クラスの実装を更新します。
Thermometer.hで、2 つのオーバーロードされた TemperatureIsBelowFreezing 関数と、それらの関数の実装で使用するプライベート イベント データ メンバーを追加します。
// Thermometer.h
...
namespace winrt::ThermometerWRC::implementation
{
struct Thermometer : ThermometerT<Thermometer>
{
...
winrt::event_token TemperatureIsBelowFreezing(Windows::Foundation::EventHandler<float> const& handler);
void TemperatureIsBelowFreezing(winrt::event_token const& token) noexcept;
private:
winrt::event<Windows::Foundation::EventHandler<float>> m_temperatureIsBelowFreezingEvent;
...
};
}
...
前述のように、イベントは winrt::event 構造体テンプレートによって表され、特定のデリゲート型によってパラメーター化されます (それ自体は args 型でパラメーター化できます)。
Thermometer.cppでは、2 つのオーバーロードされた TemperatureIsBelowFreezing 関数を実装します。
// Thermometer.cpp
...
namespace winrt::ThermometerWRC::implementation
{
winrt::event_token Thermometer::TemperatureIsBelowFreezing(Windows::Foundation::EventHandler<float> const& handler)
{
return m_temperatureIsBelowFreezingEvent.add(handler);
}
void Thermometer::TemperatureIsBelowFreezing(winrt::event_token const& token) noexcept
{
m_temperatureIsBelowFreezingEvent.remove(token);
}
void Thermometer::AdjustTemperature(float deltaFahrenheit)
{
m_temperatureFahrenheit += deltaFahrenheit;
if (m_temperatureFahrenheit < 32.f) m_temperatureIsBelowFreezingEvent(*this, m_temperatureFahrenheit);
}
}
注
自動イベント取り消し子の詳細については、「登録されたデリゲートを取り消す」を参照してください。 イベントの自動イベント 取り消し機能の実装は無料で取得できます。 つまり、C++/WinRT プロジェクションによって提供されるイベント 取り消し子のオーバーロードを実装する必要はありません。
他のオーバーロード (登録と手動の失効オーバーロード) は、プロジェクションに組み込
この上記に示されているように、AdjustTemperature 関数の実装が更新され、温度が氷点下になった場合に TemperatureIsBelowFreezing イベントが発生するようになりました。
ThermometerCoreApp を更新して、イベント を処理できるようにします。
の ThermometerCoreApp プロジェクトで、App.cppで、イベントハンドラーを登録するコードに以下の変更を加え、温度を氷点下にする。
WINRT_ASSERT はマクロ定義であり、_ASSERTEに展開されます。
struct App : implements<App, IFrameworkViewSource, IFrameworkView>
{
winrt::event_token m_eventToken;
...
void Initialize(CoreApplicationView const &)
{
m_eventToken = m_thermometer.TemperatureIsBelowFreezing([](const auto &, float temperatureFahrenheit)
{
WINRT_ASSERT(temperatureFahrenheit < 32.f); // Put a breakpoint here.
});
}
...
void Uninitialize()
{
m_thermometer.TemperatureIsBelowFreezing(m_eventToken);
}
...
void OnPointerPressed(IInspectable const &, PointerEventArgs const & args)
{
m_thermometer.AdjustTemperature(-1.f);
...
}
...
};
OnPointerPressed メソッドの変更に注意してください。 ウィンドウをクリックするたびに、温度計の温度から華氏 1 度 減算
ABI におけるパラメーター化されたデリゲート
コンポーネントとその使用中のアプリケーションの間など、アプリケーション バイナリ インターフェイス (ABI) 経由でイベントにアクセスできる必要がある場合は、イベントで Windows ランタイム デリゲート型を使用する必要があります。 上の例では、Windows::Foundation::EventHandler
これら 2 つのデリゲート型の型パラメーターは ABI と交差する必要があるため、型パラメーターも Windows ランタイム型である必要があります。 これには、Windows ランタイム クラス、サードパーティのランタイム クラス、および数値や文字列などのプリミティブ型が含まれます。 その制約を忘れると、コンパイラは "T は WinRT 型" というエラーを表示します。
コード リストの形式の例を次に示します。 このトピックで前に作成した ThermometerWRC と ThermometerCoreApp プロジェクトから始め、これらのプロジェクトのコードを編集して、これらの一覧のコードのようになります。
この最初の一覧は、の温度計WRC プロジェクト用です。 次に示すように ThermometerWRC.idl 編集した後、プロジェクトをビルドし、MyEventArgs.h と .cppで前に行ったのと同じように、Generated Files と Thermometer.h を (.cpp フォルダーから) プロジェクトにコピーします。 両方のファイルから static_assert を削除することを忘れないでください。
// ThermometerWRC.idl
namespace ThermometerWRC
{
[default_interface]
runtimeclass MyEventArgs
{
Single TemperatureFahrenheit{ get; };
}
[default_interface]
runtimeclass Thermometer
{
...
event Windows.Foundation.EventHandler<ThermometerWRC.MyEventArgs> TemperatureIsBelowFreezing;
...
};
}
// MyEventArgs.h
#pragma once
#include "MyEventArgs.g.h"
namespace winrt::ThermometerWRC::implementation
{
struct MyEventArgs : MyEventArgsT<MyEventArgs>
{
MyEventArgs() = default;
MyEventArgs(float temperatureFahrenheit);
float TemperatureFahrenheit();
private:
float m_temperatureFahrenheit{ 0.f };
};
}
// MyEventArgs.cpp
#include "pch.h"
#include "MyEventArgs.h"
#include "MyEventArgs.g.cpp"
namespace winrt::ThermometerWRC::implementation
{
MyEventArgs::MyEventArgs(float temperatureFahrenheit) : m_temperatureFahrenheit(temperatureFahrenheit)
{
}
float MyEventArgs::TemperatureFahrenheit()
{
return m_temperatureFahrenheit;
}
}
// Thermometer.h
...
struct Thermometer : ThermometerT<Thermometer>
{
...
winrt::event_token TemperatureIsBelowFreezing(Windows::Foundation::EventHandler<ThermometerWRC::MyEventArgs> const& handler);
...
private:
winrt::event<Windows::Foundation::EventHandler<ThermometerWRC::MyEventArgs>> m_temperatureIsBelowFreezingEvent;
...
}
...
// Thermometer.cpp
#include "MyEventArgs.h"
...
winrt::event_token Thermometer::TemperatureIsBelowFreezing(Windows::Foundation::EventHandler<ThermometerWRC::MyEventArgs> const& handler) { ... }
...
void Thermometer::AdjustTemperature(float deltaFahrenheit)
{
m_temperatureFahrenheit += deltaFahrenheit;
if (m_temperatureFahrenheit < 32.f)
{
auto args = winrt::make_self<winrt::ThermometerWRC::implementation::MyEventArgs>(m_temperatureFahrenheit);
m_temperatureIsBelowFreezingEvent(*this, *args);
}
}
...
この一覧は、ThermometerCoreApp プロジェクト用です。
// App.cpp
...
void Initialize(CoreApplicationView const&)
{
m_eventToken = m_thermometer.TemperatureIsBelowFreezing([](const auto&, ThermometerWRC::MyEventArgs args)
{
float degrees = args.TemperatureFahrenheit();
WINRT_ASSERT(degrees < 32.f); // Put a breakpoint here.
});
}
...
ABI にわたる単純なシグナル
イベントでパラメーターまたは引数を渡す必要がない場合は、独自の単純な Windows ランタイム デリゲート型を定義できます。 次の例は、ランタイム クラス
// ThermometerWRC.idl
namespace ThermometerWRC
{
delegate void SignalDelegate();
runtimeclass Thermometer
{
Thermometer();
event ThermometerWRC.SignalDelegate SignalTemperatureIsBelowFreezing;
void AdjustTemperature(Single value);
};
}
// Thermometer.h
...
namespace winrt::ThermometerWRC::implementation
{
struct Thermometer : ThermometerT<Thermometer>
{
...
winrt::event_token SignalTemperatureIsBelowFreezing(ThermometerWRC::SignalDelegate const& handler);
void SignalTemperatureIsBelowFreezing(winrt::event_token const& token);
void AdjustTemperature(float deltaFahrenheit);
private:
winrt::event<ThermometerWRC::SignalDelegate> m_signal;
float m_temperatureFahrenheit{ 0.f };
};
}
// Thermometer.cpp
...
namespace winrt::ThermometerWRC::implementation
{
winrt::event_token Thermometer::SignalTemperatureIsBelowFreezing(ThermometerWRC::SignalDelegate const& handler)
{
return m_signal.add(handler);
}
void Thermometer::SignalTemperatureIsBelowFreezing(winrt::event_token const& token)
{
m_signal.remove(token);
}
void Thermometer::AdjustTemperature(float deltaFahrenheit)
{
m_temperatureFahrenheit += deltaFahrenheit;
if (m_temperatureFahrenheit < 32.f)
{
m_signal();
}
}
}
// App.cpp
struct App : implements<App, IFrameworkViewSource, IFrameworkView>
{
ThermometerWRC::Thermometer m_thermometer;
winrt::event_token m_eventToken;
...
void Initialize(CoreApplicationView const &)
{
m_eventToken = m_thermometer.SignalTemperatureIsBelowFreezing([] { /* ... */ });
}
...
void Uninitialize()
{
m_thermometer.SignalTemperatureIsBelowFreezing(m_eventToken);
}
...
void OnPointerPressed(IInspectable const &, PointerEventArgs const & args)
{
m_thermometer.AdjustTemperature(-1.f);
...
}
...
};
プロジェクト内のパラメーター化されたデリゲート、単純なシグナル、およびコールバック
(バイナリ間ではなく) Visual Studio プロジェクトの内部にあるイベントが必要な場合は、それらのイベントが Windows ランタイム型に限定されない場合でも、winrt::event<Delegate> クラス テンプレートを使用できます。 winrt::d elegate
次の例では、最初にパラメーター (基本的に単純なシグナル) を受け取らないデリゲートシグネチャと、文字列を受け取るデリゲートシグネチャを示しています。
winrt::event<winrt::delegate<>> signal;
signal.add([] { std::wcout << L"Hello, "; });
signal.add([] { std::wcout << L"World!" << std::endl; });
signal();
winrt::event<winrt::delegate<std::wstring>> log;
log.add([](std::wstring const& message) { std::wcout << message.c_str() << std::endl; });
log.add([](std::wstring const& message) { Persist(message); });
log(L"Hello, World!");
イベントに、望むだけの数のデリゲートを追加できることに注目してください。 ただし、イベントに関連するいくつかのオーバーヘッドがあります。 必要なのが、1つのサブスクライブするデリゲートのみをもつ単純なコールバックであれば、winrt::delegate <... T> を単独で使用できます。
winrt::delegate<> signalCallback;
signalCallback = [] { std::wcout << L"Hello, World!" << std::endl; };
signalCallback();
winrt::delegate<std::wstring> logCallback;
logCallback = [](std::wstring const& message) { std::wcout << message.c_str() << std::endl; }f;
logCallback(L"Hello, World!");
イベントとデリゲートがプロジェクト内で内部的に使用される C++/CX コードベースから移植する場合は、winrt::d elegate を
遅延可能なイベント
Windows ランタイムの一般的なパターンは、遅延可能なイベントです。 イベント ハンドラー は、イベント引数の GetDeferral メソッドを呼び出すことによって遅延 を受け取ります。 これは、イベント ソースに対して、イベント後のアクティビティを遅延が完了するまで延期する必要があることを示します。 これにより、イベント ハンドラーは、イベントに応答して非同期アクションを実行できます。
winrt::deferrable_event_args 構造体テンプレートは、Windows ランタイムの遅延パターンを実装 (生成) するためのヘルパークラスです。 例を次に示します。
// Widget.idl
namespace Sample
{
runtimeclass WidgetStartingEventArgs
{
Windows.Foundation.Deferral GetDeferral();
Boolean Cancel;
};
runtimeclass Widget
{
event Windows.Foundation.TypedEventHandler<
Widget, WidgetStartingEventArgs> Starting;
};
}
// Widget.h
namespace winrt::Sample::implementation
{
struct Widget : WidgetT<Widget>
{
Widget() = default;
event_token Starting(Windows::Foundation::TypedEventHandler<
Sample::Widget, Sample::WidgetStartingEventArgs> const& handler)
{
return m_starting.add(handler);
}
void Starting(event_token const& token) noexcept
{
m_starting.remove(token);
}
private:
event<Windows::Foundation::TypedEventHandler<
Sample::Widget, Sample::WidgetStartingEventArgs>> m_starting;
};
struct WidgetStartingEventArgs : WidgetStartingEventArgsT<WidgetStartingEventArgs>,
deferrable_event_args<WidgetStartingEventArgs>
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{
bool Cancel() const noexcept { return m_cancel; }
void Cancel(bool value) noexcept { m_cancel = value; }
bool m_cancel = false;
};
}
イベント受信者が遅延可能なイベント パターンを使用する方法を次に示します。
// EventRecipient.h
widget.Starting([](auto sender, auto args) -> fire_and_forget
{
auto deferral = args.GetDeferral();
if (!co_await CanWidgetStartAsync(sender))
{
// Do not allow the widget to start.
args.Cancel(true);
}
deferral.Complete();
});
イベントソースの実装者（プロデューサー）として、イベント引数クラスをwinrt::deferrable_event_argsから派生させます。 deferrable_event_args<T> は、T::GetDeferral をあなたのために実装します。 また、未処理のすべての遅延が完了したときに完了する新しいヘルパー メソッド deferrable_event_args::wait_for_deferralsも公開されます (遅延が行われなかった場合は、すぐに完了します)。
// Widget.h
IAsyncOperation<bool> TryStartWidget(Widget const& widget)
{
auto args = make_self<WidgetStartingEventArgs>();
// Raise the event to let people know that the widget is starting
// and give them a chance to prevent it.
m_starting(widget, *args);
// Wait for deferrals to complete.
co_await args->wait_for_deferrals();
// Use the results.
bool started = false;
if (!args->Cancel())
{
widget.InsertBattery();
widget.FlipPowerSwitch();
started = true;
}
co_return started;
}
設計ガイドライン
デリゲートではなくイベントを関数パラメーターとして渡すことをお勧めします。
イベント ハンドラー デリゲートのシグネチャは、sender (IInspectable) と args (RoutedEventArgsなど) の 2 つのパラメーターで構成されている必要があります。
これらのガイドラインは、内部 API を設計する場合には必ずしも適用されません。 ただし、内部 API は時間の経過と同時にパブリックになることがよくあります。
関連トピック
- C++/WinRT を使用して API を作成する
- C++/WinRT で API を消費する
- C++/WinRT でデリゲートを使用してイベントを処理する
- C++/WinRT を使用して Windows ランタイム コンポーネントを作成する