Verwenden von IUIAutomationTextRange zum Zugreifen auf und Bearbeiten eines Textbereichs
In diesem Thema wird beschrieben, wie Sie die Eigenschaften und Methoden der IUIAutomationTextRange-Schnittstelle verwenden, um auf den Textinhalt eines textbasierten Steuerelements zuzugreifen und diese zu bearbeiten.
Was ist ein Textbereich?
Das Microsoft Benutzeroberflächenautomatisierung Textobjektmodell basiert auf dem Konzept des Textbereichs. Ein Textbereich ist ein Objekt, das die IUIAutomationTextRange-Schnittstelle verfügbar macht und eine zusammenhängende Textspanne in einem textbasierten Steuerelement darstellt. Jeder Textbereich hat sowohl einen Startendpunkt als auch einen Endendpunkt, und alle Textinhalte zwischen den beiden Endpunkten werden als Teil des Bereichs betrachtet. Ein Textbereich, dessen Start- und Endendpunkt sich an derselben Position befinden, wird als degenerierter (oder leerer) Textbereich bezeichnet. Ein degenerierter Textbereich wird verwendet, um eine bestimmte Position im Text eines Steuerelements zu markieren, z. B. die Position der Texteinfügemarke.
Abrufen von Textbereichsobjekten
Clientanwendungen erfassen Textbereichsobjekte mithilfe der Eigenschaften und Methoden der IUIAutomationTextPattern-Schnittstelle . Die IUIAutomationTextRangePattern::D ocumentRange-Eigenschaft ruft einen Textbereich ab, der den gesamten Textinhalt eines textbasierten Steuerelements darstellt, während andere Methoden Textbereiche abrufen, die einen Teil des Inhalts darstellen, z. B. den ausgewählten Text, den sichtbaren Text oder ein im Text eingebettetes Objekt.
Die Methoden IUIAutomationTextRangePattern::GetVisibleRanges und GetSelection können Arrays von Textbereichsobjekten abrufen. Wenn ein Steuerelement teilweise durch ein überlappende Fenster oder ein anderes Objekt verdeckt wird, gibt GetVisibleRanges ein Array zurück, das für jede teilweise sichtbare Textzeile ein Textbereichsobjekt enthält. Wenn ein textbasiertes Steuerelement die Auswahl mehrerer, nicht zusammenhängender Textspannen unterstützt, gibt GetSelection ein Array zurück, das ein Textbereichsobjekt für jede ausgewählte Spanne enthält.
Mit der IUIAutomationTextRangePattern::RangeFromChild-Methode kann eine Clientanwendung einen Textbereich abrufen, der ein Objekt einschließt, das in den Textinhalt eingebettet ist. Der Client gibt den IUIAutomationElement-Schnittstellenzeiger eines eingebetteten Objekts an, z. B. eines Bilds, einer Tabelle oder eines Hyperlinks, und die Methode gibt einen Textbereich zurück, der das Objekt umschließt. Wenn dem eingebetteten Objekt jedoch kein Text zugeordnet ist, gibt die Methode einen entarteten Textbereich zurück.
Eine Clientanwendung kann die IUIAutomationTextRangePattern::RangeFromPoint-Methode verwenden, um einen Textbereich für den sichtbaren Text oder das eingebettete Objekt abzurufen, der den angegebenen Bildschirmkoordinaten am nächsten ist.
Auswählen von Text in einem Textbereich
Die IUIAutomationTextRange-Schnittstelle enthält eine Reihe von Methoden, mit denen eine Clientanwendung die Auswahl von Text in einem textbasierten Steuerelement steuern kann.
Clientanwendungen können die IUIAutomationTextRange::Select-Methode verwenden, um den Text auszuwählen, der einem Textbereich entspricht, und um die vorherige Auswahl (falls vorhanden) aus dem Textsteuerelement zu entfernen. Das Aufrufen von Select mit einem entarteten Textbereich verschiebt die Einfügemarke an die Position des Textbereichs, ohne Text auszuwählen.
Wenn ein Steuerelement die Auswahl mehrerer, nicht zusammenhängender Textspannen unterstützt, kann ein Client die Methoden IUIAutomationTextRange::AddToSelection und RemoveFromSelection verwenden, um Textbereiche der Auflistung ausgewählter Textbereiche hinzuzufügen und aus dieser zu entfernen. Wenn das Steuerelement jeweils nur einen ausgewählten Textbereich unterstützt, der Auswahlvorgang jedoch zur Auswahl mehrerer nicht zusammenhängender Textbereiche führen würde, gibt die Methode entweder einen E_INVALIDOPERATION Fehler zurück oder erweitert oder schneidet die aktuelle Auswahl ab. Eine Clientanwendung kann ermitteln, ob ein Steuerelement die Auswahl einzelner oder mehrerer Textspannen oder überhaupt keinen unterstützt, indem die IUIAutomationTextPattern::SupportedTextSelection-Eigenschaft überprüft wird.
Wenn ein textbasiertes Steuerelement Texteinfügungen unterstützt, wird beim Aufrufen von IUIAutomationTextRange::AddToSelection oder RemoveFromSelection in einem entarteten Textbereich im Steuerelement die Einfügemarke verschoben, aber kein Text ausgewählt.
Abrufen von Text aus einem Textbereich
Clientanwendungen können die IUIAutomationTextRange::GetText-Methode verwenden, um den Nur-Text eines Textbereichs abzurufen. Der Nur-Text enthält alle Im Quelltext gefundenen Steuerzeichen, z. B. Wagenrückläufe und die Unicode-Markierung von links nach rechts (LRM). Der Nur-Text enthält keine Markuptags wie HTML, die möglicherweise im Quelltext vorhanden sind. Außerdem werden alle Escapecodes im Quelltext in die Nur-Text-Entsprechungen konvertiert. Beispielsweise wird " " in ein einfaches Leerzeichen konvertiert.
Wenn ein eingebettetes Objekt einen Textbereich umfasst, enthält der Nur-Text den inneren Text des Objekts, aber nicht den alternativen Text (die name-Eigenschaft des eingebetteten Objekts). Weitere Informationen finden Sie unter Verfügbarmachen eingebetteter Objekte Benutzeroberflächenautomatisierung.
Die IUIAutomationTextRange::FindText-Methode durchsucht einen Textbereich nach einer bestimmten Zeichenfolge und gibt einen neuen Textbereich zurück, der die Zeichenfolge umfasst.
Abrufen von Textattributen aus einem Textbereich
Textattribute bestimmen den Formatierungsstil des Texts in einem textbasierten Steuerelement und enthalten Dinge wie Vordergrundfarbe, Aufzählungszeichen, Schriftgrad usw. Benutzeroberflächenautomatisierung unterstützt eine Reihe von Textattributen und definiert einen Bezeichner für jedes unterstützte Attribut. Eine Clientanwendung kann einen Textbereich für den Wert eines bestimmten Textattributs abfragen, indem sie einen Attributbezeichner in einem Aufruf der IUIAutomationTextRange::GetAttributeValue-Methode sowie einen Zeiger auf eine VARIANT-Struktur angibt, die den Attributwert empfängt. Ausführliche Informationen zu den einzelnen Textattributen, die Benutzeroberflächenautomatisierung unterstützen, finden Sie unter Textattributebezeichner.
Der von GetAttributeValue abgerufene Wert stellt den Wert des Attributs für den gesamten Textbereich dar. Wenn der gesamte Text im Bereich den gleichen Wert für das angegebene Attribut aufweist, wird dieser Wert von GetAttributeValue zurückgegeben. Wenn der Wert des Attributs jedoch im Textbereich variiert, gibt GetAttributeValue einen IUnknown-Zeiger auf ein statisches Tokenobjekt namens ReservedMixedAttribute-Objekt zurück. Um zu ermitteln, ob der Wert eines Attributs in einem Textbereich variiert, sollte eine Clientanwendung die Ergebnisse von GetAttributeValue mit dem ReservedMixedAttribute-Objekt vergleichen, das aus der IUIAutomation::ReservedMixedAttributeValue-Eigenschaft abgerufen wird.
Ein textbasiertes Steuerelement ist nicht erforderlich, um alle Benutzeroberflächenautomatisierung Textattribute zu unterstützen. Wenn ein Client die IUIAutomationTextRange::GetAttributeValue-Methode aufruft und den Bezeichner eines nicht unterstützten Attributs übergibt, gibt die Methode einen IUnknown-Zeiger auf ein statisches Tokenobjekt namens ReservedNotSupported-Objekt zurück. Um zu ermitteln, ob ein bestimmtes Attribut unterstützt wird, sollte eine Clientanwendung die Ergebnisse von GetAttributeValue mit dem ReservedNotSupported-Objekt vergleichen, das aus der IUIAutomation::ReservedNotSupportedValue-Eigenschaft abgerufen wurde.
Clientanwendungen können die IUIAutomationTextRange::FindAttribute-Methode verwenden, um einen Textbereich nach Text zu durchsuchen, der über ein bestimmtes Textattribut verfügt. Falls gefunden, gibt die Methode einen neuen Textbereich zurück, der den übereinstimmenden Text umfasst. Beachten Sie, dass FindAttribute einen Textbereich für übereinstimmenden Text zurückgibt, auch wenn der Text nicht sichtbar ist.
Abrufen eingebetteter Objekte aus einem Textbereich
Ein Textbereich kann eingebettete Objekte wie Tabellen, Bilder, Hyperlinks usw. enthalten. Eine Clientanwendung kann eine Auflistung aller eingebetteten Objekte in einem Bereich abrufen, indem die IUIAutomationTextRange::GetChildren-Methode aufgerufen wird. Eingebettete Objekte, die sich mit dem Bereich überlappen, aber nicht vollständig von diesem eingeschlossen werden, sind ebenfalls in der Auflistung enthalten. Wenn der Bereich keine eingebetteten Objekte enthält, ruft GetChildren eine leere Auflistung ab.
Obwohl dies vom Anbieter des textbasierten Steuerelements abhängt, gibt die GetChildren-Methode in der Regel keine untergeordneten Elemente der eingebetteten Elemente zurück. Wenn beispielsweise ein Textbereich eine Tabelle mit einer Anzahl untergeordneter Zellen enthält, gibt die GetChildren-Methode in der Regel nur das Tabellenelement und nicht die Zellenelemente zurück.
Aus Leistungs- oder Architekturgründen kann GetChildren möglicherweise keine IUIAutomationElement-Objekte für alle eingebetteten Objekte in einem Textbereich abrufen. Stattdessen gibt der Anbieter möglicherweise eine Auflistung zurück, die virtualisierte Elemente enthält. Weitere Informationen finden Sie unter Arbeiten mit virtualisierten Elementen.
Bearbeiten eines Textbereichs
Die IUIAutomationTextRange-Schnittstelle bietet mehrere Methoden zum Bearbeiten und Navigieren von Textbereichen in einem textbasierten Steuerelement. Die Methoden IUIAutomationTextRange::Move, MoveEndpointByUnit und ExpandToEnclosingUnit verschieben einen Textbereich oder einen seiner Endpunkte um die angegebene Texteinheit, z. B. Zeichen, Wort, Absatz usw. Weitere Informationen finden Sie unter Benutzeroberflächenautomatisierung Texteinheiten.
Trotz ihres Namens erweitert die ExpandToEnclosingUnit-Methode nicht unbedingt einen Textbereich. Stattdessen "normalisiert" es einen Textbereich, indem die Endpunkte so verschoben werden, dass der Bereich die angegebene Texteinheit genau umfasst. Der Bereich wird erweitert, wenn er kleiner als die angegebene Einheit ist, oder verkürzt, wenn er länger als die angegebene Einheit ist. Das folgende Diagramm zeigt, wie ExpandToEnclosingUnit einen Textbereich normalisiert, indem die Endpunkte des Bereichs verschoben werden.
Wenn der Textbereich am Anfang einer Texteinheit beginnt und am Anfang von oder vor der nächsten Texteinheitsgrenze endet, wird der Endendpunkt zur nächsten Texteinheitsgrenze verschoben (siehe 1 und 2 in der vorherigen Abbildung).
Wenn der Textbereich am Anfang einer Texteinheit beginnt und bei oder nach der nächsten Einheitengrenze endet, bleibt der Endendpunkt zurück oder wird nach dem Startendpunkt zur nächsten Einheitsgrenze verschoben (siehe 3 und 4 in der vorherigen Abbildung). Wenn zwischen dem Start- und Endendpunkt mehr als eine Texteinheitsgrenze vorhanden ist, wird der Endendpunkt nach dem Startendpunkt zur nächsten Einheitsgrenze rückwärts verschoben, was zu einem Textbereich mit einer Texteinheit in der Länge führt.
Wenn der Textbereich in der Mitte einer Texteinheit beginnt, wird der Startendpunkt rückwärts an den Anfang der Texteinheit verschoben, und der Endendpunkt wird nach Bedarf nach vorne oder rückwärts zur nächsten Einheitsgrenze nach dem Startendpunkt verschoben (siehe 5 bis 8 in der vorherigen Abbildung).
Wenn die IUIAutomationTextRange::Move-Methode aufgerufen wird, normalisiert der Anbieter den Textbereich um die angegebene Texteinheit. Anschließend verschiebt der Anbieter den Bereich um die angegebene Anzahl von Texteinheiten rückwärts oder vorwärts. Beim Verschieben des Bereichs ignoriert der Anbieter die Grenzen aller eingebetteten Objekte im Text. (Die Einheitsgrenze selbst kann jedoch durch das Vorhandensein eines eingebetteten Objekts beeinflusst werden.) Das folgende Diagramm veranschaulicht, wie die Move-Methode einen Textbereich Einheit für Einheit über eingebettete Objekte und Texteinheitengrenzen verschiebt.
Die IUIAutomationTextRange::MoveEndpointByUnit-Methode verschiebt einen der Endpunkte um die angegebene Texteinheit vorwärts oder rückwärts. Die folgende Abbildung zeigt, wie sich ein Endpunkt vorwärts bewegt.
Die IUIAutomationTextRange::MoveEndpointByRange-Methode ermöglicht es einer Clientanwendung, einen Endpunkt eines Textbereichs auf denselben Speicherort wie den angegebenen Endpunkt eines zweiten Textbereichs festzulegen.
Scrollen eines Textbereichs in die Ansicht
Die IUIAutomationTextRange::ScrollIntoView-Methode scrollt einen Textbereich, sodass der Text im Viewport des textbasierten Steuerelements sichtbar ist. Beim Aufrufen von ScrollIntoView kann ein Client angeben, ob der Text am oberen oder unteren Rand des Viewports ausgerichtet werden soll.
Abrufen des einschließenden Elements eines Textbereichs
Eine Clientanwendung kann die IUIAutomationTextRange::GetEnclosingElement-Methode verwenden, um den IUIAutomation-Schnittstellenzeiger des innersten Elements abzurufen, das einen Textbereich einschließt. Das einschließende Element ist in der Regel der Textanbieter, der den Textbereich bereitstellt. Wenn der Textanbieter jedoch untergeordnete Elemente wie Tabellen oder Hyperlinks unterstützt, kann das einschließende Element ein Nachkomme des Textanbieters sein.
Vergleichen und Klonen von Textbereichen
Die IUIAutomationTextRange-Schnittstelle umfasst zwei Methoden zum Vergleichen von Textbereichen. Die IUIAutomationTextRange::Compare-Methode vergleicht die Anfangs- und Endendpunkte von zwei Textbereichen und gibt TRUE zurück, wenn beide Endpunkte identisch sind. Die IUIAutomationTextRange::CompareEndpoints-Methode vergleicht entweder den Start- oder den Endendpunkt der beiden Bereiche. Der Rückgabewert ist 0, wenn die Endpunkte identisch sind, oder ein positiver oder negativer Wert, der die relativen Positionen der beiden Endpunkte angibt.
Clientanwendungen können die IUIAutomationTextRange::Clone-Methode verwenden, um eine exakte Kopie des Textbereichs zu erstellen. Der neue Textbereich kann unabhängig vom ursprünglichen Textbereich bearbeitet werden.
Abrufen von Anmerkungen
Ein Textbereich kann Anmerkungen enthalten, wenn sie vom textbasierten Steuerelement unterstützt werden. Es gibt viele verschiedene Arten von Anmerkungen. Die UiAutomationClient.h-Headerdatei definiert einen Satz benannter Konstantenwerte, die die Typen von Anmerkungen identifizieren, die Benutzeroberflächenautomatisierung unterstützt. Weitere Informationen finden Sie unter Anmerkungstypbezeichner.
Einige Arten von Anmerkungen werden durch ein Automatisierungselement dargestellt, das das Anmerkungssteuerelementmuster (IUIAutomationAnnotationPattern-Schnittstelle ) unterstützt. Andere Arten von Anmerkungen werden über das TextRange-Steuerelementmuster verfügbar gemacht. Ein Anbieter könnte beispielsweise einen einfachen Rechtschreibfehlerindikator verfügbar machen, indem die IUIAutomationTextRange::GetAttributeValue-Methode ein AnnotationTypes-Textattribut von AnnotationType_SpellingError und einen NULL-Wert für das Textattribut AnnotationObjects zurückgibt.
Abrufen von Anmerkungstypen aus einem Textbereich
Sie können eine Liste der Typen von Anmerkungen abrufen, die in einem Textbereich vorhanden sind, indem Sie die IUIAutomationTextRange::GetAttributeValue-Methode verwenden. Geben Sie beim Aufrufen der Methode eine Textattribute-ID von UIA_AnnotationTypesAttributeId und einen Zeiger auf einen Parameter vom Typ VARIANT an. Wenn die Methode zurückgibt, enthält der VARIANT-Parameter eine Liste von Anmerkungstypbezeichnern, eine für jeden Anmerkungstyp im Textbereich. Weitere Informationen finden Sie unter Anmerkungstypbezeichner.
Abrufen aller Anmerkungen aus einem Textbereich
Um die Anmerkungen aus einem Textbereich abzurufen, rufen Sie die IUIAutomationTextRange::GetAttributeValue-Methode auf, indem Sie eine Textattribut-ID von UIA_AnnotationObjectsAttributeId und einen Zeiger auf einen Parameter vom Typ VARIANT angeben. Wenn die Methode zurückgibt, enthält der VARIANT-Parameter eine IUIAutomationElementArray-Schnittstelle , die ein Array von Automatisierungselementen darstellt, eines für jede Anmerkung im Textbereich. Die IUIAutomationElementArray::Length-Eigenschaft gibt die Anzahl der Elemente im Array an, und die IUIAutomationElementArray::GetElement-Methode ruft die IUIAutomationElement-Schnittstelle für ein bestimmtes Element ab.
Abrufen von Informationen zu einer bestimmten Anmerkung
Um Informationen zu einer bestimmten Anmerkung abzurufen, rufen Sie zuerst die IUIAutomationElement-Schnittstelle für das Anmerkungselement ab, wie im vorherigen Abschnitt beschrieben. Rufen Sie als Nächstes die IUIAutomationAnnotationPattern-Schnittstelle für die Anmerkung ab, indem Sie die IUIAutomationElement::GetCurrentPatternAs-Methode mit einer Steuerelementmuster-ID von UIA_AnnotationPatternId, einem Schnittstellenbezeichner von IID_IUIAutomationAnnotationPattern und der Adresse einer Variablen aufrufen, die den IUIAutomationAnnotation-Zeiger für die Anmerkung empfängt. Fragen Sie die Eigenschaften der IUIAutomationAnnotation-Schnittstelle ab, um den Anmerkungstypnamen und die Typ-ID, den Namen des Anmerkungsautors, das Datum und die Uhrzeit der Anmerkung sowie die IUIAutomationElement-Schnittstelle für das Element abzurufen, das mit Anmerkungen versehen wird.
Abrufen des Anmerkungszieltexts
In der Regel gilt eine Anmerkung für eine Teilmenge des Texts in einem Textbereich. Nachdem Sie die IUIAutomationElement-Schnittstelle für eine Anmerkung abgerufen haben, können Sie die Schnittstelle an die IUIAutomationTextRange2::RangeFromAnnotation-Methode übergeben, um einen Textbereich abzurufen, der den Text enthält, der das Ziel der Anmerkung ist.
Abrufen visueller Stile
Ein Anbieter implementiert das Styles-Steuerelementmuster , um ein UI-Element zu beschreiben, das über eine bestimmte Formatvorlage, eine bestimmte Füllfarbe, ein bestimmtes Füllmuster oder eine bestimmte Form verfügt. Dies ist besonders nützlich, wenn Elemente in einem Dokument beschrieben werden, die häufig über solche Stile verfügen. Solche Stile enthalten häufig Informationen, die für Kunden mit Behinderungen nützlich sind. Beispielsweise können Formatvorlagen eine bestimmte Zeichenfolge als Titel eines Dokuments oder ein bestimmtes Flussdiagrammobjekt als Diamant oder Kreis beschreiben.
Sie können die IUIAutomationTextRange::GetAttributeValue-Methode verwenden, um die Namen und Bezeichner der visuellen Stile abzurufen, die in einem Textbereich verwendet werden. Verwenden Sie das UIA_StyleNameAttributeId Textattribut, um die Formatvorlagennamen abzurufen, und UIA_StyleIdAttributeId , um die Formatbezeichner abzurufen.
Ein textbasiertes Steuerelement, das visuelle Stile unterstützt, kann das Stil-Steuerelementmuster implementieren, damit Clients auf Informationen zu einer visuellen Formatvorlage zugreifen können, die vom Steuerelement verwendet wird. Clients greifen über die IUIAutomationStylesPattern-Schnittstelle auf das Steuerelementmuster Styles zu. Sie können diese Schnittstelle abrufen, indem Sie die Methode IUIAutomationElement::GetCurrentPattern oder GetCurrentPatternAs aufrufen und UIA_StylesPatternId als Steuerelementmusterbezeichner angeben.
Die IUIAutomationStylesPattern-Schnittstelle enthält Eigenschaften und Methoden, die die folgenden Informationen zu einem visuellen Stil bereitstellen:
- Der Name des visuellen Stils, z. B. "Normal" oder "Überschrift 1".
- Der Bezeichner des visuellen Stils. Weitere Informationen finden Sie unter Formatbezeichner.
- Die Farbe, die zum Ausfüllen des textbasierten Steuerelements verwendet wird.
- Die Farbe des Musters, das zum Ausfüllen des textbasierten Steuerelements verwendet wird.
- Die Form des textbasierten Steuerelements.
- Die erweiterten Eigenschaften; d. h. eine Liste steuerelementspezifischer Formatvorlagennamen und -werte.
Aufrufen von Kontextmenüs aus Textbereichen
Ab Windows 8.1 können Textbereiche die IUIAutomationTextRange2-Schnittstelle unterstützen. Diese Schnittstelle unterstützt die ShowContextMenu-Methode . Sie können diese Methode aufrufen, um ein beliebiges Kontextmenü aufzurufen, das einem Textbereich zugeordnet ist. Das Szenario hierfür ist die automatische Korrektur von Textbereichen oder die Auswahl von IME-Kandidaten. In diesen Fällen wird ein Kontextmenü angezeigt, das die Benutzerinteraktion unterstützt.
Zugehörige Themen