Usando a biblioteca COM

Agora, a referência da biblioteca gerenciada do Tablet PC pode ser encontrada na seção de referência regular Windows Biblioteca de Classes do SDK do 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 dos 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 em COM, mas o FrameworkSDK fornece implementação nativa para Classe InkRectangle e 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 em ASP (Páginas do Servidor Ativo).

 

Trabalhando com coleções

Se você 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 coagidos a 0 quando a chamada é feita.

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

Em 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 através dos 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 de coleção na Biblioteca COM, receberá o primeiro item na coleção porque esses valores de argumento são coagidos a 0 quando a chamada é feita.

Usando IDispatch

Para aumentar o desempenho, a API (interface de programação de aplicativo COM) do Tablet PC Platform não dá suporte à chamada IDispatchImpl::Invoke com uma estrutura DISPPARAMS com argumentos nomeados. O IDispatchImpl::GetIDsOfNames também não tem suporte. Em vez disso, chame Invoke com os DISPIDs fornecidos nos cabeçalhos do SDK.

Aguardando eventos

O ambiente do Tablet PC é multithread. Consulte a documentação COM para vários threadings.

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 no 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 do sindicato é válido. Quando você receber informações em uma estrutura VARIANT, verifique o membro do vt para descobrir qual membro contém dados válidos. Da mesma forma, ao enviar informações usando uma estrutura VARIANT, sempre defina o vt para refletir o membro do sindicato que contém as informações.

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

Para obter mais informações sobre a estrutura VARIANT, consulte VARIANT e VARIANTARG Data Types.

A estrutura SAFEARRAY é fornecida como uma maneira de trabalhar com segurança com matrizes em COM. O campo parray do VARIANT é um ponteiro para um 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 o Tipo de Dados SafeArray.

Este exemplo C++ cria um IInkStrokeDisp , pInkStrokeDispem um objeto InkDisp , pInkde 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 com término 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 o Tipo de Dados BSTR.

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