Not
Åtkomst till denna sida kräver auktorisation. Du kan prova att logga in eller byta katalog.
Åtkomst till denna sida kräver auktorisation. Du kan prova att byta katalog.
Det här avsnittet beskriver hur du använder egenskaperna och metoderna för IUIAutomationTextRange- gränssnitt för att komma åt och ändra textinnehållet i en textbaserad kontroll.
Vad är ett textintervall?
Textobjektmodellen för Microsoft UI Automation baseras på begreppet textintervall. Ett textintervall är ett objekt som exponerar IUIAutomationTextRange--gränssnittet och representerar ett sammanhängande textintervall i en textbaserad kontroll. Varje textintervall har både en startslutpunkt och en slutpunkt, och allt textinnehåll mellan de två slutpunkterna anses vara en del av intervallet. Ett textintervall vars startslutpunkt och slutpunkt är på samma plats kallas för ett degenerera (eller tomt) textintervall. Ett degenererat textintervall används för att markera en specifik plats i texten i en kontroll, till exempel platsen för textinfogningspunkten.
Hämta textområdesobjekt
Klientprogram hämtar textområdesobjekt med hjälp av egenskaperna och metoderna för IUIAutomationTextPattern-gränssnittet. Egenskapen IUIAutomationTextRangePattern::D ocumentRange hämtar ett textintervall som representerar hela textinnehållet i en textbaserad kontroll, medan andra metoder hämtar textintervall som representerar en del av innehållet, till exempel den markerade texten, den synliga texten eller ett objekt som är inbäddat i texten.
Metoderna IUIAutomationTextRangePattern::GetVisibleRanges och GetSelection kan hämta matriser med textområdesobjekt. Om en kontroll delvis döljs av ett överlappande fönster eller annat objekt returnerar GetVisibleRanges en matris som innehåller ett textområdesobjekt för varje delvis synlig textrad. På samma sätt, om en textbaserad kontroll stöder valet av flera, uppdelade textintervall, returnerar GetSelection en matris som innehåller ett textområdesobjekt för varje markerat intervall.
Med metoden IUIAutomationTextRangePattern::RangeFromChild kan ett klientprogram hämta ett textintervall som omger ett objekt som är inbäddat i textinnehållet. Klienten anger IUIAutomationElement gränssnittspekare för ett inbäddat objekt, till exempel en bild, en tabell eller en hyperlänk, och metoden returnerar ett textintervall som omger objektet. Men om det inbäddade objektet inte har någon associerad text returnerar metoden ett degenererat textintervall.
Ett klientprogram kan använda metoden IUIAutomationTextRangePattern::RangeFromPoint för att hämta ett textintervall för synlig text eller inbäddat objekt som ligger närmast de angivna skärmkoordinaterna.
Markera text i ett textområde
Gränssnittet IUIAutomationTextRange innehåller ett antal metoder som gör att ett klientprogram kan styra valet av text i en textbaserad kontroll.
Klientprogram kan använda IUIAutomationTextRange::Välj metod för att markera texten som motsvarar ett textintervall och för att ta bort den tidigare markeringen, om någon, från textkontrollen. Om du anropar Välj med ett degenererat textintervall flyttas insättningspunkten till platsen för textområdet utan att markera någon text.
Om en kontroll stödjer valet av flera, åtskilda textintervall, kan en klient använda IUIAutomationTextRange::AddToSelection och RemoveFromSelection-metoderna för att lägga till och ta bort textintervall från samlingen med valda textintervall. Om kontrollen endast stöder ett markerat textintervall i taget, men markeringsåtgärden skulle resultera i val av flera olika textintervall, returnerar metoden antingen ett E_INVALIDOPERATION fel eller utökar eller trunkerar den aktuella markeringen. Ett klientprogram kan identifiera om en kontroll stöder val av enstaka eller flera textintervall eller inget alls genom att kontrollera egenskapen IUIAutomationTextPattern::SupportedTextSelection.
Om en textbaserad kontroll stöder textinfogningar, flyttas insättningspunkten utan att någon text väljs när man anropar IUIAutomationTextRange::AddToSelection eller RemoveFromSelection på ett degenererat textområde i kontrollen.
Hämtar text från ett textområde
Klientprogram kan använda metoden IUIAutomationTextRange::GetText för att hämta oformaterad text i ett textintervall. Oformaterad text innehåller alla kontrolltecken som finns i källtexten, till exempel radbrytningar och Unicode-markeringen från vänster till höger (LRM). Oformaterad text innehåller inga påläggstaggar, till exempel HTML som kan finnas i källtexten. Dessutom konverteras eventuella escape-koder i källtexten till motsvarande oformaterad text. Till exempel konverteras " " till ett enkelt blankstegstecken.
Om ett inbäddat objekt sträcker sig över ett textområde innehåller oformaterad text objektets inre text, men inte den alternativa texten (namnegenskapen för det inbäddade objektet). Mer information finns i Hur UI-automatisering exponerar inbäddade objekt.
Metoden IUIAutomationTextRange::FindText söker i ett textintervall efter en viss sträng och returnerar, om den hittas, ett nytt textintervall som omfattar strängen.
Hämta textattribut från ett textintervall
Textattribut bestämmer formateringsformatet för texten i en textbaserad kontroll och innehåller sådant som förgrundsfärg, punktformat, teckenstorlek och så vidare. UI Automation stöder ett antal textattribut och definierar en identifierare för varje attribut som stöds. Ett klientprogram kan fråga ett textintervall efter värdet för ett visst textattribut genom att ange en attributidentifierare i ett anrop till metoden IUIAutomationTextRange::GetAttributeValue, tillsammans med en pekare till en VARIANT- struktur som tar emot attributvärdet. Detaljerad information om varje textattribut som UI Automation stöder finns i textattributidentifierare.
Värdet som hämtas av GetAttributeValue representerar värdet för attributet i hela textområdet. Om all text i intervallet delar samma värde för det angivna attributet returneras det värdet av GetAttributeValue. Men om värdet för attributet varierar mellan textintervallet returnerar GetAttributeValue en IUnknown pekare till ett statiskt tokenobjekt som kallas ReservedMixedAttribute-objektet. För att ta reda på om värdet för ett attribut varierar mellan ett textintervall bör ett klientprogram jämföra resultatet av GetAttributeValue- med ReservedMixedAttribute- objekt som hämtats från egenskapen IUIAutomation::ReservedMixedAttributeValue.
En textbaserad kontroll krävs inte för att stödja alla textattribut för UI Automation. Om en klient anropar metoden IUIAutomationTextRange::GetAttributeValue och skickar identifieraren för ett attribut som inte stöds, returnerar metoden en IUnknown pekare till ett statiskt tokenobjekt som kallas ReservedNotSupported objekt. För att ta reda på om ett visst attribut stöds bör ett klientprogram jämföra resultatet av GetAttributeValue- med ReservedNotSupported-objektet som hämtats från egenskapen IUIAutomation::ReservedNotSupportedValue.
Klientprogram kan använda metoden IUIAutomationTextRange::FindAttribute för att söka i ett textintervall efter text som har ett visst textattribut. Om den hittas returnerar metoden ett nytt textintervall som omfattar matchande text. Observera att FindAttribute- returnerar ett textintervall för matchande text även om texten inte visas.
Hämtar inbäddade objekt från ett textintervall
Ett textintervall kan innehålla inbäddade objekt som tabeller, bilder, hyperlänkar och så vidare. Ett klientprogram kan hämta en samling med alla inbäddade objekt i ett intervall genom att anropa metoden IUIAutomationTextRange::GetChildren. Inbäddade objekt som överlappar intervallet men som inte är helt omgivna av det ingår också i samlingen. Om intervallet inte innehåller några inbäddade objekt hämtar GetChildren en tom samling.
Även om det beror på leverantören av den textbaserade kontrollen, returnerar metoden GetChildren vanligtvis inte några barn till de inbäddade elementen. Om ett textområde till exempel innehåller en tabell som har ett antal underordnade celler returnerar metoden GetChildren vanligtvis bara tabellelementet och inte cellelementen.
Av prestanda- eller arkitekturskäl kanske GetChildren inte kan hämta IUIAutomationElement objekt för alla inbäddade objekt i ett textintervall. I stället kan providern returnera en samling som innehåller virtualiserade objekt. Mer information finns i Arbeta med virtualiserade objekt.
Ändra ett textintervall
Gränssnittet IUIAutomationTextRange innehåller flera metoder för att manipulera och navigera i textintervall i en textbaserad kontroll. IUIAutomationTextRange::Move, MoveEndpointByUnitoch ExpandToEnclosingUnit metoderna flyttar ett textintervall eller en av dess slutpunkter enligt den angivna textenheten, såsom tecken, ord, stycke och så vidare. Mer information finns i UI Automation Text Units.
Trots namnet expanderar metoden ExpandToEnclosingUnit inte nödvändigtvis ett textintervall. I stället "normaliserar" det ett textintervall genom att flytta slutpunkterna så att intervallet omfattar den angivna textenheten exakt. Intervallet expanderas om det är mindre än den angivna enheten eller förkortas om det är längre än den angivna enheten. Följande diagram visar hur ExpandToEnclosingUnit normaliserar ett textintervall genom att flytta slutpunkterna för intervallet.
Om textintervallet börjar i början av en textenhet och slutar i början av, eller före, nästa textenhetsgräns, flyttas slutpunkten till nästa textenhetsgräns (se 1 och 2 i föregående bild).
Om textintervallet börjar i början av en textenhet och slutar vid eller efter nästa enhetsgräns förblir slutpunkten eller flyttas bakåt till nästa enhetsgräns efter startslutpunkten (se 3 och 4 i föregående bild). Om det finns fler än en textenhetsgräns mellan start- och slutpunkterna flyttas slutpunkten bakåt till nästa enhetsgräns efter startslutpunkten, vilket resulterar i ett textintervall som är en textenhet i längd.
Om textintervallet börjar mitt i en textenhet flyttas startslutpunkten bakåt till början av textenheten, och slutpunkten flyttas vid behov framåt eller bakåt till nästa enhetsgräns efter startslutpunkten (se 5 till 8 i föregående bild).
När metoden IUIAutomationTextRange::Move anropas normaliserar providern textintervallet med den angivna textenheten. Sedan flyttar providern intervallet bakåt eller framåt med det angivna antalet textenheter. När du flyttar intervallet ignorerar providern gränserna för alla inbäddade objekt i texten. (Enhetsgränsen kan dock påverkas av förekomsten av ett inbäddat objekt). Följande diagram visar hur metoden Flytta flyttar ett textintervall, enhet efter enhet, över inbäddade objekt och textenhetsgränser.
Metoden IUIAutomationTextRange::MoveEndpointByUnit flyttar en av slutpunkterna framåt eller bakåt med angiven textenhet. Följande bild visar hur en slutpunkt går framåt.
Metoden IUIAutomationTextRange::MoveEndpointByRange gör att ett klientprogram kan ange en slutpunkt för ett textintervall till samma plats som den angivna slutpunkten för ett andra textintervall.
Rulla ett textintervall till vyn
Metoden IUIAutomationTextRange::ScrollIntoView rullar ett textintervall så att texten visas i visningsområdet för den textbaserade kontrollen. När du anropar ScrollIntoViewkan en klient ange om texten ska justeras mot den övre eller nedre delen av visningsområdet.
Hämtar elementet som omsluter ett textintervall
Ett klientprogram kan använda metoden IUIAutomationTextRange::GetEnclosingElement för att återfå IUIAutomation gränssnittpekare för det innersta elementet som omger ett textintervall. Omslutande element är vanligtvis den textprovider som tillhandahåller textintervallet. Men om textleverantören stöder underordnade element, till exempel tabeller eller hyperlänkar, kan det inneslutande elementet vara en avkomling till textleverantören.
Jämföra och klona textintervall
Gränssnittet IUIAutomationTextRange innehåller två metoder för att jämföra textintervall. Metoden IUIAutomationTextRange::Compare jämför start- och slutpunkterna för två textintervall och returnerar TRUE- om båda slutpunkterna är desamma. Metoden IUIAutomationTextRange::CompareEndpoints jämför antingen start- eller slutpunkten för de två intervallen. Returvärdet är noll om slutpunkterna är desamma, eller ett positivt värde eller negativt värde som anger de relativa positionerna för de två slutpunkterna.
Klientprogram kan använda metoden IUIAutomationTextRange::Clone för att skapa en exakt kopia av textintervallet. Det nya textområdet kan ändras oberoende av det ursprungliga textintervallet.
Hämtar anteckningar
Ett textintervall kan innehålla anteckningar om den textbaserade kontrollen stöder dem. Det finns många olika typer av anteckningar. Huvudfilen UIAutomationClient.h definierar en uppsättning namngivna konstanta värden som identifierar de typer av anteckningar som UI Automation stöder. Mer information finns i Anteckningstypidentifierare.
Vissa typer av annotationer representeras av ett automatiseringselement som stöder Annotation kontrollmönster (IUIAutomationAnnotationPattern-gränssnittet). Andra typer av anteckningar exponeras via kontrollmönstret TextRange. En provider kan till exempel exponera en enkel stavningsfelindikator genom att IUIAutomationTextRange::GetAttributeValue-metoden returnerar ett AnnotationTypes textattribut för AnnotationType_SpellingErroroch ett null-värde för AnnotationObjects textattribut.
Hämta anteckningstyper från ett textintervall
Du kan hämta en lista över de typer av anteckningar som finns i ett textintervall med hjälp av metoden IUIAutomationTextRange::GetAttributeValue. När du anropar metoden anger du ett textattribut-ID för UIA_AnnotationTypesAttributeId och en pekare till en parameter av typen VARIANT. När metoden returnerar innehåller parametern VARIANT en lista med anteckningstypidentifierare, en för varje typ av anteckning i textområdet. Mer information finns i Anteckningstypidentifierare.
Hämtar alla anteckningar från ett textintervall
Om du vill hämta anteckningarna från ett textintervall anropar du metoden IUIAutomationTextRange::GetAttributeValue, anger ett textattribut-ID för UIA_AnnotationObjectsAttributeId och en pekare till en parameter av typen VARIANT. När metoden returnerar innehåller parametern VARIANT ett IUIAutomationElementArray- gränssnitt som representerar en matris med automationselement, en för varje anteckning i textområdet. Egenskapen IUIAutomationElementArray::Length anger antalet element i matrisen och metoden IUIAutomationElementArray::GetElement hämtar IUIAutomationElement--gränssnittet för ett visst element.
Hämtar information om en viss anteckning
Om du vill hämta information om en viss anteckning hämtar du först gränssnittet IUIAutomationElement för anteckningselementet enligt beskrivningen i föregående avsnitt. Hämta sedan IUIAutomationAnnotationPattern-gränssnittet för anteckningen genom att anropa IUIAutomationElement::GetCurrentPatternAs-metoden med ett kontrollmönster-ID för UIA_AnnotationPatternId, en gränssnittsidentifierare för IID_IUIAutomationAnnotationPattern och adressen till en variabel som tar emot IUIAutomationAnnotation pekaren för anteckningen. Hämta egenskaperna hos IUIAutomationAnnotation-gränssnittet för att få anteckningstypens namn och typ-ID, namnet på anteckningsförfattaren, datum och tid för anteckningen samt IUIAutomationElement-gränssnittet för elementet som annoterats.
Hämtar annoteringens måltext
Normalt gäller en anteckning för en delmängd av texten i ett textintervall. När du har hämtat IUIAutomationElement-gränssnittet för en anteckning kan du skicka gränssnittet till metoden IUIAutomationTextRange2::RangeFromAnnotation för att hämta ett textintervall som innehåller texten som är målet för anteckningen.
Hämtar visuella stilar
En leverantör implementerar Formatmallar kontrollmönstret för att beskriva ett UI-element som har ett specifikt format, fyllningsfärg, fyllningsmönster eller form. Detta är särskilt användbart när du beskriver element i ett dokument, som ofta har sådana format. Format som detta har ofta information som är användbar för kunder med funktionshinder. Formatmallar kan till exempel beskriva en viss sträng som rubrik för ett dokument eller ett visst flödesschemaobjekt som en romb eller cirkel.
Du kan använda metoden IUIAutomationTextRange::GetAttributeValue för att hämta namn och identifierare för de visuella formatmallar som används i ett textintervall. Använd textattributet UIA_StyleNameAttributeId för att hämta formatmallsnamnen och UIA_StyleIdAttributeId för att hämta formatidentifierarna.
En textbaserad kontroll som stöder visuella format kan implementera formatmallar kontrollmönster så att klienter kan komma åt information om ett visuellt format som används av kontrollen. Klienter kommer åt formatkontrollmönstret via IUIAutomationStylesPattern--gränssnittet. Du kan hämta det här gränssnittet genom att anropa metoden IUIAutomationElement::GetCurrentPattern eller GetCurrentPatternAs och ange UIA_StylesPatternId som kontrollmönsteridentifierare.
Gränssnittet IUIAutomationStylesPattern innehåller egenskaper och metoder som ger följande information om ett visuellt format:
- Namnet på det visuella formatet, till exempel "Normal" eller "Rubrik 1".
- Identifieraren för den visuella stilen. Mer information finns i formatidentifierare.
- Den färg som används för att fylla den textbaserade kontrollen.
- Färgen på det mönster som används för att fylla den textbaserade kontrollen.
- Formen på den textbaserade kontrollen.
- De utökade egenskaperna; en lista med kontrollspecifika formatmallsnamn och värden.
Anropa snabbmenyer från textområden
Från och med Windows 8.1 kan textintervall stödja IUIAutomationTextRange2- gränssnitt. Det här gränssnittet stöder metoden ShowContextMenu. Du kan anropa den här metoden för att anropa alla snabbmenyer som är associerade med ett textintervall. Scenariot för detta är autokorrigering av textintervall eller val av IME-kandidat. I dessa fall visas en snabbmeny som stöder användarinteraktion.
Relaterade ämnen