Wzorzec kontrolki adnotacji

Opisuje wytyczne i konwencje implementowania IAnnotationProvider, w tym informacje o właściwościach i metodach. Wzorzec kontrolki adnotacji służy do uwidaczniania właściwości adnotacji w dokumencie.

Przykładem jest dymek komentarza, który znajduje się na marginesie dokumentu i jest połączony z tekstem dokumentu lub komórką arkusza kalkulacyjnego.

Na poniższej ilustracji przedstawiono przykład adnotacji. Aby zapoznać się z przykładami kontrolek implementujących ten wzorzec kontrolki, zobacz typy kontrolek i obsługiwane wzorce kontrolek.

Ten temat zawiera następujące sekcje.

• wytyczne i konwencje implementacji
• wymagane elementy członkowskie IAnnotationProvider
• Tematy pokrewne

Wytyczne i konwencje implementacji

Podczas implementowania wzorca kontrolki adnotacji należy pamiętać o następujących wytycznych i konwencjach:

• Istnieje wiele różnych rodzajów adnotacji. Plik nagłówka UIAutomationClient.h definiuje zestaw nazwanych wartości stałych, które identyfikują typy adnotacji obsługiwane przez usługę Microsoft UI Automation. Aby uzyskać więcej informacji, zobacz identyfikatory typów adnotacji .
• Jeśli używasz AnnotationType_Unknown, musisz zaimplementować właściwość IAnnotationProvider::AnnotationTypeName, aby umożliwić klientom odnajdywanie nazwy typu adnotacji. Nie trzeba implementować AnnotationTypeName dla standardowego typu adnotacji, ponieważ usługa Automatyzacja interfejsu użytkownika udostępnia nazwę domyślną, ale można ją zaimplementować, jeśli musisz zastąpić nazwę domyślną.
• Właściwość IAnnotationProvider::Author jest opcjonalna.
• Właściwość IAnnotationProvider::D ateTime jest opcjonalna.
• Właściwość IAnnotationProvider::Target jest wymagana, ponieważ łączy adnotację z elementem interfejsu użytkownika, umożliwiając klientowi przechodzenie z adnotacji z powrotem do elementu interfejsu użytkownika, do którego odwołuje się adnotacja.
• Ponieważ adnotacje mogą przyjmować wiele różnych formularzy, interfejs IAnnotationProvidernie definiuje właściwości do przechowywania wartości ani tekstu adnotacji. Prosta adnotacja powinna uwidocznić interfejs IValueProvider, a właściwość IValueProvider::Value powinna zwrócić wartość tylko do odczytu określającą tekst adnotacji. Bogatsza adnotacja powinna uwidocznić interfejs ITextProvider, aby udostępnić klientom bardziej rozbudowany tekst.
• Nawigowanie z elementu interfejsu użytkownika do adnotacji od elementu zależy od rodzaju elementu, który jest adnotacją, w następujący sposób:
  • W przypadku komórek arkusza kalkulacyjnego zaimplementuj metodę ISpreadsheetItemProvider::GetAnnotationObjects, aby odwołać się do adnotacji.
  • W przypadku zawartości tekstowej zaimplementuj atrybut tekstowy AnnotationObjects w interfejsie ITextRangeProvider, aby odwołać się do adnotacji.
• Niektóre rodzaje adnotacji nie wymagają pełnej implementacji interfejsu IAnnotationProvider. Na przykład prosty wskaźnik błędu pisowni może być reprezentowany przez użycie interfejsu ITextRangeProvider zwraca atrybut tekstowy AnnotationTypes atrybutu tekstowego AnnotationType_SpellingErrororaz wartość null atrybutu AnnotationObjects atrybutu tekstowego.
• Może być przydatne zaimplementowanie interfejsu IAnnotationProvider w elemecie interfejsu użytkownika, który nie jest widoczny. Można na przykład utworzyć nieoznaczniający element automatyzacji interfejsu użytkownika, który implementuje IAnnotationProvider w celu udostępnienia rozszerzonych informacji o błędzie gramatycznym.
• Adnotacje w kontrolce opartej na tekście mogą być złożone, jeśli kontrolka zawiera nakładające się komentarze. Skorzystaj z poniższych wskazówek, aby obsługiwać złożone adnotacje:
  • Zakres tekstu bez adnotacji powinien zwracać pustą tablicę dla atrybutu tekstowego AnnotationTypes oraz pustą tablicę atrybutu tekstowego AnnotationObjects.
  • Zakres tekstu z jedną adnotacją powinien zwrócić tablicę jednej wartości całkowitej dla atrybutu AnnotationTypes atrybutu tekstowego i tablicy jednego atrybutu IRawElementProviderSimple dla atrybutu AnnotationObjects atrybutu tekstowego.
  • Zakres tekstu z wieloma adnotacjami powinien zwrócić tablicę wielu wartości całkowitych dla atrybutu AnnotationTypes atrybutu tekstowego i tablicy pasującej liczby interfejsów IRawElementProviderSimple dla atrybutu tekstowegoAnnotationObjects.
  • Zakres tekstu o różnych adnotacjach, takich jak zakres z tekstem z adnotacjami i bez adnotacji, powinien zwrócić właściwość ReservedMixedAttributeValue zarówno dla annotationTypes, jak i AnnotationObjects. Klient odbierający tę odpowiedź może rozdzielić zakres tekstu, aby znaleźć, gdzie zaczynają się i kończą adnotacje.

Wymagane elementy członkowskie IAnnotationProvider

Następujące właściwości są wymagane do zaimplementowania interfejsu IAnnotationProvider.

Ten wzorzec kontrolki nie ma skojarzonych zdarzeń.

Tematy pokrewne

typów kontrolek i ich obsługiwanych wzorców kontrolek

Wzorce kontrolek automatyzacji interfejsu użytkownika — omówienie

Omówienie drzewa automatyzacji interfejsu użytkownika