Dados de plug-in e a classe RealTimeStylus
Os plug-ins para a classe RealTimeStylus devem implementar a interface IStylusSyncPlugin ou IStylusAsyncPlugin ou ambos. Embora você precise implementar todos os métodos de interface de plug-in, seu plug-in recebe apenas chamadas em métodos sinalizados na propriedade Microsoft.StylusInput.IStylusSyncPlugin.DataInterest ou Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest .
Os métodos definidos nas interfaces usam objetos no namespace Microsoft.StylusInput.PluginData para passar os dados da caneta para os plug-ins. A tabela a seguir descreve os objetos de dados que são parâmetros nos métodos de notificação e lista o valor DataInterestMask associado à notificação.
| Dados de plug-in | Valor de DataInterestMask | Descrição |
|---|---|---|
| Customstylusdata | CustomStylusDataAdded | Dados de aplicativo personalizados que um plug-in adiciona. |
| Errordata | Erro | Informações de erro que o objeto RealTimeStylus adiciona em resposta a uma exceção sem tratamento em um de seus plug-ins. |
| Inairpacketsdata | InAirPackets | Informações de pacote para movimento de caneta enquanto a caneta está no ar acima do digitalizador. |
| Packetsdata | Pacotes | Informações de pacote para movimento de caneta enquanto a caneta está tocando o digitalizador. |
| Realtimestylusdisableddata | RealTimeStylusDisabled | Informações que o objeto RealTimeStylus adiciona quando está sendo desabilitado. |
| RealTimeStylusEnabledData | RealTimeStylusEnabled | Informações que o objeto RealTimeStylus adiciona quando está sendo habilitado. |
| Stylusbuttondowndata | Stylusbuttondown | Informações sobre o botão de caneta específico que está sendo pressionado. |
| Stylusbuttonupdata | Stylusbuttonup | Informações sobre o botão de caneta específico que está sendo liberado. |
| Stylusdowndata | Stylusdown | Informações de pacote para uma caneta à medida que a caneta é trazida em contato com o digitalizador. |
| Stylusinrangedata | Stylusinrange | Informações sobre a caneta específica que está entrando na área de entrada do objeto RealTimeStylus ou inserindo o intervalo de detecção do digitalizador acima da área de entrada do objeto RealTimeStylus . |
| Stylusoutofrangedata | Stylusoutofrange | Informações sobre a caneta específica que está deixando a área de entrada do objeto RealTimeStylus ou deixando o intervalo de detecção do digitalizador acima da área de entrada do objeto RealTimeStylus . |
| Stylusupdata | Stylusup | Informações de pacote para uma caneta à medida que a caneta é levantada do digitalizador. |
| Systemgesturedata | Systemgesture | Informações que o objeto RealTimeStylus adiciona quando detecta um gesto do sistema. |
| Tabletaddeddata | Tablet Adicionado | Informações sobre o objeto Tablet que está sendo adicionado. |
| Tabletremoveddata | TabletRemoved | Informações sobre o objeto Tablet que está sendo removido. |
Para obter informações sobre como o objeto RealTimeStylus manipula o fluxo de dados da caneta tablet, consulte Trabalhando com a classe RealTimeStylus.
Interesse de dados
O objeto RealTimeStylus verifica a propriedade Microsoft.StylusInput.IStylusSyncPlugin.DataInterest ou Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest de um plug-in quando o plug-in é adicionado à coleção de plug-ins síncrona ou assíncrona do objeto RealTimeStylus . Portanto, você deve usar a propriedade DataInterest para assinar todas as notificações que essa instância do plug-in usa, embora com pouca frequência, mas não para nenhuma das notificações que essa instância do plug-in nunca usa. Para notificações que seu plug-in usa apenas ocasionalmente marcar o estado do plug-in no método de notificação primeiro e retornar se a notificação não for usada pelo plug-in em seu estado atual.
Um plug-in recebe apenas chamadas em métodos sinalizados na propriedade Microsoft.StylusInput.IStylusSyncPlugin.DataInterest ou Microsoft.StylusInput.IStylusAsyncPlugin.DataInterest do plug-in. Para obter mais informações sobre os valores possíveis da propriedade DataInterest de um plug-in, consulte a enumeração DataInterestMask .
Timing
Os dados são enfileirados no objeto RealTimeStylus antes de serem passados para os plug-ins na coleção de plug-ins assíncrona. A lista a seguir descreve algumas situações que talvez você precise considerar ao criar um plug-in assíncrono.
- Quando o objeto RealTimeStylus é desabilitado , o plug-in assíncrono pode receber outras notificações enfileiradas antes que seu método RealTimeStylusDisabled seja chamado. Nessa situação, chamadas do plug-in para alguns dos métodos e propriedades do objeto RealTimeStylus geram uma exceção. As informações relevantes para o plug-in devem ser armazenadas em cache quando o objeto RealTimeStylus estiver habilitado.
- O método ClearStylusQueues do objeto RealTimeStylus pode remover informações da fila de saída. Portanto, os plug-ins assíncronos não podem depender do recebimento de todas as notificações relevantes.
- Quando um objeto Tablet que está disponível para o objeto RealTimeStylus é removido, o plug-in assíncrono pode receber notificação de caneta enfileirada para o tablet antes que seu método TabletRemoved seja chamado. Nessa situação, chamar o método GetTabletPropertyDescriptionCollection do objeto RealTimeStylus não funciona. As informações relevantes para o plug-in devem ser armazenadas em cache quando o objeto RealTimeStylus estiver habilitado ou quando um novo tablet for adicionado.
Dependendo do aplicativo, você pode melhorar o desempenho ao desabilitar um objeto RealTimeStylus . Quando a propriedade Enabled do objeto RealTimeStylus é definida como FALSE, os dados nas filas de entrada e saída são processados até que as filas estejam vazias. Você pode chamar o método ClearStylusQueues do objeto RealTimeStylus para limpar as filas antes de desabilitar o objeto RealTimeStylus.
Dados habilitados e desabilitados
Quando o objeto RealTimeStylus está habilitado, cada plug-in recebe uma chamada para seu método Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled ou Microsoft.StylusInput.IStylusAsyncPlugin.RealTimeStylusEnabled . O objeto RealTimeStylusEnabledData passado na notificação contém uma coleção dos identificadores de contexto para os tablets disponíveis no momento em que o objeto RealTimeStylus está habilitado.
Observação
Como os dados de plug-in da coleção de plug-ins assíncrona do objeto RealTimeStylus são enfileirados, os plug-ins assíncronos podem receber dados antes de receber uma chamada para seu método RealTimeStylusDisabled , mas depois que o objeto RealTimeStylus é desabilitado . Observe que alguns dos métodos e propriedades do objeto RealTimeStylus geram uma exceção se o objeto RealTimeStylus estiver desabilitado .
O objeto RealTimeStylus chama os métodosMicrosoft.StylusInput.IStylusSyncPlugin.RealTimeStylusEnabled e Microsoft.StylusInput.IStylusSyncPlugin.RealTimeStylusDisabled no thread do qual o objeto RealTimeStylus está habilitado ou do qual o plug-in síncrono é adicionado.
Geralmente, adicione ou remova plug-ins enquanto o objeto RealTimeStylus está desabilitado . Para obter mais informações sobre como adicionar e remover plug-ins ao objeto RealTimeStylus , consulte Plug-ins e a classe RealTimeStylus.
Dados do tablet
Quando um tablet que o objeto RealTimeStylus pode usar é adicionado ou removido do Tablet PC enquanto o objeto RealTimeStylus está habilitado, o objeto RealTimeStylus notifica seus plug-ins de que um objeto Tablet foi adicionado ou removido. Cada objeto RealTimeStylus mantém uma lista de identificadores exclusivos para os objetos Tablet com os quais ele pode interagir. O objeto RealTimeStylus tem dois métodos para traduzir entre o identificador exclusivo e o objeto Tablet, os métodos GetTabletContextIdFromTablet e GetTabletFromTabletContextId .
Observação
As informações sobre um tablet não estão mais disponíveis no objeto RealTimeStylus depois que o tablet é removido do Tablet PC.
Dados da caneta tablet
O objeto RealTimeStylus passa informações sobre a caneta tablet para seus plug-ins em vários dos métodos de notificação. As informações sobre a caneta tablet são representadas por um objeto Stylus . Esse objeto é um instantâneo do estado da caneta tablet no momento em que os dados foram coletados. Como os plug-ins recebem os dados da caneta tablet como parte do fluxo de dados da caneta tablet, os plug-ins devem usar as informações no objeto Stylus em vez de verificar o estado atual de uma caneta tablet específica por meio da classe Cursor .
Cada objeto Stylus contém o identificador de contexto do tablet para o tablet que gerou os dados.
Dados de gesto do sistema
O objeto RealTimeStylus recebe dados sobre gestos do sistema conforme eles são reconhecidos pelo Tablet PC. A tabela a seguir descreve a ordem na qual os objetos SystemGestureData ocorrem no fluxo de dados da caneta tablet em relação a outros dados de caneta tablet.
| Systemgesture | Objetos que precedem o objeto SystemGestureData | Objetos que vêm após o objeto SystemGestureData |
|---|---|---|
| Toque | O objeto StylusDownData . |
O objeto StylusUpData . |
| DoubleTap | O objeto StylusDownData , o objeto SystemGestureData para o gesto do sistema Tap e os objetos StylusUpData . |
O segundo objeto StylusDownData . |
| RightTap | O objeto StylusDownData e o objeto SystemGestureData para o membro HoldEnter da enumeração SystemGesure . |
O objeto StylusUpData . |
| Arrastar | O objeto StylusDownData . |
O objeto StylusUpData . |
| RightDrag | O objeto StylusDownData . |
O objeto StylusUpData . |
| HoldEnter | O objeto StylusDownData . |
O objeto StylusUpData . Nota: Esse gesto do sistema não será reconhecido se o usuário iniciar um gesto do sistema Drag ou RightDrag . |
| HoldLeave | Não implementado. |
Não implementado. |
| HoverEnter | Vários objetos InAirPacketsData de baixa velocidade média. |
Nota: Pode haver um atraso perceptível antes de receber o gesto do sistema HoverEnter . O objeto RealTimeStylus só receberá esses dados se o objeto RealTimeStylus estiver anexado à janela ou ao controle que está diretamente sob a caneta no momento do gesto do sistema. |
| HoverLeave | O objeto SystemGestureData para o gesto do sistema HoverEnter e vários objetos InAirPacketsData de velocidade média suficiente. |
Nota: Pode haver um atraso perceptível antes de receber o gesto do sistema HoverLeave . O objeto RealTimeStylus só receberá esses dados se o objeto RealTimeStylus estiver anexado à janela ou ao controle que está diretamente sob a caneta no momento do gesto do sistema. |
Dados de caneta personalizados
Os dados de caneta personalizados podem ser adicionados ao objeto RealTimeStylus chamando o método AddCustomStylusDataToQueue . Os dados de caneta personalizados podem ser adicionados às filas do objeto RealTimeStylus em um dos três locais.
- Quando o parâmetro de fila é definido como Saída, os dados personalizados são adicionados à fila de saída do objeto RealTimeStylus após os dados atualmente sendo processados pela coleção de plug-in síncrona.
- Quando o parâmetro de fila é definido como OutputImmediate, os dados personalizados são adicionados à fila de saída do objeto RealTimeStylus antes que os dados atualmente sejam processados pela coleção de plug-ins síncrona.
- Quando o parâmetro de fila é definido como Entrada, os dados personalizados são adicionados à fila de entrada do objeto RealTimeStylus e são enviados para a coleção de plug-in síncrona antes de novos dados do fluxo de dados da caneta tablet.
Em cada um dos casos anteriores, os dados adicionados por plug-ins subsequentes na coleção de plug-ins síncronos são adicionados após os dados adicionados pelos plug-ins anteriores.
Observação
Se a chamada para o método AddCustomStylusDataToQueue for feita de um plug-in síncrono em resposta a uma chamada a um de seus métodos IStylusSyncPlugin , os dados de caneta personalizados serão adicionados ao fluxo de dados da caneta tablet de maneira previsível; caso contrário, ele é adicionado à fila em relação aos dados de caneta atuais que o objeto RealTimeStylus está processando e não em relação aos dados que o plug-in assíncrono está processando. O método AddCustomStylusDataToQueue gerará uma exceção se o objeto RealTimeStylus estiver desabilitado .
Os dados de caneta personalizados são adicionados à fila como um objeto CustomStylusData e os plug-ins recebem esses dados por meio do método Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded ou Microsoft.StylusInput.IStylusAsyncPlugin.CustomStylusDataAdded .
Os objetos DynamicRenderer e GestureRecognizer podem adicionar dados de caneta personalizados à fila. Para obter mais informações sobre o DynamicRenderer e os objetos GestureRecognizer , consulte Plug-ins do Dynamic-Renderer e Plug-ins recognizer.
O objeto RealTimeStylus chama o método Microsoft.StylusInput.IStylusSyncPlugin.CustomStylusDataAdded no thread do qual recebe a chamada para seu método AddCustomStylusDataToQueue .
O diagrama a seguir ilustra a adição de dados de caneta personalizados à fila de saída com o parâmetro de fila definido como Saída.
Neste diagrama, os círculos com letras "A" e "B" representam dados de caneta tablet que já foram adicionados à fila de saída do objeto RealTimeStylus e que ainda não foram enviados para a coleção de plug-ins assíncrona. O círculo com letras "C" representa os dados da caneta tablet que o objeto RealTimeStylus está processando no momento. Ele é enviado para a coleção de plug-in síncrono e colocado na fila de saída. Os círculos numerados "1", "2" e "3" representam dados de caneta personalizados que foram adicionados à fila de saída pelo primeiro, segundo e terceiro plug-ins síncronos, respectivamente, em resposta aos dados da caneta tablet representados por "C". Os plug-ins adicionaram os dados de caneta personalizados com o parâmetro de fila definido como StylusQueues. O círculo vazio representa a posição na fila de saída em que os dados futuros da caneta tablet são adicionados.
O diagrama a seguir ilustra a adição de dados de caneta personalizados à fila de saída com o parâmetro de fila definido como OutputImmediate.
Neste diagrama, os círculos com letras "A" e "B" representam dados de caneta tablet que já foram adicionados à fila de saída do objeto RealTimeStylus e que ainda não foram enviados para a coleção de plug-ins assíncrona. O círculo com letras "C" representa os dados da caneta tablet que o objeto RealTimeStylus está processando no momento. Ele é enviado para a coleção de plug-in síncrono e colocado na fila de saída. Os círculos numerados "1", "2" e "3" representam dados de caneta personalizados que foram adicionados à fila de saída pelo primeiro, segundo e terceiro plug-ins síncronos, respectivamente, em resposta aos dados da caneta tablet representados por "C". Os plug-ins adicionaram os dados de caneta personalizados com o parâmetro de fila definido como OutputImmediate. O círculo vazio representa a posição na fila de saída em que os dados futuros da caneta tablet são adicionados.
O diagrama a seguir ilustra a adição de dados de caneta personalizados à fila de entrada.
Neste diagrama, os círculos com letras "A" e "B" representam dados de caneta tablet que já foram adicionados à fila de saída do objeto RealTimeStylus e que ainda não foram enviados para a coleção de plug-ins assíncrona. O círculo com letras "C" representa os dados da caneta tablet que o objeto RealTimeStylus está processando no momento. Ele é enviado para a coleção de plug-in síncrono e colocado na fila de saída. Os círculos numerados "1", "2" e "3" representam dados de caneta personalizados que foram adicionados à fila de entrada pelo primeiro, segundo e terceiro plug-ins síncronos, respectivamente, em resposta aos dados da caneta tablet representados por "C". Os plug-ins adicionaram os dados de caneta personalizados com o parâmetro de fila definido como Entrada. Os dados de caneta personalizados numerados "1" são então passados para os plug-ins síncronos e, em seguida, para a fila de saída antes que os dados de caneta personalizados sejam numerados como "2" e "3", ambos processados antes que os próximos dados da caneta tablet sejam processados. O círculo vazio representa a posição na fila de saída em que os dados futuros da caneta tablet são adicionados.
Dados de erro
Quando um plug-in gera uma exceção, o fluxo normal de dados é interrompido. O objeto RealTimeStylus gera um objeto ErrorData e chama:
- O método Microsoft.StylusInput.IStylusSyncPlugin.Error ou Microsoft.StylusInput.IStylusAsyncPlugin.Error do plug-in que gerou a exceção.
- O método Microsoft.StylusInput.IStylusSyncPlugin.Error ou Microsoft.StylusInput.IStylusAsyncPlugin.Error dos plug-ins restantes nessa coleção.
Se o plug-in que gerou a exceção for um plug-in síncrono, o objeto ErrorData será adicionado à fila de saída. Em seguida, o objeto RealTimeStylus retoma o processamento normal dos dados originais.
O diagrama a seguir ilustra a adição de dados de erro aos dados da caneta tablet.
Neste diagrama, os círculos com letras "A" e "B" representam dados de caneta tablet que já foram adicionados à fila de saída do objeto RealTimeStylus e que ainda não foram enviados para a coleção de plug-ins assíncrona. O círculo com letras "C" representa os dados da caneta tablet que o objeto RealTimeStylus está processando no momento. O círculo com letras "e" representa um objeto ErrorData gerado pelo objeto RealTimeStylus quando o segundo plug-in síncrono, Plug-in Síncrono 2, gera uma exceção enquanto está processando "C". O objeto RealTimeStylus pausa o processamento de "C" e passa "e" para o plug-in que gerou a exceção e todos os plug-ins subsequentes. Em seguida, o objeto RealTimeStylus coloca "e" na fila de saída e retoma o processamento de "C", que é passado para os plug-ins restantes na coleção de plug-ins síncrona e colocado na fila de saída após "e". O círculo vazio representa a posição na fila de saída em que os dados futuros da caneta tablet são adicionados.
Se um plug-in gerar uma exceção de seu método Error, o objeto RealTimeStylus capturará a exceção, mas não gerará um novo objeto ErrorData . Isso é para evitar a recursão.
Os dados de erro são adicionados à fila de saída após quaisquer dados de caneta personalizados adicionados na posição OutputImmediate antes da exceção que criou os dados de erro e antes de quaisquer dados de caneta personalizados adicionados na posição OutputImmediate por plug-ins subsequentes na coleção de plug-ins síncrona.
O diagrama a seguir ilustra como os dados de erro são adicionados à fila de saída em relação aos dados personalizados adicionados à fila OutputImmediate .
Neste diagrama, os círculos com letras "A" e "B" representam dados de caneta tablet que já foram adicionados à fila de saída do objeto RealTimeStylus e que ainda não foram enviados para a coleção de plug-ins assíncrona. O círculo com letras "C" representa os dados da caneta tablet que o objeto RealTimeStylus está processando no momento. Os círculos numerados "1", "2" e "3" são adicionados pelo primeiro, segundo e terceiro plug-ins síncronos, respectivamente, à fila OutputImmediate em resposta aos dados representados pelo círculo com letras "C". O círculo com letras "e" representa os dados de erro gerados em resposta a uma exceção gerada pelo segundo plug-in depois que o segundo plug-in adicionou dados personalizados à fila de saída na posição OutputImmediate .
Se qualquer plug-in síncrono adicionar dados de caneta personalizados à fila de entrada em resposta aos dados de erro, os dados serão adicionados imediatamente antes dos dados de erro. Se qualquer um dos plug-ins síncronos adicionar dados de caneta personalizados à fila de saída na posição Saída em resposta aos dados de erro, os dados serão adicionados imediatamente após os dados de erro.
O objeto RealTimeStylus chama o método Microsoft.StylusInput.IStylusSyncPlugin.Error no thread do qual a exceção é gerada.
Tópicos relacionados