Besturingselementpatronen voor tekst en tekstbereik

Beschrijft richtlijnen en conventies voor het implementeren van ITextProvider, ITextProvider2en ITextRangeProvider, inclusief informatie over eigenschappen en methoden. Met het besturingspatroon Text kunnen toepassingen en besturingselementen een eenvoudig tekstobjectmodel beschikbaar maken, zodat clients tekstuele inhoud, tekstkenmerken en ingesloten objecten kunnen ophalen uit besturingselementen op basis van tekst.

Ter ondersteuning van het besturingspatroon Text implementeert u de interfaces ITextProvider en ITextProvider2. Besturingstypen die ondersteuning moeten bieden voor het besturingselement Text zijn onder andere de besturingstypen Bewerken en Document en elk ander besturingselementtype waarmee de gebruiker tekst kan invoeren of alleen-lezen tekst kan selecteren.

Het Text-besturingspatroon kan worden gebruikt met andere Besturingspatronen van Microsoft UI Automation om verschillende typen ingesloten objecten in de tekst te ondersteunen, waaronder tabellen, hyperlinks en opdrachtknoppen.

De interfaces ITextProvider en ITextProvider2 bevatten een aantal methoden voor het verkrijgen van tekstbereiken. Een tekstbereik is een object dat een aaneengesloten reeks tekst( of meerdere, niet-aaneengesloten tekstbereiken) in een tekstcontainer vertegenwoordigt. Een ITextProvider methode verkrijgt een tekstbereik dat het hele document vertegenwoordigt, terwijl anderen tekstbereiken verkrijgen die een deel van het document vertegenwoordigen, zoals de geselecteerde tekst, de zichtbare tekst of een object dat is ingesloten in de tekst.

Een tekstbereikobject wordt vertegenwoordigd door het TextRange-besturingspatroon, dat wordt geïmplementeerd via de interface van ITextRangeProvider. Het TextRange controlepatroon biedt methoden en eigenschappen die worden gebruikt om informatie over de tekst in het bereik weer te geven, de eindpunten van het bereik te verplaatsen, tekst te selecteren of deselecteren, het bereik in beeld te schuiven, enzovoort.

Zie voor meer informatie over de Text en TextRange-besturingspatronen UI Automation-ondersteuning voor tekstuele inhoud.

Vanaf Windows 8.1-providers kunnen de ITextRangeProvider2-interface implementeren. Hiermee kunt u contextmenu's aanroepen die zijn gekoppeld aan een tekstbereik. Dit ondersteunt scenario's zoals tekst autocorrectie of IME-kandidaatselectie (Input Method Editor).

Dit onderwerp bevat de volgende secties.

• richtlijnen en conventies voor de tenuitvoerlegging
• Vereiste leden voor ITextProvider-
• Vereiste leden voor ITextRangeProvider-
• ondersteunende tekstbereiken
  • een tekstbereik bewerken op teksteenheid
  • Tekst selecteren in een tekstbereik
  • tekst ophalen uit een tekstbereik
  • ShowContextMenu implementeren
• Interoperabiliteit met de System Caret-
• Verwante onderwerpen

Implementatierichtlijnen en conventies

Let op de volgende richtlijnen en conventies bij het implementeren van het Text-besturingspatroon:

• Elk besturingselement waarmee toegang tot tekst mogelijk is (bijvoorbeeld het invoeren van tekst of het selecteren van alleen-lezen tekst) moet ondersteuning bieden voor het tekst--besturingspatroon.
• Het besturingselement Text kan worden gebruikt met elk UI-element dat tekst presenteert, zelfs een statisch label op een standaardknop. Het is echter niet vereist voor statische tekstbesturingselementen die niet kunnen worden geselecteerd of geen invoegpositie hebben.
• Om ervoor te zorgen dat tekst volledig toegankelijk is, moeten besturingselementen die ITextProvider- implementeren, ook de IValueProvider interface ondersteunen. IValueProvider vormt een aanvulling op ITextProvider- door een programmatische manier te bieden om de tekst te wijzigen. Het biedt ook meer compatibiliteit met clienttoepassingen voor ondersteunende technologie, waaronder toepassingen op basis van verouderde technologieën zoals Microsoft Active Accessibility. Wanneer beide besturingspatronen worden geïmplementeerd, zijn de TextChanged gebeurtenis (UIA_Text_TextChangedEventId) en AutomationPropertyChanged gebeurtenis (UIA_AutomationPropertyChangedEventId) equivalent voor de eigenschap Value (UIA_ValueValuePropertyId). Beide gebeurtenissen moeten worden ondersteund.
• Het besturingselement Text ondersteunt slechts één stroom tekst en één viewport per besturingselement. Als de toepassing meerdere weergaven van het document in deelvensters biedt, moet elke weergave (besturingselement) ITextProvider onafhankelijk ondersteunen.
• De methode ITextProvider::GetSelection retourneert mogelijk één tekstbereik dat de geselecteerde tekst vertegenwoordigt. Als een besturingselement ondersteuning biedt voor de selectie van meerdere, niet-aaneengesloten tekstbereiken, moet de methode GetSelection een matrix retourneren die één ITextRangeProvider interface bevat voor elke geselecteerde tekstspanne.
• Het besturingselement Text vertegenwoordigt de invoegpositie als een ontaard (leeg) tekstbereik. De methode ITextProvider::GetSelection moet een degenereren tekstbereik retourneren wanneer de invoegpositie bestaat en er geen tekst is geselecteerd. Zie Interoperability with the System Caretvoor meer informatie.
• De methode ITextProvider::GetVisibleRanges retourneert mogelijk één tekstbereik als een aaneengesloten tekstbereik zichtbaar is in de viewport of een matrix met niet-aaneengesloten tekstbereiken retourneert die meerdere, gedeeltelijk zichtbare tekstregels vertegenwoordigen.
• De methode ITextProvider::RangeFromChild moet een degenerate bereik retourneren als het onderliggende element geen tekst bevat. Omdat een ingesloten object tekst kan bevatten, retourneert de methode RangeFromChild mogelijk niet altijd een degenererend tekstbereik. Zie How UI Automation Embedded Objectsbeschikbaar maakt voor meer informatie.
• De methode ITextProvider::RangeFromPoint voert hittests uit in het documentgebied met behulp van de opgegeven schermcoördinaten. Het resulterende tekstbereik moet consistent zijn met de invoegpositie of selectie die het resultaat is van het klikken op de locatie op de opgegeven schermcoördinaten. Als een afbeelding zich bijvoorbeeld op de opgegeven schermcoördinaten bevindt, moet het resulterende tekstbereik hetzelfde zijn als het tekstbereik dat de methode ITextProvider::RangeFromChild voor de afbeelding zou verkrijgen. Als een clienttoepassing een tekstbereik aanvraagt voor de locatie in het midden van de systeemzorg (de invoegpositie), moet het resulterende tekstbereik hetzelfde zijn als de locatie van de systeemzorg.
• De eigenschap ITextProvider::D ocumentRange moet altijd een tekstbereik bevatten dat alle tekst bevat die wordt ondersteund door de bijbehorende ITextProvider-implementatie.
• De gebeurtenis UIA_Text_TextChangedEventId moet worden gegenereerd nadat er tekstwijziging plaatsvindt, zelfs als de wijziging niet zichtbaar is in de viewport. De provider moet bijvoorbeeld de gebeurtenis genereren, zelfs als de gebruiker exact dezelfde tekst over de geselecteerde tekst plakt.
• De UIA_Text_TextSelectionChangedEventId moet worden verhoogd wanneer de selectie van tekst verandert of wanneer de invoegpositie (caret) tussen de tekst wordt verplaatst.

Let bij het implementeren van het patroon TextRange op de volgende richtlijnen en conventies:

• Alle methoden van het TextRange-besturingspatroon moeten tekstbewerkingen uitvoeren, ongeacht de zichtbaarheidsstatus van de tekst. De zichtbaarheid van een tekstbereik kan altijd worden bepaald door een query uit te voeren op de IsHidden tekstkenmerk (UIA_IsHiddenAttributeId).
• Indien mogelijk moet een provider ervoor zorgen dat tekstwijzigingen, zoals verwijderingen, invoegingen en verplaatsingen, worden doorgevoerd in de bijbehorende tekstbereikobjecten (exemplaren van ITextRangeProvider interface) en een UIA_Text_TextChangedEventId gebeurtenis genereren. Clients kunnen de gebeurtenis gebruiken als hint om redactionele wijzigingen in de tekst van een besturingselement te bevestigen.
• Alle tekstbereikobjecten die worden gebruikt door de ITextRangeProvider::Compare, CompareEndpointsen MoveEndpointByRange-methoden moeten peers zijn van dezelfde Text patroon-implementatie.
• Hoewel dit niet vereist is, kan de pRetVal waarde die is opgehaald door de ITextRangeProvider::CompareEndpoints methode de afstand aangeven, in tekens (TextUnit_Character), tussen de twee eindpunten. Clienttoepassingen mogen echter niet afhankelijk zijn van de nauwkeurigheid van pRetVal- buiten de positieve of negatieve waarde.
• De ITextRangeProvider::ExpandToEnclosingUnit, Verplaatsenen MoveEndpointByUnit methoden vereisen zorgvuldige overweging van de opgegeven teksteenheid. Zie Een TextRange by Text Unit bewerken voor meer informatie.
• Zie Tekst selecteren in een tekstbereik voor implementatievereisten met betrekking tot de ITextRangeProvider::Select, AddToSelectionen RemoveFromSelection methoden tekst selecteren in een tekstbereik.
• De ITextRangeProvider::FindText en FindAttribute methoden zoeken vooruit of achteruit naar één overeenkomende tekenreeks of tekstkenmerk. Ze moeten NULL- retourneren als er geen overeenkomst wordt gevonden.
• De methode ITextRangeProvider::GetAttributeValue moet het adres retourneren dat is verkregen uit de UiaGetReservedMixedAttributeValue- of UiaGetReservedNotSupportedValue functie als het bijbehorende kenmerk in het bereik varieert of als het kenmerk niet wordt ondersteund door het tekstbesturingselement. Het TextRange specificatie van het besturingspatroon staat het toevoegen van nieuwe tekstkenmerk-id's niet toe of het wijzigen van de manier waarop de bestaande kenmerken worden gedefinieerd.
• Indien mogelijk moet de methode ITextRangeProvider::GetBoundingRectangles een matrix retourneren die één begrenzingsrechthoek bevat voor elke volledig of gedeeltelijk zichtbare regel tekst in een tekstbereik. Als dit niet mogelijk is, kan de provider een matrix retourneren die de begrenzingsrechthoeken van alleen volledig zichtbare lijnen bevat; Dit beperkt echter de mogelijkheid van een clienttoepassing om nauwkeurig te beschrijven hoe de tekst op het scherm wordt weergegeven.
• De methode ITextRangeProvider::Get Children moet alle onderliggende elementen retourneren die zijn ingesloten in een tekstbereik, maar hoeft geen onderliggende elementen van de onderliggende elementen te retourneren. Als een tekstbereik bijvoorbeeld een tabel bevat met een aantal onderliggende cellen, kan de methode GetChildren alleen het tabelelement en niet de celelementen retourneren. Om prestatie- of architectuurredenen kan een provider mogelijk niet alle ingesloten objecten beschikbaar maken die worden gehost in een document in de automatiseringsstructuur. In dit geval moet de provider ten minste ondersteuning bieden voor het inventariseren van onderliggende objecten via de methode GetChildren en, als optie, ondersteuning bieden voor het VirtualizedItem controlepatroon voor ondersteuning voor ontvirtualisatie.
• De methode ITextRangeProvider::GetEnclosingElement retourneert doorgaans de tekstprovider die het tekstbereik levert. Als de tekstprovider echter onderliggende objecten ondersteunt, zoals tabellen of hyperlinks, kan het insluitelement een afstammeling van de tekstprovider zijn. Het element dat wordt geretourneerd door GetEnclosingElement moet het element zijn dat het dichtst bij het opgegeven tekstbereik ligt. Als het tekstbereik zich bijvoorbeeld in een cel van een tabel bevindt, moet GetEnclosingElement de cel in plaats van het tabelelement retourneren.
• De methode ITextRangeProvider::GetText retourneert de tekst zonder opmaak in het bereik. Zie Tekst ophalen uit een tekstbereik voor meer informatie.
• Het aanroepen van ITextRangeProvider::ScrollIntoView moet de tekst in de viewport van het tekstbesturingselement uitlijnen zoals opgegeven door de parameter alignToTop. Hoewel er geen behoefte is aan horizontale uitlijning, moet het tekstbereik zowel horizontaal als verticaal zichtbaar zijn. Bij het evalueren van de parameter alignToTop moet een provider rekening houden met de richting van het tekstbesturingselement en de stroomrichting van de tekst. Als bijvoorbeeld alignToTop is TRUE- voor een verticaal georiënteerd tekstbesturingselement dat tekst bevat die van rechts naar links stroomt, moet de provider het tekstbereik uitlijnen met de rechterkant van de viewport.
• Wanneer u door een document bladert door TextUnit_Line, als het tekstbereik een ingesloten tabel invoert, moet elke regel tekst in een cel worden behandeld als een regel.

Vereiste leden voor ITextProvider-

De volgende eigenschappen en methoden zijn vereist voor het implementeren van de ITextProvider interface.

De volgende aanvullende eigenschappen en methoden zijn vereist voor het implementeren van de ITextProvider2 interface.

Vereiste leden voor ITextRangeProvider

De volgende eigenschappen en methoden zijn vereist voor het implementeren van de ITextRangeProvider interface.

De volgende aanvullende eigenschappen en methoden zijn vereist voor het implementeren van de ITextRangeProvider2 interface.

Het besturingselement TextRange heeft geen gekoppelde gebeurtenissen.

Ondersteunende tekstbereiken

In deze sectie wordt beschreven hoe een provider verschillende methoden van de ITextRangeProvider en ITextRangeProvider2 interfaces moet implementeren ter ondersteuning van het TextRange-besturingspatroon.

Een tekstbereik per teksteenheid bewerken

De ITextRangeProvider interface biedt verschillende methoden voor het bewerken en navigeren van tekstbereiken in een besturingselement op basis van tekst. De ITextRangeProvider::Move, MoveEndpointByUniten ExpandToEnclosingUnit methoden verplaatsen een tekstbereik of een van de eindpunten ervan door de opgegeven teksteenheid, zoals teken, woord, alinea, enzovoort. Zie UI Automation Text Unitsvoor meer informatie.

Ondanks de naam wordt met de methode ITextRangeProvider::ExpandToEnclosingUnit niet noodzakelijkerwijs een tekstbereik uitgevouwen. In plaats daarvan wordt een tekstbereik genormaliseerd door de eindpunten te verplaatsen, zodat het bereik de opgegeven teksteenheid omvat. Het bereik wordt uitgebreid als het kleiner is dan de opgegeven eenheid of korter is als het langer is dan de opgegeven eenheid. Het is van cruciaal belang dat de methode ExpandToEnclosingUnit tekstbereiken altijd consistent normaliseert; anders zouden andere aspecten van het bewerken van tekstbereiken per teksteenheid onvoorspelbaar zijn. In het volgende diagram ziet u hoe ExpandToEnclosingUnit een tekstbereik normaliseert door de eindpunten van het bereik te verplaatsen.

Als het tekstbereik begint aan het begin van een teksteenheid en eindigt aan het begin van, of vóór, de grens van de volgende teksteenheid, wordt het eindpunt verplaatst naar de volgende teksteenheidgrens (zie 1 en 2 in het vorige diagram).

Als het tekstbereik begint aan het begin van een teksteenheid en eindigt op, of na, de volgende eenheidsgrens, blijft het eindpunt achter of wordt het achterwaarts verplaatst naar de volgende eenheidsgrens na het begineindpunt (zie 3 en 4 in de vorige afbeelding). Als er meer dan één teksteenheidgrens is tussen de begin- en eindeindpunten, wordt het eindeindpunt naar de volgende eenheidsgrens verplaatst na het begineindpunt, wat resulteert in een tekstbereik dat één teksteenheid lang is.

Als het tekstbereik in een midden van de teksteenheid begint, wordt het begineindpunt naar het begin van de teksteenheid verplaatst en wordt het eindeindpunt naar voren of achteruit verplaatst, indien nodig, naar de volgende eenheidsgrens na het begineindpunt (zie 5 tot en met 8 in het vorige diagram).

Wanneer de methode ITextRangeProvider::Move wordt aangeroepen, normaliseert de provider het tekstbereik door de opgegeven teksteenheid met behulp van dezelfde normalisatielogica als de methode ExpandToEnclosingUnit. Vervolgens verplaatst de provider het bereik naar achteren of naar voren met het opgegeven aantal teksteenheden. Bij het verplaatsen van het bereik moet de provider de grenzen van ingesloten objecten in de tekst negeren. (De eenheidsgrens zelf kan echter worden beïnvloed door het bestaan van een ingesloten object). In het volgende diagram ziet u hoe met de methode Move een tekstbereik, eenheid per eenheid, wordt verplaatst tussen ingesloten objecten en teksteenheidgrenzen.

De methode ITextRangeProvider::MoveEndpointByUnit verplaatst een van de eindpunten vooruit of achteruit door de opgegeven teksteenheid, zoals in de volgende afbeelding wordt weergegeven.

Met de methode ITextRangeProvider::MoveEndpointByRange kan een clienttoepassing één eindpunt van een tekstbereik instellen op dezelfde locatie als het opgegeven eindpunt van een tweede tekstbereik.

Tekst selecteren in een tekstbereik

De ITextRangeProvider interface bevat verschillende methoden voor het beheren van de selectie van tekst in een op tekst gebaseerd besturingselement.

De ITextRangeProvider::Selecteer methode moet de tekst selecteren die overeenkomt met een tekstbereik en de vorige selectie, indien van toepassing, verwijderen uit het tekst besturingselement. Als Selecteren wordt aangeroepen voor een degenererend tekstbereik, moet de provider de invoegpositie naar de locatie van het tekstbereik verplaatsen zonder tekst te selecteren.

Als een besturingselement ondersteuning biedt voor de selectie van meerdere, niet-aaneengesloten tekstbereiken, voegt de ITextRangeProvider::AddToSelection en RemoveFromSelection methoden tekstbereiken toe aan en verwijder ze uit de verzameling geselecteerde tekstbereiken. Als het besturingselement slechts één geselecteerd tekstbereik tegelijk ondersteunt, maar de selectiebewerking zou resulteren in de selectie van meerdere niet-aaneengesloten tekstbereiken, moet de provider een E_INVALIDOPERATION fout retourneren of de huidige selectie uitbreiden of afkappen. De eigenschap ITextProvider::SupportedTextSelection moet aangeven of een besturingselement de selectie van één of meerdere tekstbereiken ondersteunt, of helemaal geen.

Als een besturingselement op basis van tekstinvoegingen ondersteunt, moet het aanroepen van ITextRangeProvider::AddToSelection of RemoveFromSelection op een degenerate tekstbereik in het besturingselement de invoegpositie verplaatsen, maar mag geen tekst worden geselecteerd.

Tekst ophalen uit een tekstbereik

De methode ITextRangeProvider::GetText retourneert de tekst zonder opmaak van een tekstbereik. De tekst zonder opmaak moet alle besturingstekens bevatten die in de brontekst worden gevonden, zoals regelterugloop en het Unicode-teken van links naar rechts (LRM). De tekst zonder opmaak mag geen markeringstags bevatten, zoals HTML die aanwezig kunnen zijn in de brontekst. Ook moeten escapecodes in de brontekst worden geconverteerd naar de equivalenten van tekst zonder opmaak. '' moet bijvoorbeeld worden geconverteerd naar een eenvoudig spatieteken.

Als een ingesloten object een tekstbereik omvat, moet de tekst zonder opmaak de binnenste tekst van het object bevatten, maar niet de alternatieve tekst (de naameigenschap van het ingesloten object), omdat deze mogelijk inconsistent is met de beschrijvende binnentekst. Zie How UI Automation Embedded Objectsbeschikbaar maakt voor meer informatie.

ShowContextMenu implementeren

ITextRangeProvider2::ShowContextMenu moet altijd het contextmenu aan het beginpunt van het bereik weergeven. Dit moet gelijk zijn aan wat er zou gebeuren als de gebruiker op de contextmenutoets of Shift+F10 drukt met de invoegpositie aan het begin van het bereik.

Als het contextmenu meestal resulteert in het verplaatsen van de invoegpositie naar een bepaalde locatie, moet dit ook worden uitgevoerd voor het programmatisch aanroepen van ShowContextMenu voor ui Automation-ondersteuning.

Interoperabiliteit met system Caret

Het correct ondersteunen van de invoegpositie is essentieel voor veel clienttoepassingen, inclusief toepassingen die niet zijn gebaseerd op UI Automation. In het besturingspatroon Tekst wordt de invoegpositie vertegenwoordigd door een degenererend (leeg) tekstbereik op de positie van de systeemzorg. Wanneer de invoegpositie wordt verplaatst, moet een besturingselement de gebeurtenis TextSelectionChanged (UIA_Text_TextSelectionChangedEventId) verhogen. Sommige clienttoepassingen zijn afhankelijk van deze gebeurtenis om de locatie van de invoegpositie te bewaken en om de tekstselectie bij te houden.

Wanneer een besturingselement geselecteerde tekst bevat, biedt het huidige ontwerp van het Tekst besturingselementpatroon geen manier om de locatie van de invoegpositie rechtstreeks te koppelen aan een bepaald tekstbereik. De provider moet de tekstselectie bijhouden en de locatie van de invoegpositie op de juiste manier instellen. Omdat het selecteren van tekst meestal wordt uitgevoerd door de invoegpositie te verplaatsen terwijl u Shift of Ctrl ingedrukt houdt, of beide, kan een provider de tekstselectie bijhouden door de status van deze toetsen te controleren wanneer de selectie verandert.

Omdat het toegankelijkheidsframework ingebouwde ondersteuning biedt voor de systeemzorg, maar niet voor een aangepaste caret, moeten op tekst gebaseerde besturingselementen waar mogelijk de systeemzorg gebruiken. Besturingselementen die gebruikmaken van een aangepaste caret kunnen ervoor zorgen dat de caret toegankelijk is door een systeemverzorging te maken die dezelfde afmetingen heeft als de aangepaste caret en het plaatsen van de systeemzorg op dezelfde locatie in de gebruikersinterface van het besturingselement als de aangepaste caret, dat wil gezegd op de invoegpositie. Als alternatief kan een besturingselement dat gebruikmaakt van een aangepaste zorg een Microsoft Active Accessibility Provider implementeren voor OBJID_CARET om toegankelijkheidsinformatie rechtstreeks voor uw aangepaste zorg te verstrekken.

Zie Caretsvoor meer informatie over de systeemzorg.

Gebruik de Inspect en Accessible Event Watcher tools om te testen of uw besturingselement de locatie van het systeem correct zichtbaar maakt.

De schermcoördinaten van het midden van de systeem caret bitmap moeten altijd overeenkomen met de locatie van de invoegpositie. Op die manier kan een client de coördinaten van het caret-scherm gebruiken in een aanroep naar ITextProvider::RangeFromPoint om een tekstbereik op te halen dat de locatie van de invoegpositie nauwkeurig weergeeft.

Verwante onderwerpen

besturingstypen en de ondersteunde besturingspatronen

type tekstbesturing

TextEdit-besturingselementpatroon

TextChild Control Pattern

Overzicht van UI Automation-besturingspatronen

UI Automation-ondersteuning voor tekstuele inhoud

Overzicht van UI Automation Tree