Panoramica sugli oggetti incorporati e TextPattern

Aggiornamento: novembre 2007

In questa sezione viene descritto come vengono esposti gli oggetti incorporati, o elementi figlio, all'interno di un documento di testo o un contenitore in automazione interfaccia utente Microsoft.

In automazione interfaccia utente un oggetto incorporato è qualsiasi elemento che ha limiti non testuali, ad esempio, un'immagine, un collegamento ipertestuale, una tabella o un tipo di documento quale un foglio di calcolo di Microsoft Excel o un file di Microsoft Windows Media. Questa definizione è diversa da quella standard, in cui un elemento viene creato in un'applicazione e incorporato, o collegato, in un'altra. Il fatto che l'oggetto possa essere modificato all'interno dell'applicazione originale è irrilevante nel contesto di automazione interfaccia utente.

Nel presente argomento sono contenute le seguenti sezioni.

Oggetti incorporati e struttura ad albero di automazione interfaccia utente
Esporre oggetti incorporati utilizzando TextPattern e TextPatternRange
Scenari comuni
Argomenti correlati

Oggetti incorporati e struttura ad albero di automazione interfaccia utente

Gli oggetti incorporati vengono considerati come singoli elementi nella visualizzazione controlli della struttura ad albero di automazione interfaccia utente. Vengono esposti come elementi figlio del contenitore di testo, in modo che sia possibile accedervi tramite lo stesso modello di altri controlli di automazione interfaccia utente.

Esempio di un contenitore di testo con oggetti incorporati di tipo tabella, immagine e collegamento ipertestuale

Tabella incorporata con immagine in un contenitore di testo

Esempio della visualizzazione contenuto per una parte del contenitore di testo precedente

Visualizzazione del contenuto dell'esempio precedente

Esporre oggetti incorporati utilizzando TextPattern e TextPatternRange

La classe delpattern di controlloTextPattern e la classe TextPatternRange, utilizzate in combinazione, espongono metodi e proprietà che facilitano lo spostamento e le query di oggetti incorporati.

Il contenuto testuale (o testo interno) di un contenitore di testo e di un oggetto incorporato, ad esempio un collegamento ipertestuale o una cella di tabella, è esposto come unico flusso continuo di testo nella visualizzazione controlli e nella visualizzazione contenuto della struttura ad albero di automazione interfaccia utente; i limiti dell'oggetto vengono ignorati. Se un client di automazione interfaccia utente sta recuperando il testo a scopo di esposizione, interpretazione o analisi, è necessario verificare la presenza nell'intervallo di testo di casi particolari, ad esempio una tabella con contenuto testuale o altri oggetti incorporati. A tale scopo, è possibile effettuare una chiamata al metodo GetChildren per ottenere un oggetto AutomationElement per ogni oggetto incorporato e quindi al metodo RangeFromChild per ottenere un intervallo di testo per ogni elemento. Questa operazione viene eseguita in modo ricorsivo fino a recuperare tutto il contenuto testuale.

Esempio di flusso di testo con oggetti incorporati e relative estensioni di intervallo

Intervalli di testo estesi da oggetti incorporati

Quando è necessario attraversare il contenuto di un intervallo di testo, è necessario effettuare una serie di passaggi perché il metodo Move venga eseguito correttamente.

L'intervallo di testo è normalizzato, ovvero è compresso in un intervallo degenerato in corrispondenza dell'endpoint Start, il che rende superfluo l'endpoint End. Questo passaggio è necessario per rimuovere l'ambiguità nelle situazioni in cui un intervallo di testo si estende sui limiti dell'oggetto TextUnit; ad esempio, "{l'U}RL https://www.microsoft.com è incorporato nel testo" dove "{" e "}" sono gli endpoint dell'intervallo di testo.
L'intervallo risultante viene spostato indietro nell'oggetto DocumentRange all'inizio del limite dell'oggetto TextUnit richiesto.
L'intervallo è spostato avanti o indietro nella proprietà DocumentRange in base al numero richiesto di limiti dell'oggetto TextUnit.
L'intervallo viene quindi espanso da uno stato di intervallo degenerato spostando l'endpoint End di un limite richiesto dell'oggetto TextUnit.

Esempi di regolazione di un intervallo di testo per Move() e ExpandToEnclosingUnit()

Regolazioni di intervallo mediante Move ed ExpandToEnclosingUnit

Scenari comuni

Nelle sezioni seguenti vengono presentati alcuni esempi degli scenari più comuni in cui vengono utilizzati oggetti incorporati.

La legenda per gli esempi illustrati è la seguente:

{ = Start

} = End

Collegamento ipertestuale

Esempio 1 - Intervallo di testo che contiene un collegamento ipertestuale incorporato

{L'URL https://www.microsoft.com è incorporato nel testo}.

Metodo chiamato	Risultato
GetText	Restituisce la stringa "L'URL https://www.microsoft.com è incorporato nel testo."
GetEnclosingElement	Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso l'oggetto AutomationElement che rappresenta il provider di testo.
GetChildren	Restituisce un oggetto AutomationElement che rappresenta il controllo collegamento ipertestuale.
RangeFromChild dove AutomationElement è l'oggetto restituito dal metodo GetChildren precedente.	Restituisce l'intervallo che rappresenta "http://www.microsoft.com."

Esempio 2 - Intervallo di testo che si estende parzialmente su un collegamento ipertestuale incorporato

L'URL http://{www}.microsoft.com è incorporato nel testo.

Metodo chiamato	Risultato
GetText	Restituisce la stringa "www".
GetEnclosingElement	Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso il controllo collegamento ipertestuale.
GetChildren	Restituisce null poiché l'intervallo di testo non si estende sull'intera stringa dell'URL.

Esempio 3 - Intervallo di testo che si estende parzialmente sul contenuto di un contenitore di testo. Il contenitore di testo include un collegamento ipertestuale incorporato che non fa parte dell'intervallo di testo.

{L'URL} https://www.microsoft.com è incorporato nel testo.

Metodo chiamato	Risultato
GetText	Restituisce la stringa "L'URL".
GetEnclosingElement	Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso l'oggetto AutomationElement che rappresenta il provider di testo.
Move con i parametri (TextUnit.Word, 1).	Sposta l'estensione dell'intervallo di testo fino a "http", poiché il testo del collegamento ipertestuale è composto da singole parole. In questo caso, il collegamento ipertestuale non viene trattato come un singolo oggetto. L'URL {http}://www.microsoft.com è incorporato nel testo.

GetText

Restituisce la stringa "L'URL".

GetEnclosingElement

Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso l'oggetto AutomationElement che rappresenta il provider di testo.

Move con i parametri (TextUnit.Word, 1).

Sposta l'estensione dell'intervallo di testo fino a "http", poiché il testo del collegamento ipertestuale è composto da singole parole. In questo caso, il collegamento ipertestuale non viene trattato come un singolo oggetto.

L'URL {http}://www.microsoft.com è incorporato nel testo.

Immagine

Esempio 1 - Intervallo di testo che contiene un'immagine incorporata

{L'immagine Esempio di immagine incorporata è incorporata nel testo}.

Metodo chiamato	Risultato
GetText	Restituisce la stringa "L'immagine è incorporata nel testo". Non è possibile prevedere di includere un testo ALT associato all'immagine nel flusso di testo.
GetEnclosingElement	Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso l'oggetto AutomationElement che rappresenta il provider di testo.
GetChildren	Restituisce un oggetto AutomationElement che rappresenta il controllo immagine.
RangeFromChild dove AutomationElement è l'oggetto restituito dal metodo GetChildren precedente.	Restituisce l'intervallo degenerato che rappresenta "".

Esempio 2 - Intervallo di testo che si estende parzialmente sul contenuto di un contenitore di testo. Il contenitore di testo include un'immagine incorporata che non fa parte dell'intervallo di testo.

{L'immagine} Esempio di immagine incorporata è incorporata nel testo.

Metodo chiamato	Risultato
GetText	Restituisce la stringa "L'immagine".
GetEnclosingElement	Restituisce l'oggetto AutomationElement più interno che racchiude l'intervallo di testo, in questo caso l'oggetto AutomationElement che rappresenta il provider di testo.
Move con i parametri (TextUnit.Word, 1).	Sposta l'estensione dell'intervallo di testo fino a "è ". Poiché solo gli oggetti incorporati basati su testo sono considerati parte del flusso di testo, l'immagine di questo esempio non influisce su Move o sul relativo valore restituito (1 in questo caso).

Tabella

Tabella utilizzata per gli esempi

Cella con immagine	Cella con testo
	X
	Y
Immagine per Z	Z

Esempio di immagine incorporata

Esempio di immagine incorporata 2

Esempio di immagine incorporata 3

Immagine per Z

Esempio 1- Ottenere il contenitore di testo dal contenuto di una cella.

Metodo chiamato	Risultato
GetItem con i parametri (0,0)	Restituisce l'oggetto AutomationElement che rappresenta il contenuto della cella della tabella; in questo caso, l'elemento è un controllo di testo.
RangeFromChild dove AutomationElement è l'oggetto restituito dal metodo GetItem precedente.	Restituisce l'intervallo che si estende sull'immagine .
GetEnclosingElement per l'oggetto restituito dal metodo RangeFromChild precedente.	Restituisce l'oggetto AutomationElement che rappresenta la cella della tabella; in questo caso, l'elemento è un controllo di testo che supporta TableItemPattern.
GetEnclosingElement per l'oggetto restituito dal metodo GetEnclosingElement precedente.	Restituisce l'oggetto AutomationElement che rappresenta la tabella.
GetEnclosingElement per l'oggetto restituito dal metodo GetEnclosingElement precedente.	Restituisce l'oggetto AutomationElement che rappresenta il provider di testo stesso.

Esempio 2 - Ottenere il contenuto di testo di una cella.

Metodo chiamato	Risultato
GetItem con i parametri (1,1).	Restituisce l'oggetto AutomationElement che rappresenta il contenuto della cella della tabella; in questo caso, l'elemento è un controllo di testo.
RangeFromChild dove AutomationElement è l'oggetto restituito dal metodo GetItem precedente.	Restituisce "Y".