Uso della libreria COM

Il riferimento alla libreria gestita di Tablet PC è ora disponibile nella sezione di riferimento della libreria di classi di Windows Vista SDK regolare. Fornisce un modello a oggetti per Microsoft Visual C++. La maggior parte degli oggetti nella libreria COM è identica a quelle trovate 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 la classe InkRectangle e la classe InkTransform che elimina la necessità di questi oggetti nell'API gestita della piattaforma Tablet PC.

Nota

Gli oggetti nell'API COM e i controlli input penna non sono progettati per l'uso in Pagine server attive (ASP).

 

Uso delle raccolte

Se si passa un valore NULL come indice a uno degli oggetti della raccolta nella libreria COM, viene visualizzato il primo elemento della raccolta perché questi valori di argomento vengono coerciti a 0 quando viene eseguita la chiamata.

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

In C++, usare un For... ciclo per scorrere una raccolta ottenendo prima la lunghezza della raccolta. Nell'esempio seguente viene illustrato come eseguire l'iterazione dei tratti di un oggetto 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
              // ...
            }
        }
    }
}

Parametri

Se si passa VT_EMPTY o VT_NULL come indice a uno degli oggetti di raccolta nella libreria COM, viene visualizzato il primo elemento dell'insieme perché questi valori di argomento vengono coesi a 0 quando viene eseguita la chiamata.

Uso di IDispatch

Per aumentare le prestazioni, l'api (API) dell'applicazione Tablet PC Platform non supporta la chiamata IDispatchImpl::Invoke con una struttura DISPPARAMS con argomenti denominati. L'oggetto IDispatchImpl::GetIDsOfNames non è supportato. Chiamare Invoke invece con i DISPID forniti nelle intestazioni dell'SDK.

Attesa di eventi

L'ambiente Tablet PC è multithreaded. Vedere la documentazione COM per il multi-threading.

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. Questa sezione descrive come usarli.

VARIANT e SAFEARRAY

La struttura VARIANT viene usata 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 usando 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 VARIANTInit COM. Al termine della struttura, cancellarlo prima che la memoria contenente l'oggetto 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 compilare un'operatore SAFEARRAY in una VARIANTE.

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

Questo esempio di C++ crea un oggetto IInkStrokeDisp , in un oggetto InkDisp, pInk, pInkStrokeDispda 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 terminatore), archiviato nei 4 byte immediatamente precedenti al primo carattere della stringa.

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

Questo esempio di C++ illustra come impostare il factoid su un oggetto InkRecognizerContext usando un 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);
}