Uso della libreria COM

Le informazioni di riferimento sulla libreria gestita di Tablet PC sono ora disponibili nella normale sezione di riferimento della libreria di classi di Windows Vista SDK. Fornisce un modello a oggetti per Microsoft Visual C++. La maggior parte degli oggetti nella libreria COM è identica a quella presente nell'API gestita da Tablet PC.

Tuttavia, l'API COM contiene alcuni membri oltre a quelli trovati nell'API gestita a causa delle differenze tra l'ambiente Microsoft Win32 standard e l'ambiente Microsoft .NET Frameworksoftware Development Kit (SDK). Ad esempio, gli oggetti InkRectangle e InkTransform vengono usati in COM, ma FrameworkSDK fornisce l'implementazione nativa per Classe InkRectangle e Classe InkTransform che elimina la necessità di questi oggetti nell'API gestita della piattaforma Tablet PC.

Uso delle raccolte

Se si passa un valore NULL come indice a uno degli oggetti delle collezioni nella libreria COM, si riceve il primo elemento della collezione perché questi valori di argomento vengono forzati a 0 quando viene effettuata la chiamata.

La proprietà _NewEnum è contrassegnata come limitata nella definizione IDL (Interface Definition Language) per le interfacce della raccolta.

In C++, usare un ciclo For... per scorrere una raccolta ottenendo prima la lunghezza della raccolta. Nell'esempio seguente viene illustrato come scorrere i tratti di un oggetto InkDisppInk.

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
              // ...
            }
        }
    }
}

Parametri

Se si passa VT_EMPTY o VT_NULL come indice a uno qualsiasi degli oggetti della raccolta nella libreria COM, si riceve il primo elemento della raccolta perché questi valori di argomento vengono forzati a 0 quando si effettua la chiamata.

Uso di IDispatch

Per migliorare le prestazioni, l'API (Tablet PC Platform Application Programming Interface) non supporta la chiamata IDispatchImpl::Invoke con una struttura DISPPARAMS con argomenti denominati. Il IDispatchImpl::GetIDsOfNames non è supportato. Chiamare invece Invoke con i DISPID forniti nelle intestazioni DELL'SDK.

In attesa di eventi

L'ambiente Tablet PC è multithreading. Vedere la documentazione COM per il multithreading.

Supporto per l'aggregazione

L'aggregazione è stata testata solo per il controllo InkEdit, il controllo InkPicture, l'oggetto InkDisp e l'oggetto InkOverlay. L'aggregazione non è stata testata per altri controlli e oggetti nella libreria.

C++

L'uso di Tablet PC SDK in C++ richiede l'uso di alcuni concetti COM, ad esempio VARIANT, SAFEARRAY e BSTR. In questa sezione viene descritto come usarli.

VARIANT e SAFEARRAY

La struttura VARIANT viene utilizzata per la comunicazione tra oggetti COM. Essenzialmente, la struttura VARIANT è un contenitore per un'unione di grandi dimensioni che contiene molti tipi di dati.

Il valore nel primo membro della struttura vt descrive quale dei membri dell'unione è valido. Quando si ricevono informazioni in una struttura VARIANT, controllare il membro vt per scoprire quale membro contiene dati validi. Analogamente, quando si inviano informazioni utilizzando una struttura VARIANT, impostare sempre vt per riflettere il membro dell'unione che contiene le informazioni.

Prima di usare la struttura, inizializzarla chiamando la funzione COM VariantInit. Al termine della struttura, cancellarlo prima che la memoria contenente variant venga liberata chiamando VariantClear.

Per altre informazioni sulla struttura VARIANT, vedere tipi di dati VARIANT e VARIANTARG.

La struttura SAFEARRAY viene fornita come modo per lavorare in modo sicuro con matrici in COM. Il campo parray di VARIANT è un puntatore a un SAFEARRAY. Usare funzioni come SafeArrayCreateVector, SafeArrayAccessData e SafeArrayUnaccessData per creare e riempire un SAFEARRAY in un valore VARIANT.

Per ulteriori informazioni sul tipo di dati SAFEARRAY, vedere Tipo di dati SafeArray.

Questo esempio C++ crea un IInkStrokeDisp , pInkStrokeDisp, in un oggetto InkDisp, pInk, da una matrice di dati punto.

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

Il formato stringa supportato per COM è BSTR. Un BSTR ha un puntatore a una stringa con terminazione zero, ma contiene anche la lunghezza della stringa (in byte, senza contare il carattere di terminazione), archiviato nei 4 byte immediatamente precedenti al primo carattere della stringa.

Per altre informazioni su BSTR, vedere tipo di dati BSTR.

Questo esempio C++ illustra come impostare il factoid in un InkRecognizerContext usando una stringa 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);
}