Uso di IUIAutomationTextRange per accedere e modificare un intervallo di testo
In questo argomento viene descritto come utilizzare le proprietà e i metodi dell'interfaccia IUIAutomationTextRange per accedere e modificare il contenuto testuale di un controllo basato su testo.
Che cos'è un intervallo di testo?
Il modello a oggetti di testo di Microsoft Automazione interfaccia utente si basa sul concetto dell'intervallo di testo. Un intervallo di testo è un oggetto che espone l'interfaccia IUIAutomationTextRange e rappresenta un intervallo contiguo di testo in un controllo basato su testo. Ogni intervallo di testo ha sia un endpoint iniziale che un endpoint finale e tutto il contenuto testuale tra i due endpoint è considerato parte dell'intervallo. Un intervallo di testo il cui endpoint iniziale e finale si trovano nella stessa posizione viene chiamato intervallo di testo degenerato (o vuoto). Un intervallo di testo degenerato viene utilizzato per contrassegnare una posizione specifica all'interno del testo di un controllo, ad esempio la posizione del punto di inserimento del testo.
Acquisizione di oggetti intervallo di testo
Le applicazioni client acquisiscono oggetti intervallo di testo usando le proprietà e i metodi dell'interfaccia IUIAutomationTextPattern . La proprietà IUIAutomationTextRangePattern::D ocumentRange recupera un intervallo di testo che rappresenta l'intero contenuto testuale di un controllo basato su testo, mentre altri metodi acquisiscono intervalli di testo che rappresentano parte del contenuto, ad esempio il testo selezionato, il testo visibile o un oggetto incorporato nel testo.
I metodi IUIAutomationTextRangePattern::GetVisibleRanges e GetSelection possono recuperare matrici di oggetti intervallo di testo. Se un controllo è parzialmente nascosto da una finestra sovrapposta o da un altro oggetto, GetVisibleRanges restituisce una matrice contenente un oggetto intervallo di testo per ogni riga di testo parzialmente visibile. Analogamente, se un controllo basato su testo supporta la selezione di più intervalli di testo non contigui, GetSelection restituisce una matrice che contiene un oggetto intervallo di testo per ogni intervallo selezionato.
Il metodo IUIAutomationTextRangePattern::RangeFromChild consente a un'applicazione client di recuperare un intervallo di testo che racchiude un oggetto incorporato nel contenuto testuale. Il client specifica il puntatore all'interfaccia IUIAutomationElement di un oggetto incorporato, ad esempio un'immagine, una tabella o un collegamento ipertestuale, e il metodo restituisce un intervallo di testo che racchiude l'oggetto. Tuttavia, se all'oggetto incorporato non è associato alcun testo, il metodo restituisce un intervallo di testo degenerato.
Un'applicazione client può utilizzare il metodo IUIAutomationTextRangePattern::RangeFromPoint per recuperare un intervallo di testo per il testo visibile o l'oggetto incorporato più vicino alle coordinate dello schermo specificate.
Selezione di testo in un intervallo di testo
L'interfaccia IUIAutomationTextRange include diversi metodi che consentono a un'applicazione client di controllare la selezione del testo in un controllo basato su testo.
Le applicazioni client possono utilizzare il metodo IUIAutomationTextRange::Select per selezionare il testo corrispondente a un intervallo di testo e per rimuovere la selezione precedente, se presente, dal controllo di testo. Chiamando Select con un intervallo di testo degenerato, il punto di inserimento viene spostato nella posizione dell'intervallo di testo senza selezionare alcun testo.
Se un controllo supporta la selezione di più intervalli di testo non contigui, un client può utilizzare i metodi IUIAutomationTextRange::AddToSelection e RemoveFromSelection per aggiungere intervalli di testo e rimuoverli da , insieme di intervalli di testo selezionati. Se il controllo supporta un solo intervallo di testo selezionato alla volta, ma l'operazione di selezione determina la selezione di più intervalli di testo non contigui, il metodo restituisce un errore E_INVALIDOPERATION oppure estende o tronca la selezione corrente. Un'applicazione client può determinare se un controllo supporta la selezione di uno o più intervalli di testo o nessuno, controllando la proprietà IUIAutomationTextPattern::SupportedTextSelection .
Se un controllo basato su testo supporta inserimenti di testo, la chiamata a IUIAutomationTextRange::AddToSelection o RemoveFromSelection in un intervallo di testo degenerato nel controllo sposta il punto di inserimento ma non seleziona alcun testo.
Recupero di testo da un intervallo di testo
Le applicazioni client possono usare il metodo IUIAutomationTextRange::GetText per recuperare il testo normale di un intervallo di testo. Il testo normale include tutti i caratteri di controllo presenti nel testo di origine, ad esempio i ritorni a capo e il contrassegno Unicode da sinistra a destra (LRM). Il testo normale non include tag di markup come HTML che possono essere presenti nel testo di origine. Inoltre, tutti i codici di escape nel testo di origine vengono convertiti negli equivalenti di testo normale. Ad esempio, " " viene convertito in un carattere di spazio semplice.
Se un oggetto incorporato si estende su un intervallo di testo, il testo normale include il testo interno dell'oggetto, ma non il testo alternativo (la proprietà name dell'oggetto incorporato). Per altre informazioni, vedere How Automazione interfaccia utente Exposes Embedded Objects.For more information, see How Automazione interfaccia utente Exposes Embedded Objects.
Il metodo IUIAutomationTextRange::FindText cerca un intervallo di testo per una determinata stringa e, se viene trovato, restituisce un nuovo intervallo di testo che include la stringa.
Recupero di attributi di testo da un intervallo di testo
Gli attributi di testo determinano lo stile di formattazione del testo in un controllo basato su testo e includono elementi quali il colore di primo piano, lo stile del punto elenco, le dimensioni del carattere e così via. Automazione interfaccia utente supporta diversi attributi di testo e definisce un identificatore per ogni attributo supportato. Un'applicazione client può eseguire una query su un intervallo di testo per il valore di un attributo di testo specifico specificando un identificatore di attributo in una chiamata al metodo IUIAutomationTextRange::GetAttributeValue , insieme a un puntatore a una struttura VARIANT che riceve il valore dell'attributo. Per informazioni dettagliate su ogni attributo di testo supportato da Automazione interfaccia utente, vedere Identificatori di attributo di testo.
Il valore recuperato da GetAttributeValue rappresenta il valore dell'attributo nell'intero intervallo di testo. Se tutto il testo nell'intervallo condivide lo stesso valore per l'attributo specificato, tale valore viene restituito da GetAttributeValue. Tuttavia, se il valore dell'attributo varia nell'intervallo di testo, GetAttributeValue restituisce un puntatore IUnknown a un oggetto token statico denominato oggetto ReservedMixedAttribute . Per determinare se il valore di un attributo varia in un intervallo di testo, un'applicazione client deve confrontare i risultati di GetAttributeValue con l'oggetto ReservedMixedAttribute recuperato dalla proprietà IUIAutomation::ReservedMixedAttributeValue .
Non è necessario un controllo basato su testo per supportare tutti gli attributi di testo Automazione interfaccia utente. Se un client chiama il metodo IUIAutomationTextRange::GetAttributeValue e passa l'identificatore di un attributo non supportato, il metodo restituisce un puntatore IUnknown a un oggetto token statico denominato oggetto ReservedNotSupported . Per determinare se è supportato un particolare attributo, un'applicazione client deve confrontare i risultati di GetAttributeValue con l'oggetto ReservedNotSupported recuperato dalla proprietà IUIAutomation::ReservedNotSupportedValue .
Le applicazioni client possono usare il metodo IUIAutomationTextRange::FindAttribute per cercare testo in un intervallo di testo con un attributo di testo specifico. Se viene trovato, il metodo restituisce un nuovo intervallo di testo che include il testo corrispondente. Si noti che FindAttribute restituisce un intervallo di testo per il testo corrispondente anche se il testo non è visibile.
Recupero di oggetti incorporati da un intervallo di testo
Un intervallo di testo può includere oggetti incorporati, ad esempio tabelle, immagini, collegamenti ipertestuali e così via. Un'applicazione client può recuperare una raccolta di tutti gli oggetti incorporati in un intervallo chiamando il metodo IUIAutomationTextRange::GetChildren . Gli oggetti incorporati che si sovrappongono all'intervallo, ma non sono interamente racchiusi da esso, sono inclusi anche nella raccolta. Se l'intervallo non contiene oggetti incorporati, GetChildren recupera una raccolta vuota.
Anche se dipende dal provider del controllo basato su testo, il metodo GetChildren in genere non restituisce elementi figlio degli elementi incorporati. Ad esempio, se un intervallo di testo contiene una tabella con un numero di celle figlio, il metodo GetChildren restituisce in genere solo l'elemento tabella e non gli elementi della cella.
Per motivi di prestazioni o architetturali, GetChildren potrebbe non essere in grado di recuperare gli oggetti IUIAutomationElement per tutti gli oggetti incorporati in un intervallo di testo. Al contrario, il provider potrebbe restituire una raccolta che include elementi virtualizzati. Per altre informazioni, vedere Utilizzo di elementi virtualizzati.
Modifica di un intervallo di testo
L'interfaccia IUIAutomationTextRange fornisce diversi metodi per la modifica e l'esplorazione di intervalli di testo in un controllo basato su testo. I metodi IUIAutomationTextRange::Move, MoveEndpointByUnit e ExpandToEnclosingUnit spostano un intervallo di testo o uno dei relativi endpoint in base all'unità di testo specificata, ad esempio carattere, parola, paragrafo e così via. Per altre informazioni, vedere Automazione interfaccia utente unità di testo.
Nonostante il nome, il metodo ExpandToEnclosingUnit non espande necessariamente un intervallo di testo. Al contrario, "normalizza" un intervallo di testo spostando gli endpoint in modo che l'intervallo includa esattamente l'unità di testo specificata. L'intervallo viene espanso se è minore dell'unità specificata o abbreviato se è più lungo dell'unità specificata. Il diagramma seguente mostra come ExpandToEnclosingUnit normalizza un intervallo di testo spostando gli endpoint dell'intervallo.
Se l'intervallo di testo inizia all'inizio di un'unità di testo e termina all'inizio di o prima, il limite successivo dell'unità di testo, l'endpoint finale viene spostato al limite successivo dell'unità di testo (vedere 1 e 2 nella figura precedente).
Se l'intervallo di testo inizia all'inizio di un'unità di testo e termina in corrispondenza o dopo, il limite dell'unità successiva, l'endpoint finale rimane o viene spostato all'indietro al limite dell'unità successiva dopo l'endpoint iniziale (vedere 3 e 4 nella figura precedente). Se sono presenti più limiti di unità di testo tra gli endpoint iniziale e finale, l'endpoint finale viene spostato all'indietro fino al limite dell'unità successiva dopo l'endpoint iniziale, con conseguente intervallo di testo di una singola unità di testo.
Se l'intervallo di testo inizia al centro di un'unità di testo, l'endpoint iniziale viene spostato all'indietro all'inizio dell'unità di testo e l'endpoint finale viene spostato in avanti o indietro, se necessario, al limite dell'unità successiva dopo l'endpoint iniziale (vedere da 5 a 8 nella figura precedente).
Quando viene chiamato il metodo IUIAutomationTextRange::Move , il provider normalizza l'intervallo di testo in base all'unità di testo specificata. Il provider sposta quindi l'intervallo indietro o avanti in base al numero specificato di unità di testo. Quando si sposta l'intervallo, il provider ignora i limiti di qualsiasi oggetto incorporato nel testo. Il limite di unità può tuttavia essere influenzato dall'esistenza di un oggetto incorporato. Il diagramma seguente illustra come il metodo Move sposta un intervallo di testo, un'unità per unità, tra oggetti incorporati e limiti di unità di testo.
Il metodo IUIAutomationTextRange::MoveEndpointByUnit sposta uno degli endpoint in avanti o indietro in base all'unità di testo specificata. La figura seguente mostra come un endpoint si sposta in avanti.
Il metodo IUIAutomationTextRange::MoveEndpointByRange consente a un'applicazione client di impostare un endpoint di un intervallo di testo sulla stessa posizione dell'endpoint specificato di un secondo intervallo di testo.
Scorrimento di un intervallo di testo nella visualizzazione
Il metodo IUIAutomationTextRange::ScrollIntoView scorre un intervallo di testo in modo che il testo sia visibile nel riquadro di visualizzazione del controllo basato su testo. Quando si chiama ScrollIntoView, un client può specificare se il testo deve essere allineato alla parte superiore o inferiore del riquadro di visualizzazione.
Recupero dell'elemento di inclusione di un intervallo di testo
Un'applicazione client può usare il metodo IUIAutomationTextRange::GetEnclosingElement per recuperare il puntatore dell'interfaccia IUIAutomation dell'elemento più interno che racchiude un intervallo di testo. L'elemento contenitore è in genere il provider di testo che fornisce l'intervallo di testo. Tuttavia, se il provider di testo supporta elementi figlio come tabelle o collegamenti ipertestuali, l'elemento contenitore potrebbe essere un discendente del provider di testo.
Confronto e clonazione di intervalli di testo
L'interfaccia IUIAutomationTextRange include due metodi per confrontare gli intervalli di testo. Il metodo IUIAutomationTextRange::Compare confronta gli endpoint iniziali e finali di due intervalli di testo e restituisce TRUE se entrambi gli endpoint sono uguali. Il metodo IUIAutomationTextRange::CompareEndpoints confronta l'endpoint iniziale o finale dei due intervalli. Il valore restituito è zero se gli endpoint sono uguali o un valore positivo o negativo che indica le posizioni relative dei due endpoint.
Le applicazioni client possono usare il metodo IUIAutomationTextRange::Clone per creare una copia esatta dell'intervallo di testo. Il nuovo intervallo di testo può essere modificato indipendentemente dall'intervallo di testo originale.
Recupero di annotazioni
Un intervallo di testo può includere annotazioni se il controllo basato su testo li supporta. Esistono molti tipi diversi di annotazioni. Il file di intestazione UIAutomationClient.h definisce un set di valori costanti denominati che identificano i tipi di annotazioni supportate Automazione interfaccia utente. Per altre informazioni, vedere Identificatori di tipo di annotazione.
Alcuni tipi di annotazioni sono rappresentati da un elemento di automazione che supporta il modello di controllo annotazione (interfaccia IUIAutomationAnnotationPattern ). Altri tipi di annotazioni vengono esposti tramite il modello di controllo TextRange . Ad esempio, un provider potrebbe esporre un semplice indicatore di errore ortografico usando il metodo IUIAutomationTextRange::GetAttributeValue restituisce un attributo di testo AnnotationTypes di AnnotationType_SpellingError e un valore Null per l'attributo di testo AnnotationObjects .
Recupero di tipi di annotazioni da un intervallo di testo
È possibile recuperare un elenco dei tipi di annotazioni presenti in un intervallo di testo usando il metodo IUIAutomationTextRange::GetAttributeValue . Quando si chiama il metodo, specificare un ID attributo di testo di UIA_AnnotationTypesAttributeId e un puntatore a un parametro di tipo VARIANT. Quando il metodo restituisce, il parametro VARIANT contiene un elenco di identificatori di tipo di annotazione, uno per ogni tipo di annotazione nell'intervallo di testo. Per altre informazioni, vedere Identificatori di tipo di annotazione.
Recupero di tutte le annotazioni da un intervallo di testo
Per recuperare le annotazioni da un intervallo di testo, chiamare il metodo IUIAutomationTextRange::GetAttributeValue , specificando un ID attributo di testo di UIA_AnnotationObjectsAttributeId e un puntatore a un parametro di tipo VARIANT. Quando il metodo restituisce, il parametro VARIANT contiene un'interfaccia IUIAutomationElementArray che rappresenta una matrice di elementi di automazione, una per ogni annotazione nell'intervallo di testo. La proprietà IUIAutomationElementArray::Length indica il numero di elementi nella matrice e il metodo IUIAutomationElementArray::GetElement recupera l'interfaccia IUIAutomationElement per un particolare elemento.
Recupero di informazioni su una particolare annotazione
Per recuperare informazioni su una particolare annotazione, recuperare prima di tutto l'interfaccia IUIAutomationElement per l'elemento annotazione, come descritto nella sezione precedente. Recuperare quindi l'interfaccia IUIAutomationAnnotationPattern per l'annotazione chiamando il metodo IUIAutomationElement::GetCurrentPatternAs con un ID modello di controllo di UIA_AnnotationPatternId, un identificatore dell'interfaccia di IID_IUIAutomationAnnotationPattern e l'indirizzo di una variabile che riceve il puntatore IUIAutomationAnnotation per l'annotazione. Eseguire una query sulle proprietà dell'interfaccia IUIAutomationAnnotation per recuperare il nome del tipo di annotazione e l'ID del tipo, il nome dell'autore dell'annotazione, la data e l'ora dell'annotazione e l'interfaccia IUIAutomationElement per l'elemento che viene annotato.
Recupero del testo di destinazione annotazione
In genere, un'annotazione si applica a un sottoinsieme del testo in un intervallo di testo. Dopo aver recuperato l'interfaccia IUIAutomationElement per un'annotazione, è possibile passare l'interfaccia al metodo IUIAutomationTextRange2::RangeFromAnnotation per recuperare un intervallo di testo contenente il testo che è la destinazione dell'annotazione.
Recupero di stili visivi
Un provider implementa il modello di controllo Stili per descrivere un elemento dell'interfaccia utente con uno stile specifico, un colore di riempimento, un modello di riempimento o una forma. Ciò è particolarmente utile quando si descrivono gli elementi in un documento, che spesso hanno tali stili. Gli stili come questo spesso contengono informazioni utili per i clienti con disabilità; Ad esempio, gli stili possono descrivere una determinata stringa come titolo di un documento o un determinato oggetto diagramma di flusso come un diamante o un cerchio.
È possibile usare il metodo IUIAutomationTextRange::GetAttributeValue per recuperare i nomi e gli identificatori degli stili visivi usati in un intervallo di testo. Usare l'attributo di testo UIA_StyleNameAttributeId per recuperare i nomi di stile e UIA_StyleIdAttributeId per recuperare gli identificatori di stile.
Un controllo basato su testo che supporta gli stili visivi può implementare il modello di controllo Stili per consentire ai client di accedere alle informazioni su uno stile visivo usato dal controllo. I client accedono al modello di controllo Stili tramite l'interfaccia IUIAutomationStylesPattern . È possibile recuperare questa interfaccia chiamando il metodo IUIAutomationElement::GetCurrentPattern o GetCurrentPatternAs , specificando UIA_StylesPatternId come identificatore del modello di controllo.
L'interfaccia IUIAutomationStylesPattern include proprietà e metodi che forniscono le informazioni seguenti su uno stile visivo:
- Nome dello stile di visualizzazione, ad esempio "Normal" o "Titolo 1".
- Identificatore dello stile visivo. Per altre informazioni, vedere Identificatori di stile.
- Colore utilizzato per riempire il controllo basato sul testo.
- Colore del modello usato per riempire il controllo basato sul testo.
- Forma del controllo basato su testo.
- Proprietà estese; ovvero un elenco di nomi e valori di stile specifici del controllo.
Richiamare menu di scelta rapida da intervalli di testo
A partire da Windows 8.1, gli intervalli di testo possono supportare l'interfaccia IUIAutomationTextRange2. Questa interfaccia supporta il metodo ShowContextMenu . È possibile chiamare questo metodo per richiamare qualsiasi menu di scelta rapida associato a un intervallo di testo. Lo scenario per questo è la correzione automatica degli intervalli di testo o della selezione dei candidati IME. In questi casi viene visualizzato un menu di scelta rapida che supporta l'interazione dell'utente.
Argomenti correlati