Patrón de control de anotación

Describe instrucciones y convenciones para implementar IAnnotationProvider, incluida la información sobre las propiedades y los métodos. El patrón de control Annotation se usa para exponer las propiedades de una anotación en un documento.

Un ejemplo es un globo de comentarios que está en el margen de un documento y está conectado a algún texto de documento o a una celda de hoja de cálculo.

En la ilustración siguiente se muestra un ejemplo de una anotación. Para obtener ejemplos de controles que implementan este patrón de control, vea Tipos de control y Sus patrones de control admitidos.

En este tema se incluyen las siguientes secciones.

• Directrices y convenciones de implementación
• Miembros necesarios para IAnnotationProvider
• Temas relacionados

Directrices y convenciones de implementación

Al implementar el patrón de control Annotation , tenga en cuenta las siguientes directrices y convenciones:

• Hay muchos tipos diferentes de anotaciones. El archivo de encabezado UIAutomationClient.h define un conjunto de valores constantes con nombre que identifican los tipos de anotaciones que admite Microsoft Automatización de la interfaz de usuario. Para obtener más información, vea Identificadores de tipo de anotación.
• Si usa AnnotationType_Unknown, debe implementar la propiedad IAnnotationProvider::AnnotationTypeName para permitir que los clientes detecten el nombre del tipo de anotación. No es necesario implementar AnnotationTypeName para un tipo de anotación estándar porque Automatización de la interfaz de usuario proporciona un nombre predeterminado, pero puede implementarlo si necesita invalidar el nombre predeterminado.
• La propiedad IAnnotationProvider::Author es opcional.
• La propiedad IAnnotationProvider::D ateTime es opcional.
• La propiedad IAnnotationProvider::Target es necesaria porque vincula una anotación a un elemento de interfaz de usuario, lo que permite a un cliente navegar desde la anotación de nuevo al elemento de interfaz de usuario al que hace referencia la anotación.
• Dado que las anotaciones pueden tener muchas formas diferentes, la interfaz IAnnotationProvider no define una propiedad para almacenar el valor o el texto de una anotación. Una anotación simple debe exponer la interfaz IValueProvider y la propiedad IValueProvider::Value debe devolver un valor de solo lectura que especifique el texto de la anotación. Una anotación más completa debe exponer la interfaz ITextProvider para proporcionar texto más completo a los clientes.
• Navegar desde un elemento de interfaz de usuario a una anotación del elemento depende del tipo de elemento que se anota, como se indica a continuación:
  • Para las celdas de hoja de cálculo, implemente el método ISpreadsheetItemProvider::GetAnnotationObjects para hacer referencia a la anotación.
  • Para el contenido textual, implemente el atributo de texto AnnotationObjects en la interfaz ITextRangeProvider para hacer referencia a la anotación.
• Algunos tipos de anotaciones no requieren una implementación completa de la interfaz IAnnotationProvider . Por ejemplo, un indicador simple de error ortográfico podría representarse haciendo que la interfaz ITextRangeProvider devuelva un atributo de texto AnnotationTypes de AnnotationType_SpellingError y un valor NULL para el atributo de texto AnnotationObjects .
• Puede ser útil implementar la interfaz IAnnotationProvider en un elemento de interfaz de usuario que no está visible. Por ejemplo, podría crear un elemento Automatización de la interfaz de usuario no visible que implemente IAnnotationProvider para proporcionar información extendida sobre un error gramatical.
• Las anotaciones de un control basado en texto pueden ser complejas si el control contiene comentarios superpuestos. Use las instrucciones siguientes para controlar anotaciones complejas:
  • Un intervalo de texto sin anotaciones debe devolver una matriz vacía para el atributo de texto AnnotationTypes y una matriz vacía para el atributo de texto AnnotationObjects .
  • Un intervalo de texto con una anotación debe devolver una matriz de un valor entero para el atributo de texto AnnotationTypes y una matriz de una interfaz IRawElementProviderSimple para el atributo de texto AnnotationObjects .
  • Un intervalo de texto con varias anotaciones debe devolver una matriz de varios valores enteros para el atributo de texto AnnotationTypes y una matriz de un número coincidente de interfaces IRawElementProviderSimple para el atributo de texto AnnotationObjects .
  • Un intervalo de texto con anotaciones variables, como un intervalo con texto anotado y no anotado, debe devolver la propiedad ReservedMixedAttributeValue para AnnotationTypes y AnnotationObjects. Un cliente que recibe esta respuesta puede subdividir el intervalo de texto para buscar dónde comienzan y terminan las anotaciones.

Miembros necesarios para IAnnotationProvider

Las siguientes propiedades son necesarias para implementar la interfaz IAnnotationProvider .

Miembros requeridos	Tipo de miembro	Notas
AnnotationTypeId	Propiedad	Ninguno.
AnnotationTypeName	Propiedad	Ninguno.
Autor	Propiedad	Ninguno.
Datetime	Propiedad	Ninguno.
Destino	Propiedad	Ninguno.

 

Este patrón de control no tiene eventos asociados.

Temas relacionados

Tipos de control y sus patrones de control admitidos

Información general acerca de los patrones de control de UI Automation

Información general sobre el árbol de la UI Automation