Uso de la biblioteca COM

La referencia de la biblioteca administrada de pc tableta ahora se puede encontrar en la sección de referencia normal de la biblioteca de clases del SDK de Windows Vista. Proporciona un modelo de objetos para Microsoft Visual C++. La mayoría de los objetos de la biblioteca COM son idénticos a los que se encuentran en la API administrada de Tablet PC.

Sin embargo, la API COM contiene algunos miembros además de los que se encuentran en la API administrada debido a las diferencias entre el entorno estándar de Microsoft Win32 y el entorno del Kit de desarrollo de Microsoft .NET Framework (SDK). Por ejemplo, los objetos InkRectangle e InkTransform se usan en COM, pero FrameworkSDK proporciona una implementación nativa para la clase InkRectangle y la clase InkTransform que elimina la necesidad de estos objetos en la API administrada de la plataforma tablet PC.

Nota

Los objetos de la API COM y los controles de entrada de lápiz no están diseñados para su uso en Active Server Pages (ASP).

 

Trabajar con colecciones

Si pasa un valor NULL como índice a cualquiera de los objetos de colección de la biblioteca COM, recibirá el primer elemento de la colección porque estos valores de argumento se convierten en 0 cuando se realiza la llamada.

La propiedad _NewEnum está marcada como restringida en la definición del lenguaje de definición de interfaz (IDL) para las interfaces de colección.

En C++, use un bucle para recorrer en For... iteración una colección obteniendo primero la longitud de la colección. En el ejemplo siguiente se muestra cómo recorrer en iteración los trazos de un 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

Si pasa VT_EMPTY o VT_NULL como índice a cualquiera de los objetos de colección de la biblioteca COM, recibirá el primer elemento de la colección porque estos valores de argumento se convierten en 0 cuando se realiza la llamada.

Uso de IDispatch

Para aumentar el rendimiento, la interfaz de programación de aplicaciones COM (API) de plataforma tablet PC no admite llamadas IDispatchImpl::Invoke con una estructura DISPPARAMS con argumentos con nombre. IDispatchImpl::GetIDsOfNames Tampoco se admite . En su lugar, llame a Invoke con los DISPID proporcionados en los encabezados del SDK.

Esperando eventos

El entorno de tablet PC es multiproceso. Consulte la documentación de COM para la multiproceso.

Compatibilidad con agregaciones

Se ha probado la agregación solo para el control InkEdit , el control InkPicture , el objeto InkDisp y el objeto InkOverlay . No se ha probado la agregación para otros controles y objetos de la biblioteca.

C++

El uso del SDK de Tablet PC en C++ requiere el uso de algunos conceptos COM, como VARIANT, SAFEARRAY y BSTR. En esta sección se describe cómo usarlos.

VARIANT y SAFEARRAY

La estructura VARIANT se usa para la comunicación entre objetos COM. Básicamente, la estructura VARIANT es un contenedor para una unión grande que contiene muchos tipos de datos.

El valor del primer miembro de la estructura, vt, describe cuál de los miembros de la unión es válido. Cuando reciba información en una estructura VARIANT, compruebe el miembro vt para averiguar qué miembro contiene datos válidos. De forma similar, al enviar información mediante una estructura VARIANT, establezca siempre vt para reflejar el miembro de unión que contiene la información.

Antes de usar la estructura , inicialícelo llamando a la función COM VariantInit. Cuando termine con la estructura , desactive antes de que se libere la memoria que contiene variant llamando a VariantClear.

Para obtener más información sobre la estructura VARIANT, vea VARIANT y VARIANTARG Data Types.

La estructura SAFEARRAY se proporciona como una manera de trabajar de forma segura con matrices en COM. El campo parray de VARIANT es un puntero a SAFEARRAY. Use funciones como SafeArrayCreateVector, SafeArrayAccessData y SafeArrayUnaccessData para crear y rellenar SAFEARRAY en un VARIANT.

Para obtener más información sobre el tipo de datos SAFEARRAY, consulte SafeArray Data Type.

En este ejemplo de C++ se crea un IInkStrokeDisp , pInkStrokeDisp, en un objeto InkDisp , pInk, a partir de una matriz de datos de 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

El formato de cadena admitido para COM es BSTR. Un BSTR tiene un puntero a una cadena terminada en cero, pero también contiene la longitud de la cadena (en bytes, sin contar el terminador), que se almacena en los 4 bytes inmediatamente anteriores al primer carácter de la cadena.

Para obtener más información sobre BSTR, vea Tipo de datos BSTR.

En este ejemplo de C++ se muestra cómo establecer el factoid en inkRecognizerContext mediante 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);
}