Método IStylusPlugin::StylusUp (rtscom.h)

Artigo
03/01/2024

Notifica o plug-in de implementação de que o usuário levantou a caneta tablet da superfície do digitalizador de tablets.

Sintaxe

HRESULT StylusUp(
  [in]      IRealTimeStylus  *piRtsSrc,
  [in]      const StylusInfo *pStylusInfo,
  [in]      ULONG            cPropCountPerPkt,
  [in]      LONG             *pPacket,
  [in, out] LONG             **ppInOutPkt
);

Parâmetros

[in] piRtsSrc

O objeto classe RealTimeStylus (RTS) que enviou a notificação.

[in] pStylusInfo

Uma estrutura StylusInfo que contém as informações sobre o RTS associado à caneta.

[in] cPropCountPerPkt

Número de propriedades por pacote. Os valores válidos são de 0 a 32, inclusive.

[in] pPacket

O início dos dados do pacote.

[in, out] ppInOutPkt

Um ponteiro para o pacote de dados de caneta modificado. O plug-in pode usar esse parâmetro para alimentar dados de pacote modificados para pacotes downstream. Um valor diferente de NULL indica que o pacote foi modificado e o RTS enviará esses dados para plug-ins usando o parâmetro pPacket .

Retornar valor

Para obter uma descrição dos valores retornados, consulte Classes e interfaces RealTimeStylus.

Comentários

Esse método é usado quando a caneta sai da superfície do digitalizador.

Você pode retornar uma matriz de pacotes modificados no buffer , ppInOutPkt. Os pacotes usados pelos métodos IStylusPlugin::StylusUp e IStylusPlugin::StylusDown só podem ser modificados. Eles não podem ser excluídos. Os pacotes usados pelos métodos IStylusPlugin::P ackets e Método IStylusPlugin::InAirPackets podem ser excluídos.

Se você modificar pacotes, cPropCountPerPkt, que é o número de LONGs em ppInOutPkt, deverá ser divisível pelas propriedades de pacote desejadas (DPP) atuais disponíveis no dispositivo de entrada atual.

Modifique os pacotes atualizando os parâmetros cPropCountPerPkt e ppInOutPkts . Altere cPropCountPerPkt para uma contagem de propriedades de pacote total válida e ppInOutPkts para um buffer de dados válido que contabilize valores para cada DPP em cada pacote. Somente um pacote pode estar presente nesse local para o Método IStylusPlugin::StylusUp e o Método IStylusPlugin::StylusDown.

Por exemplo, se você adicionar três pacotes e seu DPP for atualmente X,Y e Pressão, você deverá ter nove valores LONG nesse buffer e definir cPropCountPerPkt como 9.

O valor cPropCountPerPkt é útil para ajudar a esclarecer os limites entre pacotes na matriz simples de inteiros que entra para eventos como o evento NewPackets Event . Os pacotes podem ser agrupados para serem mais eficientes com a transferência de dados, de modo que não seja necessário que um plug-seja chamado uma vez por pacote.

Exemplos

O exemplo de código C++ a seguir implementa um método StylusUp que chama uma função auxiliar, ModifyPacket, para alterar o valor dos dados X,Y para fazê-lo se enquadrar em um retângulo especificado. Essa é a mesma funcionalidade implementada no exemplo de C#, Exemplo de plug-in RealTimeStylus. O segundo snippet de código é a função ModifyPacket .

STDMETHODIMP CPacketModifier::StylusUp( 
            /* [in] */ IRealTimeStylus *piRtsSrc,
            /* [in] */ const StylusInfo *pStylusInfo,
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
	return ModifyPacket(cPropCountPerPkt, pPacket, ppInOutPkt);
}

// Helper method to modify a single packet
// Called from StylusDown() and StylusUp()
HRESULT CPacketModifier::ModifyPacket(
            /* [in] */ ULONG cPropCountPerPkt,
            /* [size_is][in] */ LONG *pPacket,
            /* [out][in] */ LONG **ppInOutPkt)
{
	// Pointer to a buffer to hold changed packet values
	LONG* pTempOutPkt = NULL;
	
	// X and Y come first (0 and 1), 
	// other properties follow
	ULONG iOtherProps = 2;

	if (cPropCountPerPkt > 0)
	{
		pTempOutPkt = (LONG*)CoTaskMemAlloc(sizeof(LONG)*cPropCountPerPkt);

		if (NULL != pTempOutPkt)
		{
			// Packet data always has x followed by y followed by the rest.
			LONG x = pPacket[0];
			LONG y = pPacket[1];

			// In the packet data, check whether
			// its X,Y values fall outside of the specified rectangle.
			// If so, replace them with the nearest point that still
			// falls within the rectangle.
			x = (x < m_filterRect.left ? m_filterRect.left : x);
			x = (x > m_filterRect.right ? m_filterRect.right : x);
			y = (y < m_filterRect.top ? m_filterRect.top : y);
			y = (y > m_filterRect.bottom ? m_filterRect.bottom : y);

			// If necessary, modify the x,y packet data
			if ((x != pPacket[0]) || (y != pPacket[1]))
			{
				pTempOutPkt[0] = x;
				pTempOutPkt[1] = y;

				// Copy the properties that we haven't modified
				while (iOtherProps < cPropCountPerPkt)
				{
					pTempOutPkt[iOtherProps] = pPacket[iOtherProps++];
				}

				*ppInOutPkt = pTempOutPkt;
			}
			else
			{
				CoTaskMemFree(pTempOutPkt);
			}
		}
	}

	return S_OK;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP Tablet PC Edition [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Nenhum compatível
Plataforma de Destino	Windows
Cabeçalho	rtscom.h
DLL	RTSCom.dll