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 o Microsoft Visual C++. A maioria dos objetos na Biblioteca COM são idênticos aos encontrados na API gerenciada do 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 Microsoft .NET Frameworksoftware development kit (SDK). Por exemplo, os objetos InkRectangle e InkTransform são usados em COM, mas o FrameworkSDK fornece implementação nativa para InkRectangle Class e InkTransform Class que elimina a necessidade desses objetos na API gerenciada da plataforma Tablet PC.

Trabalhando com coleções

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

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

Em C++, utilize um loop do tipo For... para iterar por uma coleção, obtendo primeiro o comprimento da coleção. O exemplo abaixo mostra como iterar pelos traçados 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 de coleção na Biblioteca COM, receberá o primeiro item da coleção porque esses valores de argumento são coagidos a 0 quando a chamada é feita.

Usando IDispatch

Para aumentar o desempenho, a interface de programação de aplicativos (API) COM da plataforma Tablet PC não suporta chamar IDispatchImpl::Invoke com uma estrutura DISPPARAMS com argumentos nomeados. O IDispatchImpl::GetIDsOfNames também não é suportado. Em vez disso, utilize os DISPIDs fornecidos nos cabeçalhos do SDK para chamar Invoke.

À espera de eventos

O ambiente do Tablet PC é multiencadeado. Consulte a documentação COM para multithreading.

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++

Usar o 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 grande união que carrega muitos tipos de dados.

O valor no primeiro membro da estrutura, vt, descreve qual dos elementos da união é válido. Ao receber informações numa estrutura VARIANT, verifique 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 do sindicato que contém as informações.

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

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

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

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

Este exemplo de C++ cria um IInkStrokeDisp, pInkStrokeDisp, num InkDisp objeto, pInk, a partir 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 suportado 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 BSTR Data Type.

Este exemplo de C++ mostra como definir o factoide 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);
}