通过

插件数据和 RealTimeStylus 类

  • 项目

RealTimeStylus 类的插件必须实现 IStylusSyncPlugin 或 IStylusAsyncPlugin 接口，或两者。 虽然必须实现所有插件接口方法，但插件仅接收对插件 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest 或 Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest 属性中标记的方法的调用。

接口上定义的方法使用 Microsoft.StylusInput.PluginData 命名空间中的对象将笔数据传递给插件。下表描述了作为通知方法中的参数的数据对象，并列出了与通知关联的 DataInterestMask 值。

插件数据 DataInterestMask 值 说明
CustomStylusData CustomStylusDataAdded 插件添加的自定义应用程序数据。
ErrorData 错误 RealTimeStylus 对象添加的错误信息，以响应其中一个插件中未经处理的异常。
InAirPacketsData InAirPackets 触笔位于数字化器上方的空中时，触笔运动的数据包信息。
PacketsData 数据包数 触笔触摸数字化器时触笔运动的数据包信息。
RealTimeStylusDisabledData RealTimeStylusDisabled RealTimeStylus 对象在禁用时添加的信息。
RealTimeStylusEnabledData RealTimeStylusEnabled RealTimeStylus 对象在启用时添加的信息。
StylusButtonDownData StylusButtonDown 有关正在按下的特定触笔按钮的信息。
StylusButtonUpData StylusButtonUp 有关要释放的特定触笔按钮的信息。
StylusDownData StylusDown 触笔与数字化器接触时，触笔的数据包信息。
StylusInRangeData StylusInRange 有关进入 RealTimeStylus 对象的输入区域或进入 RealTimeStylus 对象输入区域上方数字化器检测范围的特定触笔的信息。
StylusOutOfRangeData StylusOutOfRange 有关离开 RealTimeStylus 对象的输入区域或离开 RealTimeStylus 对象输入区域上方数字化器检测范围的特定触笔的信息。
StylusUpData StylusUp 从数字化器中提取触笔时触笔的数据包信息。
SystemGestureData SystemGesture RealTimeStylus 对象在检测到系统手势时添加的信息。
TabletAddedData TabletAdded 有关要添加的 Tablet 对象的信息。
TabletRemovedData TabletRemoved 有关要删除的 Tablet 对象的信息。

 

有关 RealTimeStylus 对象如何处理平板电脑笔数据流的信息，请参阅 使用 RealTimeStylus 类。

数据兴趣

将插件添加到 RealTimeStylus 对象的同步或异步插件集合时，RealTimeStylus 对象将检查插件的 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest 或 Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest 属性。 因此，应使用 DataInterest 属性订阅此插件实例使用的所有通知，但很少订阅此插件实例从未使用过的任何通知。 对于插件仅偶尔使用的通知，检查先在通知方法中显示插件的状态，如果当前状态的插件未使用该通知，则返回 。

插件仅接收对插件的 Microsoft.StylusInput.IStylusSyncPlugin.DataInterest 或 Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest 属性中标记的方法的调用。 有关插件 的 DataInterest 属性的可能值的详细信息，请参阅 DataInterestMask 枚举。

定时

在将数据传递到异步插件集合中的插件之前，数据在 RealTimeStylus 对象中排队。 以下列表描述了在设计异步插件时可能需要考虑的一些情况。

  • 禁用 RealTimeStylus 对象时，异步插件可能会在调用其 RealTimeStylusDisabled 方法之前收到其他排队通知。 在这种情况下，从插件调用 RealTimeStylus 对象的某些方法和属性会引发异常。 启用 RealTimeStylus 对象时，应缓存与插件相关的信息。
  • RealTimeStylus 对象的 ClearStylusQueues 方法可能会从输出队列中删除信息。 因此，异步插件不能依赖于接收所有相关通知。
  • 删除可用于 RealTimeStylus 对象的 Tablet 对象时，异步插件可能会在调用其 TabletRemoved 方法之前收到平板电脑的排队触笔通知。 在这种情况下，调用 RealTimeStylus 对象的 GetTabletPropertyDescriptionCollection 方法不起作用。 启用 RealTimeStylus 对象或添加新平板电脑时，应缓存与插件相关的信息。

根据应用程序，可以在禁用 RealTimeStylus 对象时提高性能。 当 RealTimeStylus 对象的 Enabled 属性设置为 FALSE 时，将处理输入和输出队列上的数据，直到队列为空。 在禁用 RealTimeStylus 对象之前，可以调用 RealTimeStylus 对象的 ClearStylusQueues 方法清除队列。

已启用和禁用的数据

启用 RealTimeStylus 对象后，每个插件都会收到对其 Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled 或 Microsoft.StylusInput.IStylusAsyncPlugin.RealTimeStylusEnabled 方法的 调用。 通知中传递的 RealTimeStylusEnabledData 对象包含启用 RealTimeStylus 对象时可用平板电脑的上下文标识符集合。

注意

由于 RealTimeStylus 对象的异步插件集合的插件数据已排队，因此异步插件可能会在接收对其 RealTimeStylusDisabled 方法的调用之前、在 RealTimeStylus 对象禁用之后接收数据。 请注意，如果禁用 RealTimeStylus 对象，则 某些 RealTimeStylus 对象的方法和属性将引发异常。

 

RealTimeStylus 对象在启用 RealTimeStylus 对象的线程上调用 Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled 和 Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusDisabled 方法，

通常，在 禁用 RealTimeStylus 对象时添加或删除插件。 有关向 RealTimeStylus 对象添加和删除插件的详细信息，请参阅 插件和 RealTimeStylus 类。

平板电脑数据

启用 RealTimeStylus 对象时，当 RealTimeStylus 对象可以使用的平板电脑添加到或从平板电脑中删除时， RealTimeStylus 对象会通知其插件 已添加或删除 Tablet 对象。 每个 RealTimeStylus 对象都为其可以与之交互的 Tablet 对象维护一个唯一标识符列表。 RealTimeStylus 对象具有两种在唯一标识符和 Tablet 对象之间进行转换的方法，即 GetTabletContextIdFromTablet 和 GetTabletFromTabletContextId 方法。

注意

从平板电脑中删除平板电脑后， RealTimeStylus 对象不再提供有关平板电脑的信息。

 

平板电脑笔数据

RealTimeStylus 对象通过多种通知方法将有关平板电脑笔的信息传递给其插件。 有关平板电脑笔的信息由 Stylus 对象表示。 此对象是收集数据时平板电脑笔状态的快照。 由于插件将平板电脑笔数据作为平板电脑笔数据流的一部分接收，因此插件应使用 Stylus 对象中的信息，而不是通过 Cursor 类检查特定平板电脑笔的当前状态。

每个 触笔 对象都包含生成数据的平板电脑的平板电脑上下文标识符。

系统手势数据

RealTimeStylus 对象接收有关由平板电脑识别的系统手势的数据。 下表描述了 SystemGestureData 对象在平板电脑笔数据流中相对于其他平板电脑笔数据的出现顺序。

SystemGesture SystemGestureData 对象前面的对象 SystemGestureData 对象之后的对象
点击 StylusDownData 对象。
 StylusUpData 对象。
DoubleTap StylusDownData 对象、点击系统手势的 SystemGestureData 对象和 StylusUpData 对象。
 第二个 StylusDownData 对象。
RightTap SystemGesure 枚举的 HoldEnter 成员的 StylusDownData 对象和 SystemGestureData 对象。
 StylusUpData 对象。
拖动 StylusDownData 对象。
 StylusUpData 对象。
RightDrag StylusDownData 对象。
 StylusUpData 对象。
HoldEnter StylusDownData 对象。
 StylusUpData 对象。
注意： 如果用户开始 拖动 或 RightDrag 系统手势，则无法识别此系统手势。
HoldLeave 未实现。
 未实现。
HoverEnter 几个平均速度较低的 InAirPacketsData 对象。
 注意： 在收到 HoverEnter 系统手势之前可能会有明显的延迟。 仅当 RealTimeStylus 对象附加到在系统手势时笔正下方的窗口或控件时， RealTimeStylus 对象才会接收此数据。
HoverLeave HoverEnter 系统手势的 SystemGestureData 对象和具有足够平均速度的多个 InAirPacketsData 对象。
 注意： 在接收 HoverLeave 系统手势之前可能会有明显的延迟。 仅当 RealTimeStylus 对象附加到在系统手势时笔正下方的窗口或控件时， RealTimeStylus 对象才会接收此数据。

 

自定义触笔数据

可以通过调用 AddCustomStylusDataToQueue 方法将自定义触笔数据添加到 RealTimeStylus 对象。 自定义触笔数据可以添加到 RealTimeStylus 对象的队列中的三个位置之一。

  • 当 queue 参数设置为 Output 时，在同步插件集合当前正在处理的数据之后，自定义数据将添加到 RealTimeStylus 对象的输出队列中。
  • 当 queue 参数设置为 OutputImmediate 时，自定义数据将添加到 RealTimeStylus 对象的输出队列中，然后同步插件集合当前正在处理的数据。
  • 当 queue 参数设置为 Input 时，自定义数据将添加到 RealTimeStylus 对象的输入队列中，并发送到同步插件集合，然后再从平板电脑笔的数据流获取新数据。

在前面的每种情况下，同步插件集合中后续插件添加的数据都是在前面插件添加的数据之后添加的。

注意

如果从同步插件调用 AddCustomStylusDataToQueue 方法，以响应对其 IStylusSyncPlugin 方法之一的调用，则自定义触笔数据以可预测的方式添加到平板电脑笔数据流;否则，它将添加到队列中，这与 RealTimeStylus 对象正在处理的当前笔数据相关，而不是与异步插件正在处理的数据相关。 如果禁用 RealTimeStylus 对象，AddCustomStylusDataToQueue 方法将引发异常。

 

自定义触笔数据作为 CustomStylusData 对象添加到队列中，插件通过其 Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded 或 Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded 方法接收此数据。

DynamicRenderer 和 GestureRecognizer 对象可能会向队列添加自定义触笔数据。 有关 DynamicRenderer 和 GestureRecognizer 对象的详细信息，请参阅 动态呈现器插件 和 识别器插件。

RealTimeStylus 对象在其接收对其 AddCustomStylusDataToQueue 方法的调用的线程上调用 Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded 方法。

下图演示了如何将自定义触笔数据添加到输出队列，并将 队列 参数设置为 Output。

显示到输出队列的自定义触笔数据流的插图

在此图中，字母为“A”和“B”的圆圈表示已添加到 RealTimeStylus 对象的输出队列且尚未发送到异步插件集合的平板电脑笔数据。 字母为“C”的圆圈表示 RealTimeStylus 对象当前正在处理的平板电脑笔数据。 它被发送到同步插件集合并放置在输出队列中。 编号为“1”、“2”和“3”的圆圈表示第一个、第二个和第三个同步插件分别添加到输出队列的自定义触笔数据，以响应由“C”表示的平板电脑笔数据。 这些插件添加了自定义触笔数据， 并将队列 参数设置为 StylusQueues。 空圆表示在输出队列中添加未来平板电脑笔数据的位置。

下图演示了将自定义触笔数据添加到输出队列，并将 队列 参数设置为 OutputImmediate。

显示输出队列的自定义触笔数据流的关系图。

在此图中，字母为“A”和“B”的圆圈表示已添加到 RealTimeStylus 对象的输出队列且尚未发送到异步插件集合的平板电脑笔数据。 字母为“C”的圆圈表示 RealTimeStylus 对象当前正在处理的平板电脑笔数据。 它被发送到同步插件集合并放置在输出队列中。 编号为“1”、“2”和“3”的圆圈表示第一个、第二个和第三个同步插件分别添加到输出队列的自定义触笔数据，以响应由“C”表示的平板电脑笔数据。 这些插件添加了自定义触笔数据， 并将队列 参数设置为 OutputImmediate。 空圆表示在输出队列中添加未来平板电脑笔数据的位置。

下图说明了如何将自定义触笔数据添加到输入队列。

显示到输出队列的自定义触笔数据流的插图

在此图中，字母为“A”和“B”的圆圈表示已添加到 RealTimeStylus 对象的输出队列且尚未发送到异步插件集合的平板电脑笔数据。 字母为“C”的圆圈表示 RealTimeStylus 对象当前正在处理的平板电脑笔数据。 它被发送到同步插件集合并放置在输出队列中。 编号为“1”、“2”和“3”的圆圈表示第一、第二和第三个同步插件分别添加到输入队列的自定义触笔数据，以响应“C”表示的平板电脑笔数据。 插件添加了自定义触笔数据，并将 队列 参数设置为 Input。 编号为“1”的自定义触笔数据随后传递到同步插件，然后在编号为“2”和“3”的自定义触笔数据之前传递到输出队列，这两者在处理下一个平板电脑笔数据之前进行处理。 空圆表示在输出队列中添加未来平板电脑笔数据的位置。

错误数据

当插件引发异常时，正常的数据流将中断。 RealTimeStylus 对象生成 ErrorData 对象并调用：

如果引发异常的插件是同步插件，则 ErrorData 对象将添加到输出队列。 然后 ，RealTimeStylus 对象恢复对原始数据的正常处理。

下图演示了向平板电脑笔数据添加错误数据。

自定义触笔数据流到输出队列，并添加错误数据

在此图中，字母为“A”和“B”的圆圈表示已添加到 RealTimeStylus 对象的输出队列且尚未发送到异步插件集合的平板电脑笔数据。 字母为“C”的圆圈表示 RealTimeStylus 对象当前正在处理的平板电脑笔数据。 字母为“e”的圆圈表示当第二个同步插件同步插件 2 在处理“C”时引发异常时，RealTimeStylus 对象生成的 ErrorData 对象。 然后 ，RealTimeStylus 对象暂停对“C”的处理，并将“e”传递给生成异常的插件和所有后续插件。然后 ，RealTimeStylus 对象将“e”放在输出队列中，并恢复对“C”的处理，该处理将传递给同步插件集合中的其余插件，并放置在“e”之后的输出队列中。 空圆表示在输出队列中添加未来平板电脑笔数据的位置。

如果插件从其 Error 方法引发异常， 则 RealTimeStylus 对象将捕获该异常，但不会生成新的 ErrorData 对象。 这是为了防止递归。

错误数据将添加到输出队列中的任何自定义触笔数据之后，这些数据是在创建错误数据的异常之前在 OutputImmediate 位置添加的，在同步插件集合中的后续插件添加到 OutputImmediate 位置的任何自定义触笔数据之前。

下图说明了如何相对于添加到 OutputImmediate 队列的自定义数据将错误数据添加到输出队列。

添加到输出队列中的错误数据与添加到输出队列的自定义数据相关。

在此图中，字母为“A”和“B”的圆圈表示已添加到 RealTimeStylus 对象的输出队列且尚未发送到异步插件集合的平板电脑笔数据。 字母为“C”的圆圈表示 RealTimeStylus 对象当前正在处理的平板电脑笔数据。 编号为“1”、“2”和“3”的圆圈分别由第一个、第二个和第三个同步插件添加到 OutputImmediate 队列中，以响应用圆圈字母“C”表示的数据。 带圆圈字母“e”表示在将自定义数据添加到 OutputImmediate 位置的输出队列后，第二个插件引发的异常而生成的错误数据。

如果任何同步插件将自定义触笔数据添加到输入队列以响应错误数据，则会在错误数据之前立即添加数据。 如果任何同步插件将自定义触笔数据添加到输出队列的 输出 位置以响应错误数据，则数据将立即添加到错误数据之后。

RealTimeStylus 对象在引发异常的线程上调用 Microsoft.StylusInput.IStylusSyncPlugin.Error 方法。

Microsoft.Ink.Tablet

Microsoft.StylusInput.PluginData

Microsoft.StylusInput.DataInterestMask

Microsoft.StylusInput.RealTimeStylus

使用 RealTimeStylus 类