TextPointer, classe

La classe TextPointer introduit la terminologie suivante :

• Position fondamentale - un TextPointer pointe toujours sur une position dans le contenu. De telles positions tombent entre des caractères du contenu, ou entre des balises de flux d'élément du contenu définissant la structure du contenu.

• Position actuelle – Comme un TextPointer indique toujours une position, et comme beaucoup des opérations pouvant être exécutées par un TextPointer sont relatives à la position sur laquelle pointe le TextPointer, il est logique d'appeler la position indiquée par un TextPointer la position actuelle.

• Position d'insertion - Une position d'insertion est une position où du nouveau contenu peut être ajouté sans violer de règles sémantiques concernant le contenu associé. En pratique, une position d'insertion correspond à l'emplacement d'un signe insertion dans le contenu. Un exemple de position TextPointer valide, autre qu'une position d'insertion, est une position entre deux balises Paragraph adjacentes (c'est-à-dire, la balise de fermeture du paragraphe précédent et celle d'ouverture du suivant).

• Symbole - Pour satisfaire les opérations TextPointer impliquant des symboles, chacun des éléments suivants est considéré comme un symbole :

  • Une balise d'ouverture ou de fermeture d'un élément TextElement.

  • Un élément UIElement contenu dans un InlineUIContainer ou BlockUIContainer. Notez qu'un UIElement de ce type compte toujours comme symbole unique ; tout contenu ou élément supplémentaire présent dans le UIElement ne compte pas comme symbole.

  • Chaque caractère Unicode 16 bits dans un élément Run texte.

• Conteneur de texte - Un conteneur de texte est l'élément constituant l'ultime limite pour le flux du contenu traité ; la position indiquée par un TextPointer tombe toujours dans un conteneur de texte. Actuellement, un conteneur de texte doit être soit un FlowDocument soit un TextBlock. En général, les opérations entre instances TextPointer dans différents conteneurs de texte ne sont pas prises en charge.

• Document - Le contenu d'un conteneur de texte est appelé document, comme dans la méthode IsInSameDocument et les propriétés DocumentStart et DocumentEnd.

La classe TextPointer doit faciliter le parcours et les manipulations de contenu représenté par des éléments de flux Windows Presentation Foundation (WPF) ; en général, de tels éléments dérivent de TextElement. Parmi les opérations facilitées par TextPointer figurent les suivantes :

• Effectuer une comparaison ordinale entre la position actuelle et une seconde position spécifiée. Voir la méthode CompareTo.

• Déterminer le type de contenu adjacent à la position actuelle dans une direction spécifiée. Consultez la méthode GetPointerContext et énumération TextPointerContext.

• Obtenir le TextElement portant sur ou adjacent à la position actuelle. Consultez Paragraph et la méthode GetAdjacentElement.

• Obtenir le conteneur de texte portant sur le document actuel. Voir la propriété Parent.

• Obtenir un nombre spécifié de caractères précédant ou suivant la position actuelle. Voir la méthode GetTextInRun.

• Insérer une chaîne de caractères à la position actuelle. Voir la méthode InsertTextInRun.

• Trouver des limites de ligne dans le contenu. Consultez la méthode GetLineStartPosition et la propriété IsAtLineStartPosition.

• Traduire entre des positions TextPointer et des offsets de symboles dans le contenu. Consultez les méthodes GetOffsetToPosition et GetPositionAtOffset.

• Exécuter des tests de positionnement visuels en traduisant entre une position TextPointer et un Point représentant des coordonnées relatives.

• Rechercher une position d'insertion proche, ou vérifier si la position actuelle est une position d'insertion. Consultez les méthodes GetInsertionPosition et GetNextInsertionPosition et la propriété IsAtInsertionPosition.

La position et LogicalDirection indiqués par un objet TextPointer sont immuables. Lorsque du contenu est édité ou modifié, la position indiquée par un TextPointer ne change pas par rapport au texte voisin, mais son offset dès le début du contenu reflète la nouvelle position relative dans le contenu. Par exemple, un TextPointer indiquant une position au début d'un paragraphe donné continue à pointer vers le début de ce paragraphe même lorsque du contenu est inséré ou supprimé avant ou après le paragraphe.

La classe TextPointer ne fournit pas de constructeurs publics. Une instance de TextPointer est créée en utilisant des propriétés ou méthodes d'autres objets (y compris d'autres objets TextPointer). La liste suivante fournit quelques exemples de méthodes et propriétés qui créent et renvoient un TextPointer. Cette liste n'est pas exhaustive :

• À partir d'un TextRange: Start et End.

• À partir d'un TextElement: ContentStart, ContentEnd, ElementStart, et ElementEnd.

• À partir d'un TextBlock (conteneur de texte) : ContentStart, ContentEndet GetPositionFromPoint.

• À partir d'un FlowDocument (conteneur de texte) : ContentStart, et ContentEnd

• À partir d'un TextPointerexistant : DocumentStart, DocumentEnd, GetNextInsertionPositionet GetPositionAtOffset.

L'exemple suivant montre comment utiliser un TextPointer pour rechercher une position dans le premier élément Run d'un conteneur de texte spécifié.

// This method returns the position just inside of the first text Run (if any) in a 
// specified text container.
TextPointer FindFirstRunInTextContainer(DependencyObject container)
{
    TextPointer position = null;

    if (container != null){
        if (container is FlowDocument)
            position = ((FlowDocument)container).ContentStart;
        else if (container is TextBlock)
            position = ((TextBlock)container).ContentStart;
        else
            return position;
    }
    // Traverse content in forward direction until the position is immediately after the opening 
    // tag of a Run element, or the end of content is encountered.
    while (position != null)
    {
        // Is the current position just after an opening element tag?
        if (position.GetPointerContext(LogicalDirection.Backward) == TextPointerContext.ElementStart)
        {
            // If so, is the tag a Run?
            if (position.Parent is Run)
                break;
        }

        // Not what we're looking for; on to the next position.
        position = position.GetNextContextPosition(LogicalDirection.Forward);
    }

    // This will be either null if no Run is found, or a position just inside of the first Run element in the
    // specifed text container.  Because position is formed from ContentStart, it will have a logical direction
    // of Backward.
    return position;
} 

L'exemple suivant implémente un algorithme de recherche simple à l'aide de la logistique TextPointer.

// This method will search for a specified word (string) starting at a specified position.
TextPointer FindWordFromPosition(TextPointer position, string word)
{
    while (position != null)
    {
         if (position.GetPointerContext(LogicalDirection.Forward) == TextPointerContext.Text)
         {
             string textRun = position.GetTextInRun(LogicalDirection.Forward);

             // Find the starting index of any substring that matches "word".
             int indexInRun = textRun.IndexOf(word);
             if (indexInRun >= 0)
             {
                 position = position.GetPositionAtOffset(indexInRun);
                 break;
             }
         }
         else
            position = position.GetNextContextPosition(LogicalDirection.Forward);
     }

     // position will be null if "word" is not found.
     return position; 
}

.NET Framework

.NET Framework Client Profile

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (rôle principal du serveur non pris en charge), Windows Server 2008 R2 (rôle principal du serveur pris en charge avec SP1 ou version ultérieure ; Itanium non pris en charge)

Référence