Данные подключаемого модуля и класс RealTimeStylus
Подключаемые модули для класса RealTimeStylus должны реализовывать интерфейс IStylusSyncPlugin или IStylusAsyncPlugin или оба интерфейса. Хотя необходимо реализовать все методы интерфейса подключаемого модуля, подключаемый модуль принимает вызовы только для методов, помеченных в свойстве подключаемых модулей Microsoft.StylusInput.IStylusSyncPlugin.DataInterest или Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest .
Методы, определенные в интерфейсах, используют объекты в пространстве имен Microsoft.StylusInput.PluginData для передачи данных пера в подключаемые модули. В следующей таблице описаны объекты данных, которые являются параметрами в методах уведомлений, и приведено значение DataInterestMask , связанное с уведомлением.
| Данные подключаемого модуля | Значение DataInterestMask | Описание |
|---|---|---|
| CustomStylusData | CustomStylusDataAdded | Пользовательские данные приложения, добавляемые подключаемым модулем. |
| ErrorData | Ошибка | Сведения об ошибке, которые объект RealTimeStylus добавляет в ответ на необработанное исключение в одном из своих подключаемых модулей. |
| InAirPacketsData | InAirPackets | Сведения о пакете для перемещения пера, когда перо находится в воздухе над дигитайзером. |
| ПакетыData | Пакеты | Сведения о пакете для перемещения пера, когда перо касается дигитайзера. |
| 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 | ПланшетДобавлен | Сведения о добавляемом объекте Tablet . |
| TabletRemovedData | Планшет удален | Сведения об удаляемом объекте Tablet . |
Сведения о том, как объект RealTimeStylus обрабатывает поток данных пера планшета, см. в статье Работа с классом RealTimeStylus.
Интерес к данным
Объект RealTimeStylus проверяет свойство Microsoft.StylusInput.IStylusSyncPlugin.DataInterest или Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest подключаемого модуля, когда подключаемый модуль добавляется в синхронную или асинхронную коллекцию подключаемых модулей объекта RealTimeStylus . Поэтому следует использовать свойство DataInterest, чтобы подписаться на все уведомления, используемые этим экземпляром подключаемого модуля, хотя и редко, но не на уведомления, которые этот экземпляр подключаемого модуля никогда не использует. Для уведомлений, которые ваш подключаемый модуль использует только время от времени, проверка состояние подключаемого модуля в методе уведомления и возвращается, если уведомление не используется вашим подключаемым модулем в его текущем состоянии.
Подключаемый модуль принимает вызовы только для методов, помеченных в свойстве Microsoft.StylusInput.IStylusSyncPlugin.DataInterest или Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest . Дополнительные сведения о возможных значениях свойства DataInterest подключаемого модуля см. в перечислении DataInterestMask .
Временные свойства
Данные помещются в очередь в объекте RealTimeStylus перед их передачей подключаемым модулям в асинхронной коллекции подключаемых модулей. В следующем списке описаны некоторые ситуации, которые могут потребоваться учитывать при разработке асинхронного подключаемого модуля.
- Если объект RealTimeStylus отключен, асинхронный подключаемый модуль может получать другие уведомления в очереди перед вызовом метода RealTimeStylusDisabled . В этом случае вызовы из подключаемого модуля к некоторым методам и свойствам объекта RealTimeStylus вызывают исключение. Сведения, относящиеся к подключаемой системе, должны кэшироваться при включении объекта RealTimeStylus .
- Метод ClearStylusQueues объекта RealTimeStylus может удалять сведения из очереди вывода. Поэтому асинхронные подключаемые модули не могут полагаться на получение всех соответствующих уведомлений.
- При удалении объекта Tablet , доступного для объекта RealTimeStylus , асинхронный подключаемый модуль может получить уведомление пера в очереди для планшета до вызова метода TabletRemoved . В этом случае вызов метода GetTabletPropertyDescriptionCollectionCollection объекта RealTimeStylus не работает. Сведения, относящиеся к подключаемом модулю, должны кэшироваться при включении объекта RealTimeStylus или при добавлении нового планшета.
В зависимости от приложения можно повысить производительность при отключении объекта RealTimeStylus . Если свойство Enabled объекта RealTimeStylus имеет значение FALSE, данные входных и выходных очередей обрабатываются до тех пор, пока очереди не будут пустыми. Вы можете вызвать метод ClearStylusQueues объекта RealTimeStylus, чтобы очистить очереди перед отключением объекта RealTimeStylus.
Включенные и отключенные данные
Если объект RealTimeStylus включен, каждый подключаемый модуль получает вызов метода Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled или Microsoft.StylusInput.IStylusAsyncPlugin.RealTimeStylusEnabled . Объект RealTimeStylusEnabledData , переданный в уведомление, содержит коллекцию идентификаторов контекста для доступных планшетов на момент включения объекта RealTimeStylus .
Примечание
Так как данные подключаемого модуля для асинхронной коллекции подключаемых модулей объекта RealTimeStylus помещается в очередь, асинхронные подключаемые модули могут получать данные до получения вызова метода RealTimeStylusDisabled , но после отключения объекта RealTimeStylus . Обратите внимание, что некоторые методы и свойства объекта RealTimeStylus создают исключение, если объект RealTimeStylus отключен.
Объект RealTimeStylus вызывает методы Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled и Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusDisabled в потоке, из которого включен объект RealTimeStylus или из которого добавляется синхронный подключаемый модуль.
Как правило, добавьте или удалите подключаемые модули, пока объект RealTimeStylus отключен. Дополнительные сведения о добавлении и удалении подключаемых модулей в объекте RealTimeStylus см. в разделе Подключаемые модули и класс RealTimeStylus.
Данные планшета
Когда планшет, который может использовать объект RealTimeStylus , добавляется к планшету или удаляется с планшетного компьютера при включенном объекте RealTimeStylus , объект RealTimeStylus уведомляет подключаемые модули о добавлении или удалении объекта Tablet . Каждый объект RealTimeStylus поддерживает список уникальных идентификаторов для объектов Tablet, с которыми он может взаимодействовать. Объект RealTimeStylus имеет два метода для преобразования между уникальным идентификатором и объектом Tablet, методы GetTabletContextIdFromTablet и GetTabletFromTabletContextId .
Примечание
Сведения о планшете больше не доступны из объекта RealTimeStylus после удаления планшета с планшетного компьютера.
Данные пера планшета
Объект RealTimeStylus передает сведения о пере планшета своим подключаемым модулям в нескольких методах уведомления. Сведения о перо планшета представлены объектом Stylus . Этот объект является snapshot состояния пера планшета на момент сбора данных. Так как подключаемые модули получают данные пера планшета как часть потока данных пера планшета, подключаемые модули должны использовать сведения в объекте Stylus, а не проверять текущее состояние конкретного пера планшета с помощью класса Cursor .
Каждый объект Stylus содержит идентификатор контекста планшета для планшета, создающего данные.
Системные данные жестов
Объект RealTimeStylus получает данные о системных жестах по мере их распознавания планшетным компьютером. В следующей таблице описан порядок, в котором объекты SystemGestureData встречаются в потоке данных пера планшета относительно других данных пера планшета.
| SystemGesture | Объекты, предшествующие объекту SystemGestureData | Объекты, которые приходят после объекта SystemGestureData |
|---|---|---|
| Касание | Объект StylusDownData . |
Объект StylusUpData . |
| DoubleTap | Объект StylusDownData , объект SystemGestureData для системного жеста Tap и объекты StylusUpData . |
Второй объект StylusDownData . |
| RightTap | Объекты StylusDownData и SystemGestureData для элемента HoldEnter перечисления SystemGesure . |
Объект StylusUpData . |
| Перетащите | Объект StylusDownData . |
Объект StylusUpData . |
| RightDrag | Объект StylusDownData . |
Объект StylusUpData . |
| HoldEnter | Объект StylusDownData . |
Объект StylusUpData . Примечание: Этот системный жест не распознается, если пользователь начинает использовать системный жест перетаскивания или правой части . |
| HoldLeave | Не реализован. |
Не реализован. |
| HoverEnter | Несколько объектов InAirPacketsData с низкой средней скоростью. |
Примечание: Перед получением системного жеста HoverEnter может возникнуть заметная задержка. Объект RealTimeStylus получает эти данные только в том случае, если объект RealTimeStylus присоединен к окну или элементу управления, который находится непосредственно под пером во время выполнения системного жеста. |
| HoverLeave | Объект SystemGestureData для системного жеста HoverEnter и несколько объектов InAirPacketsData с достаточной средней скоростью. |
Примечание: Перед получением системного жеста HoverLeave может возникнуть заметная задержка. Объект RealTimeStylus получает эти данные только в том случае, если объект RealTimeStylus присоединен к окну или элементу управления, который находится непосредственно под пером во время выполнения системного жеста. |
Пользовательские данные пера
Пользовательские данные пера можно добавить в объект RealTimeStylus путем вызова метода AddCustomStylusDataToQueue . Данные пользовательского пера можно добавить в очереди объекта RealTimeStylus в одном из трех мест.
- Если параметру очереди присвоено значение Output, пользовательские данные добавляются в очередь вывода объекта RealTimeStylus после данных, обрабатываемых синхронной подключаемой коллекцией.
- Если параметру очереди присвоено значение OutputImmediate, пользовательские данные добавляются в очередь вывода объекта RealTimeStylus перед данными, обрабатываемыми синхронной коллекцией подключаемых модулей.
- Если параметру очереди задано значение Input, пользовательские данные добавляются во входную очередь объекта RealTimeStylus и отправляются в синхронную коллекцию подключаемых модулей перед новыми данными из потока данных пера планшета.
В каждом из предыдущих случаев данные, добавленные последующими подключаемыми модулями в синхронной коллекции подключаемых модулей, добавляются после добавления данных предыдущими подключаемыми модулями.
Примечание
Если вызов метода AddCustomStylusDataToQueue выполняется из синхронного подключаемого модуля в ответ на вызов одного из его методов IStylusSyncPlugin , то данные пользовательского пера добавляются в поток данных пера планшета предсказуемым образом; В противном случае он добавляется в очередь относительно текущих данных пера, обрабатываемых объектом RealTimeStylus , а не относительно данных, обрабатываемых асинхронным подключаемым модулем. Метод AddCustomStylusDataToQueue создает исключение, если объект RealTimeStylus отключен.
Пользовательские данные пера добавляются в очередь как объект CustomStylusData , и подключаемые модули получают эти данные через метод Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded или Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded .
Объекты DynamicRenderer и GestureRecognizer могут добавлять пользовательские данные пера в очередь. Дополнительные сведения об объектах DynamicRenderer и GestureRecognizer см. в разделе Подключаемые модули Dynamic-Renderer и Подключаемые модули распознавателя.
Объект RealTimeStylus вызывает метод Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded в потоке, из которого он получает вызов метода AddCustomStylusDataToQueue .
На следующей схеме показано добавление пользовательских данных пера в выходную очередь с параметром очереди , равным 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 и вызывает:
- Метод Microsoft.StylusInput.IStylusSyncPlugin.Error или Microsoft.StylusInput.IStylusAsyncPlugin.Error подключаемого модуля, вызвавшего исключение.
- Метод Microsoft.StylusInput.IStylusSyncPlugin.Error или Microsoft.StylusInput.IStylusAsyncPlugin.Error остальных подключаемых модулей в этой коллекции.
Если подключаемый модуль, вызвавший исключение, является синхронным подключаемым модулем, объект ErrorData добавляется в очередь вывода. Затем объект RealTimeStylus возобновляет нормальную обработку исходных данных.
На следующей схеме показано добавление данных об ошибках в данные пера планшета.
На этой схеме круги с буквами "A" и "B" представляют данные пера планшета, которые уже были добавлены в очередь вывода объекта RealTimeStylus и еще не отправлены в асинхронную коллекцию подключаемых модулей. Круг с буквой "C" представляет данные пера планшета, которые в настоящее время обрабатывает объект RealTimeStylus . Круг с буквой "e" представляет объект ErrorData , созданный объектом RealTimeStylus , когда второй синхронный подключаемый модуль Synchronous Plug-in 2 создает исключение при обработке "C". Затем объект 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 в потоке, из которого создается исключение.
Связанные темы