本主题基于 Windows 运行时 components with C++/WinRT 主题中演示如何构建的 Windows 运行时 组件及其使用该组件的应用程序。
下面是本主题添加的新功能。
- 更新温度计运行时类，使其在温度降至冰点以下时触发事件。
- 更新使用温度计运行时类的核心应用，以便处理该事件。
注释
有关安装和使用 C++/WinRT Visual Studio 扩展（VSIX）和 NuGet 包（一起提供项目模板和生成支持）的信息，请参阅Visual Studio对 C++/WinRT 的支持。
Important
有关有助于你了解如何使用 C++/WinRT 使用和编写运行时类的基本概念和术语，请参阅 使用 C++/WinRT 使用 API 和 使用 C++/WinRT 编写 API。
创建 ThermometerWRC 和 ThermometerCoreApp
如果要遵循本主题中所示的更新，以便可以生成和运行代码，则第一步是按照 C++/WinRT 主题的 Windows 运行时 组件中的演练进行操作。 这样一来，你将拥有 ThermometerWRC Windows 运行时 组件，以及使用该组件的 ThermometerCoreApp 核心应用。
更新 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 函数实现的方式）。 其中一个重载接受一个要注册的委托，并返回一个令牌（winrt::event_token）。 另一个则接收一个令牌，并撤销相关联委托的注册。
现在打开 Thermometer.h 并 Thermometer.cpp更新 温度计 运行时类的实现。 在 Thermometer.h 中，添加两个重载的 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 中，实现两个重载的 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 投影会为你提供它。
其他重载（注册重载和手动撤销重载）并未内置到投影中。 这样，就可以灵活地为方案以最佳方式实现它们。 调用 event：：add 和 event：：remove ，如这些实现中所示，这是一个高效且并发/线程安全的默认值。 但是，如果你有非常大量的事件，那么你可能不想为每个事件都设置一个事件字段，而是改为采用某种稀疏实现方式。
你还可以从上面看到，AdjustTemperature 函数的实现已更新，以便在温度降到冰点以下时引发 TemperatureIsBelowFreezing 事件。
更新 温度计CoreApp 以处理事件
在 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 度华氏度。 现在，应用正在处理温度低于冰点时引发的事件。 为了演示该事件是否按预期被引发，请在处理 TemperatureIsBelowFreezing 事件的 lambda 表达式内部设置断点，运行应用程序，然后在窗口内单击。
跨 ABI 的参数化委托
如果事件必须跨应用程序二进制接口（例如组件及其使用的应用程序之间）进行访问，则事件必须使用Windows 运行时委托类型。 上面的示例使用 Windows：：Foundation：：EventHandler<T> Windows 运行时 委托类型。 TypedEventHandler<TSender，TResult> 是Windows 运行时委托类型的另一个示例。
这两个委托类型的类型参数必须跨越 ABI 边界，因此这些类型参数也必须是 Windows 运行时类型。 这包括Windows运行时类、第三方运行时类以及数字和字符串等基元类型。 如果忘记了该约束，编译器将帮助你处理“T 必须是 WinRT 类型”错误。
下面是代码列表形式的示例。 从本主题前面创建的 热计WRC 和 温度计CoreApp 项目开始，并编辑这些项目中的代码，看起来像这些列表中的代码。
第一个列表适用于 温度计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);
}
}
...
此列表适用于 温度计CoreApp 项目。
// 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 运行时 委托类型。 下面的示例显示了温度 计 运行时类的更简单版本。 它声明名为 SignalDelegate 的委托类型，然后使用该类型引发信号类型事件，而不是使用参数引发事件。
// 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 而不是实际的Windows 运行时委托类型，因为 winrt：:d elegate 也支持非Windows 运行时参数。
下面的示例首先显示了不采用任何参数（实质上是简单信号）的委托签名，然后显示一个采用字符串的委托签名。
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!");
请注意如何根据需要向事件添加任意数量的订阅委托。 不过，事件会带来一些额外开销。 如果你需要的只是一个仅带单个订阅委托的简单回调，那么可以单独使用 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::delegate 将帮助你在 C++/WinRT 中复现这种模式。
可延迟事件
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_argsT> 为你实现 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;
}
设计指南
我们建议你将事件而非委托作为函数参数传递。 winrt：：event 的 add 函数是一个例外，因为在这种情况下必须传递委托。 制定此准则的原因是，委托在不同的 Windows 运行时 语言中可能具有不同的形式（具体取决于它们支持单个客户端注册还是多个客户端注册）。 事件及其多个订阅者模型构成了更可预测和一致的选项。
事件处理程序委托的签名应包含两个参数： sender （IInspectable）和 args （某些事件参数类型，例如 RoutedEventArgs）。
请注意，在设计内部 API 时，这些准则不一定适用。 不过，内部 API 在一段时间内通常成为公共 API。
