Trabalhando com a classe RealTimeStylus
A classe RealTimeStylus faz parte das APIs (interfaces de programação de aplicativo) StylusInput. As seções a seguir descrevem os principais elementos da classe RealTimeStylus e das APIs StylusInput.
Instanciando a classe RealTimeStylus
Ao criar um objeto RealTimeStylus , você tem a opção de anexá-lo a um identificador de janela ou a um controle. Anexar o objeto RealTimeStylus a um identificador de janela requer permissões adicionais. Para obter mais informações sobre essas permissões, consulte Considerações de confiança parcial para as APIs stylusInput.
Observação
Você não pode anexar o objeto RealTimeStylus a uma janela ou controle em um processo diferente.
Se você usar o construtor padrão, criará um objeto RealTimeStylus que só pode aceitar a entrada de outro objeto RealTimeStylus . Para obter mais informações sobre como conectar dois objetos RealTimeStylus , consulte The Cascaded RealTimeStylus Model.
O objeto RealTimeStylus implementa a interface IDisposable .
Estendendo a classe RealTimeStylus
Para permitir que seus plug-ins interajam com o fluxo de dados da caneta tablet, o objeto RealTimeStylus mantém duas coleções de plug-in, que são acessíveis pelas propriedades GetStylusSyncPlugin e GetStylusAsyncPlugin em C++ e pelas propriedades SyncPluginCollection e AsyncPluginCollection no código gerenciado. Você pode adicionar um plug-in chamando o método AddStylusSyncPlugin ou AddStylusAsyncPlugin da coleção dentro da propriedade apropriada. Para obter mais informações sobre como criar e usar plug-ins, consulte Plug-ins e a classe RealTimeStylus. Para obter informações sobre como decidir se deseja criar um plug-in síncrono ou assíncrono para uma tarefa específica, consulte Considerações de threading para as APIs stylusInput e considerações de desempenho para as APIs StylusInput.
Os plug-ins síncronos devem implementar a interface IStylusSyncPlugin e os plug-ins assíncronos devem implementar a interface IStylusAsyncPlugin . Cada plug-in tem uma propriedade IStylusSyncPlugin.DataInterest ou IStylusAsyncPlugin.DataInterest . O objeto RealTimeStylus chama apenas os métodos de notificação do plug-in para métodos nos quais o plug-in se inscreveu. Para obter mais informações sobre os métodos de notificação, consulte Dados de plug-in e a classe RealTimeStylus.
O objeto RealTimeStylus implementa a interface IStylusAsyncPlugin . A única maneira de instanciar um objeto RealTimeStylus que aceita a entrada de outro objeto RealTimeStylus é usar o construtor padrão e implementar o modelo RealTimeStylus em cascata. Para obter mais informações sobre como conectar dois objetos RealTimeStylus , consulte The Cascaded RealTimeStylus Model.
O objeto RealTimeStylus tem duas filas internas que carregam os dados da caneta tablet, a fila de entrada e a fila de saída. Os dados de caneta são convertidos em instâncias das classes no namespace Microsoft.StylusInput.PluginData . A lista a seguir descreve como o objeto RealTimeStylus manipula os dados da caneta tablet.
- O objeto RealTimeStylus verifica se há objetos de dados de plug-in primeiro em sua fila de entrada e, em seguida, no fluxo de dados da caneta tablet.
- O objeto RealTimeStylus envia um objeto de dados plug-in para os objetos em sua coleção de plug-in síncrona. Cada plug-in síncrono pode adicionar dados à fila de entrada ou saída.
- Depois que o objeto de dados do plug-in for enviado a todos os membros da coleção de plug-ins síncrona, o objeto de dados de plug-in será colocado na fila de saída do objeto RealTimeStylus .
- Em seguida, o objeto RealTimeStylus verifica o próximo objeto de dados de plug-in a ser processado.
- Embora a fila de saída do objeto RealTimeStylus contenha dados, o objeto RealTimeStylus envia um objeto de dados plug-in de sua fila de saída para os objetos em sua coleção de plug-ins assíncrona. Cada plug-in assíncrono pode adicionar dados à fila de entrada ou saída, mas como os plug-ins assíncronos são executados no thread da interface do usuário, os dados são adicionados à fila em relação aos dados da caneta atual que o objeto RealTimeStylus está processando e não em relação aos dados que o plug-in assíncrono está processando.
O diagrama a seguir ilustra o fluxo de dados de caneta tablet por meio do objeto RealTimeStylus e suas coleções de plug-in.
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. O círculo vazio representa a posição na fila de saída em que os dados futuros da caneta tablet são adicionados.
Para obter mais informações sobre como dados específicos são adicionados à fila e processados, consulte Dados de plug-in e a classe RealTimeStylus.
Veja a seguir um cenário mínimo para usar o objeto RealTimeStylus em um formulário que coleta tinta.
- Crie um formulário que implemente a interface IStylusAsyncPlugin .
- Crie um objeto RealTimeStylus anexado a um controle no formulário.
- Defina interesse nas notificações StylusDown, Packets e StylusUp na propriedade IStylusAsyncPlugin.DataInterest do formulário.
- Nos métodos StylusDown, Packets e StylusUp do formulário, adicione código para manipular as notificações stylus down, packets e stylus up enviadas do objeto RealTimeStylus do formulário.
Para obter um exemplo desse aplicativo, consulte o Exemplo de Coleção de Tinta RealTimeStylus.
Trabalhando com objetos tablet
Cada objeto RealTimeStylus habilitado mantém uma lista de identificadores exclusivos para os objetos Tablet com os quais ele pode interagir. O objeto RealTimeStylus expõe dois métodos para traduzir entre o identificador exclusivo e o objeto Tablet : os métodos GetTabletContextIdFromTablet e GetTabletFromTabletContextId .
O objeto TabletPropertyDescription (em código gerenciado) contém uma propriedade PacketPropertyId e uma estrutura TabletPropertyMetrics que descreve o intervalo, a resolução e as unidades da propriedade para um objeto Tablet específico. O método GetDesiredPacketDescription do objeto RealTimeStylus retorna uma matriz de GUIDs (identificadores globalmente exclusivos) para as propriedades de pacote que o objeto RealTimeStylus encaminha para seus plug-ins quando essas propriedades de pacote estão disponíveis. Para modificar o conjunto de propriedades de pacote que o objeto RealTimeStylus passa para seus plug-ins, chame o método SetDesiredPacketDescription do objeto RealTimeStylus. O método GetTabletPropertyDescriptionCollection (em código gerenciado) do objeto RealTimeStylus usa um identificador de tablet exclusivo e retorna uma coleção de objetos TabletPropertyDescription . Essas propriedades de pacote representam o subconjunto de propriedades compatíveis com o tablet que são retornadas pelo método GetDesiredPacketDescription .
Para obter uma lista dos GUIDs da propriedade de pacote padrão, consulte a classe PacketPropertyGuids Constants .
Considerações especiais
A lista a seguir descreve outros pontos a serem considerados ao usar o objeto RealTimeStylus com um objeto Tablet .
- O método SetDesiredPacketDescription só pode ser chamado enquanto o objeto Tablet está desabilitado. O objeto RealTimeStylus pode modificar a lista de propriedades de pacote desejadas; portanto, chame o método GetDesiredPacketDescription após a chamada para o método SetDesiredPacketDescription para determinar quais propriedades de pacote o objeto RealTimeStylus pode encaminhar para seus plug-ins. Um tablet só tem a garantia de dar suporte aos valores X, Y e PacketStatus para o PacketProperty. Portanto, o design do plug-in pode precisar considerar o recebimento de menos propriedades de pacote do que o desejado.
- O método GetTabletPropertyDescriptionCollection (para código gerenciado) só pode ser chamado enquanto o objeto RealTimeStylus está habilitado. Como a notificação pode ser enviada para os plug-ins assíncronos depois que o objeto RealTimeStylus for desabilitado , talvez seja necessário armazenar em cache as informações de cada objeto Tablet . O método GetTabletPropertyDescriptionCollection retorna uma lista das propriedades de pacote desejadas compatíveis com o tablet especificado.
- Quando o objeto RealTimeStylus está habilitado, cada plug-in recebe uma chamada para seu método 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.
- 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. Para obter mais informações, consulte Dados de plug-in e a classe RealTimeStylus.
Trabalhando com canetas 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 , obtido pelo método GetStyluses . Esse objeto é uma representação 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 . Para obter informações sobre como os dados do botão caneta tablet e caneta tablet são passados para plug-ins, consulte Dados de plug-in e a classe RealTimeStylus.
Para obter uma matriz dos objetos Stylus que o objeto RealTimeStylus encontrou desde que foi habilitado pela última vez, use o método GetStyluses do objeto RealTimeStylus.
Tópicos relacionados
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de