Verwenden der COM-Bibliothek

Die Referenz zu der verwalteten Tablet PC-Bibliothek finden Sie jetzt im abschnitt "Reguläre Referenz zur Windows Vista SDK-Klassenbibliothek". Es stellt ein Objektmodell für Microsoft Visual C++ bereit. Die meisten Objekte in der COM-Bibliothek sind mit denen in der verwalteten Tablet PC-API identisch.

Die COM-API enthält jedoch aufgrund von Unterschieden zwischen der Microsoft Win32-Standardumgebung und der Umgebung des Microsoft .NET FrameworkSoftware Development Kit (SDK) zusätzlich zu den Mitgliedern der verwalteten API. Beispielsweise werden die Objekte InkRectangle und InkTransform in COM verwendet, aber das FrameworkSDK bietet eine native Implementierung für die InkRectangle-Klasse und die InkTransform-Klasse , die die Notwendigkeit dieser Objekte in der verwalteten API der Tablet PC-Plattform beseitigt.

Hinweis

Die Objekte in der COM-API und die Freihandsteuerelemente sind nicht für die Verwendung in Active Server Pages (ASP) konzipiert.

 

Arbeiten mit Sammlungen

Wenn Sie einen NULL-Wert als Index an eines der Auflistungsobjekte in der COM-Bibliothek übergeben, erhalten Sie das erste Element in der Auflistung, da diese Argumentwerte beim Aufruf auf 0 geerct werden.

Die _NewEnum-Eigenschaft ist in der IDL-Definition (Interface Definition Language) für die Auflistungsschnittstellen als eingeschränkt gekennzeichnet.

Verwenden Sie in C++ eine For... Schleife, um eine Auflistung zu durchlaufen, indem Sie zuerst die Länge der Sammlung abrufen. Das folgende Beispiel zeigt, wie Sie die Striche eines InkDisp-Objekts durchlaufen. 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
              // ...
            }
        }
    }
}

Parameter

Wenn Sie VT_EMPTY oder VT_NULL als Index an eines der Auflistungsobjekte in der COM-Bibliothek übergeben, erhalten Sie das erste Element in der Auflistung, da diese Argumentwerte beim Aufruf auf 0 geerct werden.

Verwenden von IDispatch

Um die Leistung zu erhöhen, unterstützt die Tablet PC Platform COM-Anwendungsprogrammierschnittstelle (API) das Aufrufen IDispatchImpl::Invoke mit einer DISPPARAMS-Struktur mit benannten Argumenten nicht. Der IDispatchImpl::GetIDsOfNames wird auch nicht unterstützt. Rufen Sie Invoke stattdessen mit den DISPIDs auf, die in den SDK-Headern angegeben sind.

Warten auf Ereignisse

Die Tablet-PC-Umgebung ist multithreaded. Informationen zum Multithreading finden Sie in der COM-Dokumentation.

Unterstützung für Aggregation

Aggregation wurde nur für das InkEdit-Steuerelement , das InkPicture-Steuerelement , das InkDisp-Objekt und das InkOverlay-Objekt getestet. Aggregation wurde nicht für andere Steuerelemente und Objekte in der Bibliothek getestet.

C++

Die Verwendung des Tablet PC SDK in C++ erfordert die Verwendung einiger COM-Konzepte, z. B. VARIANT, SAFEARRAY und BSTR. In diesem Abschnitt wird beschrieben, wie sie verwendet werden.

VARIANT und SAFEARRAY

Die VARIANT-Struktur wird für die Kommunikation zwischen COM-Objekten verwendet. Im Wesentlichen ist die VARIANT-Struktur ein Container für eine große Union, die viele Arten von Daten enthält.

Der Wert im ersten Element der Struktur, vt, beschreibt, welches der Gewerkschaftsmitglieder gültig ist. Wenn Sie Informationen in einer VARIANT-Struktur erhalten, überprüfen Sie das vt-Element, um herauszufinden, welches Element gültige Daten enthält. Legen Sie beim Senden von Informationen mithilfe einer VARIANT-Struktur immer vt so fest, dass das Unionmitglied die Informationen enthält.

Bevor Sie die Struktur verwenden, initialisieren Sie sie, indem Sie die Com-Funktion VariantInit aufrufen. Wenn Sie mit der Struktur fertig sind, löschen Sie sie, bevor der Arbeitsspeicher, der den VARIANT enthält, freigegeben wird, indem Sie VariantClear aufrufen.

Weitere Informationen zur VARIANT-Struktur finden Sie unter VARIANT- und VARIANTARG-Datentypen.

Die SAFEARRAY-Struktur wird als Möglichkeit zum sicheren Arbeiten mit Arrays in COM bereitgestellt. Das Parrayfeld des VARIANT ist ein Zeiger auf ein SAFEARRAY. Verwenden Sie Funktionen wie SafeArrayCreateVector, SafeArrayAccessData und SafeArrayUnaccessData, um ein SAFEARRAY in einem VARIANT-Objekt zu erstellen und zu füllen.

Weitere Informationen zum SAFEARRAY-Datentyp finden Sie unter SafeArray-Datentyp.

In diesem C++-Beispiel wird aus einem Array von Punktdaten ein IInkStrokeDisppInkStrokeDisp, , in einem InkDisp-Objekt erstellt pInk.

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

Das unterstützte Zeichenfolgenformat für COM ist BSTR. Ein BSTR hat einen Zeiger auf eine Zeichenfolge mit Null, enthält aber auch die Länge der Zeichenfolge (in Bytes, ohne den Abschlussator zu zählen), die in den 4 Bytes direkt vor dem ersten Zeichen der Zeichenfolge gespeichert wird.

Weitere Informationen zu BSTR finden Sie unter BSTR-Datentyp.

In diesem C++-Beispiel wird gezeigt, wie das Factoid für einen InkRecognizerContext mithilfe eines BSTR festgelegt wird.

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);
}