De COM-bibliotheek gebruiken

De naslaginformatie over de beheerde bibliotheek voor tablet-pc's vindt u nu in de reguliere naslagsectie van de Windows Vista SDK-klassebibliotheek. Het biedt een objectmodel voor Microsoft Visual C++. Het merendeel van de objecten in de COM-bibliotheek is identiek aan de objecten die zijn gevonden in de beheerde API voor tablet-pc's.

De COM-API bevat echter enkele leden naast die in de beheerde API vanwege verschillen tussen de standaard Microsoft Win32-omgeving en de Sdk-omgeving (Microsoft .NET Frameworksoftware Development Kit). De objecten InkRectangle en InkTransform worden bijvoorbeeld gebruikt in COM, maar de FrameworkSDK biedt systeemeigen implementatie voor InkRectangle Class en InkTransform Class waardoor deze objecten niet meer nodig zijn in de beheerde API van het Tablet PC-platform.

Werken met verzamelingen

Als u een NULL- waarde als index doorgeeft aan een van de verzamelingsobjecten in de COM-bibliotheek, ontvangt u het eerste item in de verzameling omdat deze argumentwaarden worden afgetrokken van 0 wanneer de aanroep wordt uitgevoerd.

De eigenschap _NewEnum is gemarkeerd als beperkt in de idL-definitie (Interface Definition Language) voor de verzamelingsinterfaces.

Gebruik in C++een For... lus om een verzameling te herhalen door eerst de lengte van de verzameling te verkrijgen. In het onderstaande voorbeeld ziet u hoe u de pennenstreken van een InkDisp--object, pInk, kunt herhalen.

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

Parameters

Als u VT_EMPTY of VT_NULL als index doorgeeft aan een van de verzamelingsobjecten in de COM-bibliotheek, ontvangt u het eerste item in de verzameling omdat deze argumentwaarden worden afgetrokken van 0 wanneer de aanroep wordt uitgevoerd.

IDispatch gebruiken

Om de prestaties te verbeteren, biedt de API (Tablet PC Platform COM Application Programming Interface) geen ondersteuning voor het aanroepen van IDispatchImpl::Invoke met een DISPPARAMS-structuur met benoemde argumenten. De IDispatchImpl::GetIDsOfNames wordt ook niet ondersteund. Roep in plaats daarvan Invoke aan met de DISPID's die zijn opgegeven in de SDK-headers.

Wachten op gebeurtenissen

De Tablet PC-omgeving is multithreaded. Raadpleeg de COM-documentatie voor multithreading.

Ondersteuning voor aggregatie

Aggregatie is alleen getest voor de controle InkEdit, de controle InkPicture, het InkDisp-object en het InkOverlay-object. Aggregatie is niet getest op andere besturingselementen en objecten in de bibliotheek.

C++

Voor het gebruik van de Tablet PC SDK in C++ zijn enkele COM-concepten vereist, zoals VARIANT, SAFEARRAY en BSTR. In deze sectie wordt beschreven hoe u deze kunt gebruiken.

VARIANT en SAFEARRAY

De VARIANT-structuur wordt gebruikt voor communicatie tussen COM-objecten. In wezen is de VARIANT-structuur een container voor een grote samenvoeging die veel soorten gegevens bevat.

De waarde in het eerste element van de structuur, vt, beschrijft welke van de leden van de union geldig is. Wanneer u informatie ontvangt in een VARIANT-structuur, controleert u het vt-lid om te achterhalen welk lid geldige gegevens bevat. Wanneer u gegevens verzendt met behulp van een VARIANT-structuur, moet u ook altijd vt instellen om het union-lid weer te geven dat de informatie bevat.

Voordat u de structuur gebruikt, initialiseert u deze door de functie VariantInit COM aan te roepen. Wanneer u klaar bent met de structuur, maakt deze leeg voordat het geheugen dat de VARIANT bevat, wordt vrijgemaakt door VariantClear aan te roepen.

Zie VARIANT- en VARIANTARG-gegevenstypenvoor meer informatie over de variantstructuur.

De SAFEARRAY-structuur wordt geleverd als een manier om veilig te werken met matrices in COM. Het parrayveld van DE VARIANT is een aanwijzer naar een SAFEARRAY. Gebruik functies zoals SafeArrayCreateVector, SafeArrayAccessData en SafeArrayUnaccessData om een SAFEARRAY in een VARIANT te maken en in te vullen.

Zie SafeArray-gegevenstypevoor meer informatie over het gegevenstype SAFEARRAY.

In dit C++-voorbeeld wordt een IInkStrokeDisp-, pInkStrokeDispgemaakt in een InkDisp--object, pInk, op basis van een array met puntgegevens.

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

De ondersteunde tekenreeksindeling voor COM is BSTR. Een BSTR heeft een pointer naar een nulgeëindigde tekenreeks, maar bevat ook de lengte van de tekenreeks (in bytes, zonder het eindteken mee te tellen), die wordt opgeslagen in de 4 bytes direct voorafgaand aan het eerste teken van de tekenreeks.

Zie BSTR-gegevenstypevoor meer informatie over BSTR.

In dit C++-voorbeeld ziet u hoe u de factoid instelt in een InkRecognizerContext door gebruik te maken van een 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);
}