Modello di controllo annotazione

Descrive linee guida e convenzioni per l'implementazione di IAnnotationProvider, incluse informazioni sulle proprietà e sui metodi. Il modello di controllo Annotazione viene usato per esporre le proprietà di un'annotazione in un documento.

Un esempio è un palloncino di commento che si trova nel margine di un documento ed è connesso a un testo del documento o a una cella del foglio di calcolo.

La figura seguente mostra un esempio di annotazione. Per esempi di controlli che implementano questo modello di controllo, vedere Tipi di controllo e modelli di controllo supportati.

In questo argomento sono contenute le sezioni seguenti.

• Linee guida e convenzioni di implementazione
• Membri obbligatori per IAnnotationProvider
• Argomenti correlati

Linee guida e convenzioni di implementazione

Quando si implementa il modello di controllo annotazione , prendere nota delle linee guida e delle convenzioni seguenti:

• Esistono molti tipi diversi di annotazioni. Il file di intestazione UIAutomationClient.h definisce un set di valori costanti denominati che identificano i tipi di annotazioni supportate da Microsoft Automazione interfaccia utente. Per altre informazioni, vedere Identificatori di tipo di annotazione.
• Se si usa AnnotationType_Unknown, è necessario implementare la proprietà IAnnotationProvider::AnnotationTypeName per consentire ai client di individuare il nome del tipo di annotazione. Non è necessario implementare AnnotationTypeName per un tipo di annotazione standard perché Automazione interfaccia utente fornisce un nome predefinito, ma è possibile implementarlo se è necessario eseguire l'override del nome predefinito.
• La proprietà IAnnotationProvider::Author è facoltativa.
• La proprietà IAnnotationProvider::D ateTime è facoltativa.
• La proprietà IAnnotationProvider::Target è necessaria perché collega un'annotazione a un elemento dell'interfaccia utente, consentendo a un client di passare dall'annotazione all'elemento dell'interfaccia utente a cui fa riferimento l'annotazione.
• Poiché le annotazioni possono accettare molte forme diverse, l'interfaccia IAnnotationProvider non definisce una proprietà per archiviare il valore o il testo di un'annotazione. Una semplice annotazione deve esporre l'interfaccia IValueProvider e la proprietà IValueProvider::Value deve restituire un valore di sola lettura che specifica il testo dell'annotazione. Un'annotazione più ricca deve esporre l'interfaccia ITextProvider per fornire testo più avanzato ai client.
• Lo spostamento da un elemento dell'interfaccia utente a un'annotazione sull'elemento dipende dal tipo di elemento annotato, come indicato di seguito:
  • Per le celle del foglio di calcolo, implementare il metodo ISpreadsheetItemProvider::GetAnnotationObjects per fare riferimento all'annotazione.
  • Per il contenuto testuale, implementare l'attributo di testo AnnotationObjects nell'interfaccia ITextRangeProvider per fare riferimento all'annotazione.
• Alcuni tipi di annotazioni non richiedono un'implementazione completa dell'interfaccia IAnnotationProvider . Ad esempio, un semplice indicatore di errore ortografico può essere rappresentato dalla presenza dell'interfaccia ITextRangeProvider di restituire un attributo di testo AnnotationTypes di AnnotationType_SpellingError e un valore Null per l'attributo di testo AnnotationObjects .
• Può essere utile implementare l'interfaccia IAnnotationProvider in un elemento dell'interfaccia utente non visibile. Ad esempio, è possibile creare un elemento Automazione interfaccia utente non visibile che implementa IAnnotationProvider per fornire informazioni estese su un errore di grammatica.
• Le annotazioni in un controllo basato su testo possono essere complesse se il controllo contiene commenti sovrapposti. Usare le linee guida seguenti per gestire annotazioni complesse:
  • Un intervallo di testo senza annotazioni deve restituire una matrice vuota per l'attributo di testo AnnotationTypes e una matrice vuota per l'attributo di testo AnnotationObjects .
  • Un intervallo di testo con un'annotazione deve restituire una matrice di un valore intero per l'attributo di testo AnnotationTypes e una matrice di un'interfaccia IRawElementProviderSimple per l'attributo di testo AnnotationObjects .
  • Un intervallo di testo con più annotazioni deve restituire una matrice di più valori integer per l'attributo di testo AnnotationTypes e una matrice di un numero corrispondente di interfacce IRawElementProviderSimple per l'attributo di testo AnnotationObjects .
  • Un intervallo di testo con annotazioni variabili, ad esempio un intervallo con testo annotato e non annotato, deve restituire la proprietà ReservedMixedAttributeValue per AnnotationTypes e AnnotationObjects. Un client che riceve questa risposta può suddividere l'intervallo di testo per trovare dove iniziano e terminano le annotazioni.

Membri obbligatori per IAnnotationProvider

Per implementare l'interfaccia IAnnotationProvider sono necessarie le proprietà seguenti.

Questo pattern di controllo non è associato a eventi.

Argomenti correlati

Tipi di controllo e modelli di controllo supportati

Cenni preliminari sui pattern di controllo per l'automazione interfaccia utente

Panoramica dell'albero di automazione dell'interfaccia utente