Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Toto téma popisuje, jak používat vlastnosti a metody IUIAutomationTextRange rozhraní pro přístup k textovému obsahu textového ovládacího prvku a manipulaci s ním.
Co je oblast textu?
Textový objektový model Microsoft UI Automation je založen na konceptu rozsahu textu . Rozsah textu je objekt, který poskytuje rozhraní IUIAutomationTextRange a představuje souvislé rozpětí textu v textovém ovládacím prvku. Každá oblast textu má počáteční i koncový bod a veškerý textový obsah mezi těmito dvěma koncovými body se považuje za součást rozsahu. Oblast textu, jejíž počáteční bod a koncový bod jsou ve stejném umístění, se nazývá degenerovaný (nebo prázdný) rozsah textu. Degenerovaná oblast textu slouží k identifikaci konkrétního místa v textu ovládacího prvku, například ke zjištění umístění kurzoru pro vložení textu.
Získání objektů oblasti textu
Klientské aplikace získávají objekty rozsahu textu pomocí vlastností a metod IUIAutomationTextPattern rozhraní. Vlastnost IUIAutomationTextRangePattern::DocumentRange načte textovou oblast, která představuje celý textový obsah textového ovládacího prvku, zatímco jiné metody získávají textové rozsahy představující část obsahu, například vybraný text, viditelný text nebo objekt vložený do textu.
Metody IUIAutomationTextRangePattern::GetVisibleRanges a GetSelection mohou načíst pole objektů textového rozsahu. Pokud je ovládací prvek částečně zakrytý překrývajícím se oknem nebo jiným objektem, GetVisibleRanges vrátí pole obsahující objekt textové oblasti pro každý částečně viditelný řádek textu. Podobně platí, že pokud textový ovládací prvek podporuje výběr více nesouvislých rozsahů textu, GetSelection vrátí pole, které obsahuje objekt textového rozsahu pro každý vybraný rozsah.
Metoda IUIAutomationTextRangePattern::RangeFromChild umožňuje klientské aplikaci načíst textový rozsah, který obsahuje objekt, který je vložen do textového obsahu. Klient určuje IUIAutomationElement ukazatel rozhraní vloženého objektu, jako je obrázek, tabulka nebo hypertextový odkaz, a metoda vrátí textový rozsah, který ohraničuje objekt. Pokud však vložený objekt nemá přidružený žádný text, metoda vrátí degenerované textové oblasti.
Klientská aplikace může použít metodu IUIAutomationTextRangePattern::RangeFromPoint k načtení textové oblasti pro viditelný text nebo vložený objekt, který je nejblíže zadaným souřadnicím obrazovky.
Výběr textu v oblasti textu
Rozhraní IUIAutomationTextRange obsahuje řadu metod, které klientské aplikaci umožňují řídit výběr textu v textovém ovládacím prvku.
Klientské aplikace můžou použít IUIAutomationTextRange::Select metodu k výběru textu, který odpovídá rozsahu textu, a k odebrání předchozího výběru z textového ovládacího prvku. Volání Vybrat s degenerovaným textovým rozsahem posune kurzor na místo textového rozsahu, aniž by bylo vybráno nějaký text.
Pokud ovládací prvek podporuje výběr více nesouvislého rozsahu textu, může klient použít IUIAutomationTextRange::AddToSelection a RemoveFromSelection metody pro přidání rozsahů textu a jejich odebrání z kolekce vybraných oblastí textu. Pokud ovládací prvek podporuje pouze jeden vybraný výběr textu najednou, ale pokud by operace výběru vedla k výběru několika nesouvislých textových rozsahů, vrátí metoda buď E_INVALIDOPERATION chybu, nebo rozšíří či zkrátí aktuální výběr. Klientská aplikace může zjistit, zda ovládací prvek podporuje výběr jednoho nebo více rozsahů textu, nebo žádné vůbec, zaškrtnutím vlastnosti IUIAutomationTextPattern::SupportedTextSelection vlastnost.
Pokud textový ovládací prvek podporuje vkládání textu, volání IUIAutomationTextRange::AddToSelection nebo RemoveFromSelection v degenerované oblasti textu v ovládacím prvku přesune kurzor, ale nevybere žádný text.
Načítání textu z oblasti textu
Klientské aplikace mohou použít metodu IUIAutomationTextRange::GetText k načtení prostého textu oblasti textu. Prostý text obsahuje všechny řídicí znaky nalezené ve zdrojovém textu, například návrat na začátek řádku a znak LRM (Unicode zleva doprava). Čistý text neobsahuje žádné značky, jako je HTML, které mohou být obsaženy ve zdrojovém textu. Všechny řídicí kódy ve zdrojovém textu se také převedou na ekvivalenty prostého textu. Například " se převede na jednoduchý znak mezery.
Pokud vložený objekt zahrnuje rozsah textu, prostý text obsahuje vnitřní text objektu, ale nikoli alternativní text (vlastnost názvu vloženého objektu). Další informace naleznete v tématu Jak automatizace uživatelského rozhraní zveřejňuje vložené objekty.
Metoda IUIAutomationTextRange::FindText prohledá oblast textu konkrétního řetězce a pokud je nalezena, vrátí novou textovou oblast, která zahrnuje řetězec.
Načítání atributů textu z oblasti textu
Atributy textu určují styl formátování textu v textovém ovládacím prvku a zahrnují například barvu popředí, styl odrážek, velikost písma atd. Automatizace uživatelského rozhraní podporuje řadu textových atributů a definuje identifikátor pro každý podporovaný atribut. Klientská aplikace se může dotazovat na hodnotu konkrétního textového atributu zadáním identifikátoru atributu při volání metody IUIAutomationTextRange::GetAttributeValue, spolu s ukazatelem na strukturu VARIANT, která přijímá hodnotu atributu. Podrobné informace o každém textovém atributu, který automatizace uživatelského rozhraní podporuje, najdete v tématu identifikátory atributů textu.
Hodnota načtená GetAttributeValue představuje hodnotu atributu v celé textové oblasti. Pokud veškerý text v rozsahu sdílí stejnou hodnotu pro zadaný atribut, GetAttributeValuevrátí tuto hodnotu. Pokud se však hodnota atributu liší v rozsahu textu, GetAttributeValue vrátí ukazatel IUnknown na objekt statického tokenu nazvaný ReservedMixedAttribute. Pokud chcete zjistit, jestli se hodnota atributu liší v rozsahu textu, měla by klientská aplikace porovnat výsledky GetAttributeValue s objektem ReservedMixedAttribute, který byl načten z vlastnosti IUIAutomation::ReservedMixedAttributeValue.
Ovládací prvek založený na textu není nutný k podpoře všech atributů textu automatizace uživatelského rozhraní. Pokud klient volá metodu IUIAutomationTextRange::GetAttributeValue a předá identifikátor nepodporovaného atributu, vrátí metoda IUnknown ukazatel na objekt statického tokenu s názvem ReservedNotSupported objektu. Chcete-li zjistit, zda je podporován konkrétní atribut, měla by klientská aplikace porovnat výsledky GetAttributeValue s objektem ReservedNotSupported načteným z vlastnosti IUIAutomation::ReservedNotSupportedValue.
Klientské aplikace můžou použít metodu IUIAutomationTextRange::FindAttribute k vyhledání textového rozsahu textu, který má konkrétní textový atribut. Pokud se najde, vrátí metoda novou oblast textu, která zahrnuje odpovídající text. Všimněte si, že FindAttribute vrátí oblast textu pro odpovídající text, i když text není viditelný.
Načítání vložených objektů z oblasti textu
Oblast textu může obsahovat vložené objekty, jako jsou tabulky, obrázky, hypertextové odkazy atd. Klientská aplikace může načíst kolekci všech vložených objektů v rozsahu voláním metody IUIAutomationTextRange::GetChildren. Vložené objekty, které se překrývají s daným rozsahem, ale nejsou jím zcela uzavřeny, jsou také zahrnuty do kolekce. Pokud oblast neobsahuje žádné vložené objekty, GetChildren načte prázdnou kolekci.
I když to závisí na poskytovateli textového ovládacího prvku, metoda GetChildren obvykle nevrací žádné podřízené položky vložených elementů. Pokud například textový rozsah obsahuje tabulku s několika dceřinými buňkami, metoda GetChildren obvykle vrátí pouze prvek tabulky, nikoli jednotlivé prvky buňky.
Z důvodů výkonu nebo architektury GetChildren nemusí být možné načíst IUIAutomationElement objekty pro všechny vložené objekty v textové oblasti. Místo toho může poskytovatel vrátit kolekci, která obsahuje virtualizované položky. Další informace naleznete v tématu Práce s virtualizovanými položkami.
Manipulace s rozsahem textu
Rozhraní IUIAutomationTextRange poskytuje několik metod pro manipulaci s rozsahy textu a navigaci v textovém ovládacím prvku. Tyto metody IUIAutomationTextRange::Move, MoveEndpointByUnita ExpandToEnclosingUnit přesunou oblast textu nebo jeden z jeho koncových bodů o zadanou textovou jednotku, jako je znak, slovo, odstavec a podobně. Další informace naleznete v tématu automatizace textových jednotek uživatelského rozhraní.
Navzdory názvu nemusí metoda ExpandToEnclosingUnit nutně rozšířit rozsah textu. Místo toho "normalizuje" oblast textu přesunutím koncových bodů tak, aby rozsah zahrnoval zadanou textovou jednotku přesně. Oblast se rozšíří, pokud je menší než zadaná jednotka, nebo se zkrátí, pokud je delší. Následující diagram ukazuje, jak ExpandToEnclosingUnit normalizovat rozsah textu přesunutím koncových bodů rozsahu.
Pokud oblast textu začíná na začátku textové jednotky a končí na začátku nebo před následující hranicí textové jednotky, koncový bod se přesune na další hranici textové jednotky (viz 1 a 2 na předchozím obrázku).
Pokud textový úsek začíná na začátku textové jednotky a končí na, nebo po, další hranici jednotky, koncový bod zůstane na místě nebo se přesune zpět k dalšímu rozhraní jednotky za počátečním bodem (viz 3 a 4 na předchozím obrázku). Pokud mezi počátečním a koncovými koncovými body existuje více než jedna hranice textové jednotky, koncový koncový bod se přesune zpět na další hranici jednotky za počátečním koncovým bodem, což vede k rozsahu textu, který je jedna textová jednotka s délkou.
Pokud oblast textu začíná uprostřed textové jednotky, počáteční koncový bod se přesune zpět na začátek textové jednotky a koncový koncový bod se podle potřeby přesune dopředu nebo dozadu na další hranici jednotky za počátečním koncovým bodem (viz 5 až 8 na předchozím obrázku).
Když je volána metoda IUIAutomationTextRange::Move, zprostředkovatel normalizuje rozsah textu zadanou textovou jednotkou. Potom poskytovatel přesune rozsah dozadu nebo dopředu o zadaný počet textových jednotek. Při přesouvání rozsahu poskytovatel ignoruje hranice všech vložených objektů v textu. (Samotná hranice jednotky však může být ovlivněna existencí vloženého objektu). Následující diagram ukazuje, jak metoda Move přesune rozsah textu, jednotku podle jednotek, přes vložené objekty a hranice textové jednotky.
Metoda IUIAutomationTextRange::MoveEndpointByUnit přesune jeden z koncových bodů dopředu nebo dozadu zadanou textovou jednotkou. Následující obrázek ukazuje, jak se koncový bod posune vpřed.
Metoda IUIAutomationTextRange::MoveEndpointByRange umožňuje klientské aplikaci nastavit jeden koncový bod textového rozsahu na stejné umístění jako zadaný koncový bod druhého textového rozsahu.
Posouvání oblasti textu do zobrazení
IUIAutomationTextRange::ScrollIntoView metoda posune textový rozsah tak, aby byl text viditelný v oblasti zobrazení textového ovládacího prvku. Při volání ScrollIntoViewmůže klient určit, zda má být text zarovnaný s horním nebo dolním okrajem oblasti zobrazení.
Načtení ohraničujícího prvku textového úseku
Klientská aplikace může použít metodu IUIAutomationTextRange::GetEnclosingElement k načtení ukazatele rozhraní IUIAutomation nejvnitřnějšího prvku, který uzavírá textový rozsah. Obalující prvek je obvykle poskytovatel textu, který dodává rozsah textu. Pokud však zprostředkovatel textu podporuje podřízené prvky, jako jsou tabulky nebo hypertextové odkazy, může být nadřazený prvek následníkem zprostředkovatele textu.
Porovnání a klonování oblastí textu
Rozhraní IUIAutomationTextRange obsahuje dvě metody porovnání rozsahů textu. Metoda IUIAutomationTextRange::Compare porovná počáteční a koncové koncové koncové body dvou rozsahů textu a vrátí TRUE pokud jsou oba koncové body stejné. IUIAutomationTextRange::CompareEndpoints metoda porovnává počáteční nebo koncový bod obou rozsahů. Návratová hodnota je nulová, pokud jsou koncové body stejné, nebo kladná nebo záporná hodnota, která označuje relativní pozice těchto dvou koncových bodů.
Klientské aplikace mohou použít metodu IUIAutomationTextRange::Clone k vytvoření přesné kopie rozsahu textu. Nová oblast textu se dá manipulovat nezávisle na původním rozsahu textu.
Načítání poznámek
Oblast textu může obsahovat poznámky, pokud je textový ovládací prvek podporuje. Existuje mnoho různých druhů poznámek. Soubor hlavičky UIAutomationClient.h definuje sadu pojmenovaných konstantních hodnot, které identifikují typy poznámek, které podporuje automatizace uživatelského rozhraní. Další informace naleznete v tématu identifikátory typů poznámek.
Některé druhy poznámek jsou reprezentovány automatizačním prvkem podporujícím řídicí vzor Annotation (IUIAutomationAnnotationPattern rozhraní). Další druhy poznámek jsou vystaveny prostřednictvím vzoru ovládacího prvku TextRange. Zprostředkovatel může například vystavit jednoduchý indikátor pravopisné chyby, když metoda IUIAutomationTextRange::GetAttributeValue vrátí textový atribut AnnotationTypes s hodnotou AnnotationType_SpellingErrora hodnotu null pro textový atribut AnnotationObjects.
Načítání typů poznámek z oblasti textu
Pomocí metody IUIAutomationTextRange::GetAttributeValue můžete načíst seznam typů poznámek, které jsou přítomné v textovém rozsahu. Při volání metody zadejte ID textového atributu UIA_AnnotationTypesAttributeId a ukazatel na parametr typu VARIANT. Když se metoda vrátí, VARIANT parametr obsahuje seznam identifikátorů typu poznámky, jeden pro každý typ poznámky v textové oblasti. Další informace naleznete v tématu Identifikátory typů poznámek.
Načítání všech poznámek z oblasti textu
Chcete-li načíst poznámky z textového rozsahu, použijte metodu IUIAutomationTextRange::GetAttributeValue, přičemž zadáte ID textového atributu UIA_AnnotationObjectsAttributeId a ukazatel na parametr typu VARIANT. Když se metoda vrátí, parametr VARIANT obsahuje rozhraní IUIAutomationElementArray, které představuje pole automatizačních prvků, každý pro každou anotaci v textovém rozsahu. IUIAutomationElementArray::Length vlastnost označuje počet prvků v poli a IUIAutomationElementArray::GetElement metoda načte IUIAutomationElement rozhraní pro konkrétní prvek.
Načítání informací o určité poznámce
Chcete-li získat informace o konkrétní poznámce, nejprve načtěte rozhraní IUIAutomationElement pro prvek poznámky, jak je popsáno v předchozí části. Dále načtěte rozhraní IUIAutomationAnnotationPattern pro anotaci voláním IUIAutomationElement::GetCurrentPatternAs metodou s ID vzoru ovládacího prvku UIA_AnnotationPatternId, identifikátor rozhraní IID_IUIAutomationAnnotationPattern a adresu proměnné, která přijímá IUIAutomationAnnotation ukazatel pro anotaci. Zadejte dotaz na vlastnosti rozhraní IUIAutomationAnnotation, abyste načetli název typu anotace a ID typu, název autora anotace, datum a čas anotace a rozhraní IUIAutomationElement pro prvek, který je anotován.
Načtení cílového textu poznámky
Poznámka se obvykle vztahuje na určitou podmnožinu textu v oblasti textu. Po načtení rozhraní IUIAutomationElement pro anotaci můžete předat rozhraní metodě IUIAutomationTextRange2::RangeFromAnnotation pro načtení textové oblasti, která obsahuje text, jenž je cílem anotace.
Načítání vizuálních stylů
Poskytovatel implementuje kontrolní vzor Styly k popisu prvku uživatelského rozhraní, který má určitý styl, barvu výplně, vzor výplně nebo tvar. To je zvlášť užitečné při popisu prvků v dokumentu, které často mají takové styly. Styly, jako je tato, často obsahují informace, které jsou užitečné pro zákazníky s postižením; Styly můžou například popisovat určitý řetězec jako název dokumentu nebo určitý objekt vývojového diagramu jako kosočtverec nebo kruh.
Pomocí metody IUIAutomationTextRange::GetAttributeValue můžete načíst názvy a identifikátory vizuálních stylů, které se používají v textovém rozsahu. Pomocí textového atributu UIA_StyleNameAttributeId načtěte názvy stylů a pomocí UIA_StyleIdAttributeId načtěte identifikátory stylů.
Textový ovládací prvek, který podporuje vizuální styly, může implementovat vzor ovládacích prvků Styly umožňující klientům přístup k informacím o vizuálním stylu používaném ovládacím prvku. Klienti přistupují k ovládacímu vzoru Styly prostřednictvím rozhraní IUIAutomationStylesPattern. Toto rozhraní můžete načíst voláním IUIAutomationElement::GetCurrentPattern, nebo metodou GetCurrentPatternAs určující UIA_StylesPatternId jako identifikátor ovládacího vzoru.
Rozhraní IUIAutomationStylesPattern obsahuje vlastnosti a metody, které poskytují následující informace o vizuálním stylu:
- Název vizuálního stylu, například "Normální" nebo "Nadpis 1".
- Identifikátor vizuálního stylu. Další informace naleznete v identifikátorech stylů .
- Barva použitá k vyplnění textového ovládacího prvku.
- Barva vzorku použitého k vyplnění textového ovládacího prvku.
- Obrazec textového ovládacího prvku.
- Rozšířené vlastnosti; to znamená seznam názvů a hodnot specifických pro ovládací prvky.
Vyvolání kontextových nabídek z rozsahů textu
Od Windows 8.1 můžou rozsahy textu podporovat rozhraní IUIAutomationTextRange2. Toto rozhraní podporuje metodu ShowContextMenu. Tuto metodu můžete použít pro vyvolání libovolné místní nabídky, která souvisí s rozsahem textu. Scénář zahrnuje automatické opravy rozsahů textu nebo výběr možnosti editoru IME. V těchto případech se zobrazí místní nabídka, která podporuje interakci uživatele.
Související témata
-
Podpora automatizace uživatelského rozhraní pro textový obsah