Usando a biblioteca COM

A referência da biblioteca gerenciada do tablet pc agora pode ser encontrada na seção de referência regular da Biblioteca de Classes do SDK do Windows Vista. Ele fornece um modelo de objeto para Microsoft Visual C++. A maioria dos objetos na Biblioteca COM é idêntica àquelas encontradas na API Gerenciada por Tablet PC.

No entanto, a API COM contém alguns membros além daqueles encontrados na API Gerenciada devido a diferenças entre o ambiente padrão do Microsoft Win32 e o ambiente do SDK (Kit de Desenvolvimento do Microsoft .NET Frameworksoftware). Por exemplo, os objetos InkRectangle e InkTransform são usados no COM, mas o FrameworkSDK fornece implementação nativa para a Classe InkRectangle e a Classe InkTransform que elimina a necessidade desses objetos na API Gerenciada da plataforma Tablet PC.

Observação

Os objetos na API COM e nos controles de tinta não foram projetados para uso no ASP (Active Server Pages).

 

Trabalhando com coleções

Se você passar um valor NULL como o índice para qualquer um dos objetos da coleção na Biblioteca COM, receberá o primeiro item na coleção porque esses valores de argumento são forçados a 0 quando a chamada é feita.

A propriedade _NewEnum é marcada como restrita na definição IDL (Interface Definition Language) para as interfaces de coleção.

No C++, use um For... loop para iterar por meio de uma coleção obtendo primeiro o comprimento da coleção. O exemplo a seguir mostra como iterar pelos traços de um objeto InkDisp , pInk.

IInkStrokes* pStrokes;
HRESULT result = pInk->get_Strokes(&pStrokes);
if (SUCCEEDED(result))
{
    // Loop over strokes
    long nStrokes;
    result = pStrokes->get_Count(&nStrokes);
    if (SUCCEEDED(result))
    {
        for (int i =0; i < nStrokes; i++)
        {
            IInkStrokeDisp* pStroke;
            result = pStrokes->Item(i, &pStroke);
            if (SUCCEEDED(result))
            {
              // Code that uses pStroke
              // ...
            }
        }
    }
}

Parâmetros

Se você passar VT_EMPTY ou VT_NULL como o índice para qualquer um dos objetos da coleção na Biblioteca COM, receberá o primeiro item na coleção porque esses valores de argumento são forçados a 0 quando a chamada é feita.

Usando IDispatch

Para aumentar o desempenho, a API (interface de programação de aplicativo) COM da Plataforma TABLET PC não dá suporte a chamadas IDispatchImpl::Invoke com uma estrutura DISPPARAMS com argumentos nomeados. Também IDispatchImpl::GetIDsOfNames não há suporte para o . Em vez disso, chame Invoke com os DISPIDs fornecidos nos cabeçalhos do SDK.

Aguardando eventos

O ambiente do tablet pc é multithreaded. Consulte a documentação COM para multi-threading.

Suporte para agregação

A agregação foi testada apenas para o controle InkEdit , o controle InkPicture , o objeto InkDisp e o objeto InkOverlay . A agregação não foi testada para outros controles e objetos na biblioteca.

C++

O uso do SDK do Tablet PC em C++ requer o uso de alguns conceitos COM, como VARIANT, SAFEARRAY e BSTR. Esta seção descreve como usá-los.

VARIANT e SAFEARRAY

A estrutura VARIANT é usada para comunicação entre objetos COM. Essencialmente, a estrutura VARIANT é um contêiner para uma união grande que carrega muitos tipos de dados.

O valor no primeiro membro da estrutura, vt, descreve qual dos membros da união é válido. Quando você recebe informações em uma estrutura VARIANT, marcar o membro vt para descobrir qual membro contém dados válidos. Da mesma forma, quando você envia informações usando uma estrutura VARIANT, sempre defina vt para refletir o membro da união que contém as informações.

Antes de usar a estrutura , inicialize-a chamando a função VARIANTInit COM. Quando terminar a estrutura, desmarque-a antes que a memória que contém a VARIANT seja liberada chamando VariantClear.

Para obter mais informações sobre a estrutura VARIANT, confira Tipos de dados VARIANT e VARIANTARG.

A estrutura SAFEARRAY é fornecida como uma maneira de trabalhar com segurança com matrizes em COM. O campo parray da VARIANT é um ponteiro para um SAFEARRAY. Use funções como SafeArrayCreateVector, SafeArrayAccessData e SafeArrayUnaccessData para criar e preencher uma SAFEARRAY em uma VARIANT.

Para obter mais informações sobre o tipo de dados SAFEARRAY, consulte Tipo de dados SafeArray.

Este exemplo de C++ cria um IInkStrokeDisp , pInkStrokeDisp, em um objeto InkDisp , pInk, de uma matriz de dados de ponto.

VARIANT   var, varPK;
LONG*   plongArray=NULL;
POINT   ptArray[2]={0};
long   lSize=0;
IInkStrokeDisp* pInkStrokeDisp;

IInkDisp*   pInk;   // the object should be created correctly 
                    // elsewhere and assigned here.
HRESULT   hr=E_FAIL;

ptArray[0].x = 20;
ptArray[0].y = 100;
ptArray[1].x = 30;
ptArray[1].y = 110;
lSize = 2;   // two points

VariantInit( &var );
VariantInit( &varPK );
SAFEARRAY* psa = SafeArrayCreateVector( VT_I4, 0, lSize*2 );
if( psa )
{
  if( SUCCEEDED( hr = SafeArrayAccessData( psa, (void**)&plongArray) ))
   {
      for( long i = 0; i < lSize; i++ ) 
      {
         plongArray[2*i] = ptArray[i].x;
         plongArray[2*i+1] = ptArray[i].y;
      }
      hr = SafeArrayUnaccessData( psa );

      if ( SUCCEEDED( hr ) ) 
      {
         var.vt     = VT_ARRAY | VT_I4;
         var.parray = psa;

        // varPK (packet description) is currently reserved, so it is
        // just empty variant for now.
         pInk->CreateStroke( var, varPK, &pInkStrokeDisp );   
      }
   }
}
VariantClear( &var );
VariantClear( &varPK );

BSTR

O formato de cadeia de caracteres com suporte para COM é BSTR. Um BSTR tem um ponteiro para uma cadeia de caracteres terminada em zero, mas também contém o comprimento da cadeia de caracteres (em bytes, sem contar o terminador), que é armazenado nos 4 bytes imediatamente anteriores ao primeiro caractere da cadeia de caracteres.

Para obter mais informações sobre BSTR, consulte Tipo de dados BSTR.

Este exemplo de C++ mostra como definir o factoid em um InkRecognizerContext usando um BSTR.

IInkRecognizerContext* pRecognizerContext = NULL;
result = CoCreateInstance(CLSID_InkRecognizerContext, 
    NULL, CLSCTX_INPROC_SERVER,
    IID_IInkRecognizerContext, 
    (void **) &pRecognizerContext);
if SUCCEEDED(result)
{
    BSTR bstrFactoid = SysAllocString(FACTOID_DATE);
    result = pRecognizerContext->put_Factoid(bstrFactoid);
    if SUCCEEDED(result)
    {
      // Use recognizer context...
      // ...
    }
    SysFreeString(bstrFactoid);
}