Lire en anglais

Partager via

Saisie de texte personnalisée

  • Article

Les API de texte principales de l’espace de noms Windows.UI.Text.Core permettent à une application Windows de recevoir une entrée de texte de n’importe quel service de texte pris en charge sur les appareils Windows. Les API sont similaires aux API Text Services Framework dans le fait que l’application n’est pas nécessaire pour avoir une connaissance détaillée des services de texte. Cela permet à l’application de recevoir du texte dans n’importe quelle langue et à partir de n’importe quel type d’entrée, comme le clavier, la parole ou le stylet.

API importantes : Windows.UI.Text.Core, CoreTextEditContext

Pourquoi utiliser les API de texte principales ?

Pour de nombreuses applications, les contrôles de zone de texte XAML ou HTML sont suffisants pour l’entrée de texte et la modification. Toutefois, si votre application gère des scénarios de texte complexes, comme une application de traitement de texte, vous aurez peut-être besoin de la flexibilité d’un contrôle d’édition de texte personnalisé. Vous pouvez utiliser les API de clavier CoreWindow pour créer votre contrôle de modification de texte, mais elles ne permettent pas de recevoir une entrée de texte basée sur la composition, ce qui est nécessaire pour prendre en charge les langues d’Asie de l’Est.

Utilisez plutôt les API Windows.UI.Text.Core lorsque vous devez créer un contrôle de modification de texte personnalisé. Ces API sont conçues pour vous offrir une grande flexibilité dans le traitement de l’entrée de texte, dans n’importe quelle langue, et vous permettent de fournir l’expérience de texte la mieux adaptée à votre application. Les contrôles d’entrée de texte et de modification créés avec les API de texte principales peuvent recevoir une entrée de texte de toutes les méthodes d’entrée de texte existantes sur les appareils Windows, des éditeurs de méthodes d’entrée basées sur Text Services Framework et l’écriture manuscrite sur les PC sur le clavier WordFlow (qui fournit la correction automatique, la prédiction et la dictée) sur les appareils mobiles.

Architecture

Voici une représentation simple du système d’entrée de texte.

  • « Application » représente une application Windows hébergeant un contrôle d’édition personnalisé créé à l’aide des API de texte principales.
  • Les API Windows.UI.Text.Core facilitent la communication avec les services de texte via Windows. La communication entre le contrôle de modification de texte et les services de texte est gérée principalement via un objet CoreTextEditContext qui fournit les méthodes et les événements pour faciliter la communication.

Diagramme d’architecture CoreText

Plages de texte et sélection

Les contrôles d’édition fournissent de l’espace pour l’entrée de texte et les utilisateurs s’attendent à modifier du texte n’importe où dans cet espace. Ici, nous expliquons le système de positionnement de texte utilisé par les API de texte principales et la façon dont les plages et les sélections sont représentées dans ce système.

Position d’insertion de l’application

Les plages de texte utilisées avec les API de texte principales sont exprimées en termes de positions d’insertion. Une « position de caret d’application (ACP) » est un nombre de base zéro qui indique le nombre de caractères à partir du début du flux de texte immédiatement avant le caret, comme illustré ici.

Capture d’écran montrant le nombre de caractères acp (Application Caret Position)

Plages de texte et sélection

Les plages de texte et les sélections sont représentées par la structure CoreTextRange qui contient deux champs :

Champ Type de données Description
StartCaretPosition Nombre [JavaScript] | System.Int32 [.NET] | int32 [C++] La position de début d’une plage est l’ACP immédiatement avant le premier caractère.
EndCaretPosition Nombre [JavaScript] | System.Int32 [.NET] | int32 [C++] La position de fin d’une plage est l’ACP immédiatement après le dernier caractère.

 

Par exemple, dans la plage de texte affichée précédemment, la plage [0, 5] spécifie le mot « Hello ». StartCaretPosition doit toujours être inférieur ou égal à EndCaretPosition. La plage [5, 0] n’est pas valide.

Point d’insertion

La position de caret actuelle, fréquemment appelée point d’insertion, est représentée par la définition de l’argument StartCaretPosition pour qu’elle soit égale à EndCaretPosition.

Sélection non liée

Certains contrôles d’édition prennent en charge les sélections non incohérentes. Par exemple, Microsoft application Office prend en charge plusieurs sélections arbitraires et de nombreux éditeurs de code source prennent en charge la sélection de colonnes. Toutefois, les API de texte principales ne prennent pas en charge les sélections non contiguës. Les contrôles d’édition ne doivent signaler qu’une sélection contiguë unique, le plus souvent la sous-plage active des sélections non contiguës.

Par exemple, l’image suivante montre un flux de texte avec deux sélections non contiguës : [0, 1] et [6, 11] pour lesquelles le contrôle d’édition ne doit signaler qu’un seul ([0, 1] ou [6, 11]).

Capture d’écran montrant une sélection de texte non contiguë, où le premier caractère et les cinq derniers caractères sont sélectionnés.

Utilisation du texte

La classe CoreTextEditContext active le flux de texte entre Windows et les contrôles de modification via l’événement TextUpdating, l’événement TextRequested et la méthode NotifyTextChanged.

Votre contrôle d’édition reçoit du texte par le biais d’événements TextUpdating générés lorsque les utilisateurs interagissent avec des méthodes d’entrée de texte telles que les claviers, la parole ou les imEs.

Lorsque vous modifiez du texte dans votre contrôle d’édition, par exemple, en collant du texte dans le contrôle, vous devez notifier Windows en appelant NotifyTextChanged.

Si le service de texte requiert le nouveau texte, un événement TextRequested est déclenché. Vous devez fournir le nouveau texte dans le gestionnaire d’événements TextRequested .

Acceptation des mises à jour de texte

Votre contrôle d’édition doit généralement accepter les demandes de mise à jour de texte, car ils représentent le texte que l’utilisateur souhaite entrer. Dans le gestionnaire d’événements TextUpdating , ces actions sont attendues de votre contrôle d’édition :

  1. Insérez le texte spécifié dans CoreTextTextUpdatingEventArgs.Text dans la position spécifiée dans CoreTextTextUpdatingEventArgs.Range.
  2. Placez la sélection à la position spécifiée dans CoreTextTextUpdatingEventArgs.NewSelection.
  3. Informez le système que la mise à jour a réussi en définissant CoreTextTextUpdatingEventArgs.Result sur CoreTextTextUpdatingResult.Succeeded.

Par exemple, il s’agit de l’état d’un contrôle d’édition avant que l’utilisateur ne tape « d ». Le point d’insertion est à [10, 10].

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à [10, 10], avant une insertion

Lorsque l’utilisateur tape « d », un événement TextUpdating est déclenché avec les données CoreTextTextUpdatingEventArgs suivantes :

Dans votre contrôle d’édition, appliquez les modifications spécifiées et définissez Result sur Succeeded. Voici l’état du contrôle après l’application des modifications.

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à \[11, 11\], après une insertion

Rejet des mises à jour de texte

Parfois, vous ne pouvez pas appliquer de mises à jour de texte, car la plage demandée se trouve dans une zone du contrôle d’édition qui ne doit pas être modifiée. Dans ce cas, vous ne devez pas appliquer de modifications. Au lieu de cela, informez le système que la mise à jour a échoué en définissant CoreTextTextUpdatingEventArgs.Result sur CoreTextTextUpdatingResult.Failed.

Par exemple, considérez un contrôle d’édition qui accepte uniquement une adresse de messagerie. Les espaces doivent être rejetés, car les adresses de messagerie ne peuvent pas contenir d’espaces. Par conséquent, lorsque des événements TextUpdating sont déclenchés pour la clé d’espace, vous devez simplement définir Result sur Failed dans votre contrôle d’édition.

Notification des modifications de texte

Parfois, votre contrôle d’édition apporte des modifications au texte, par exemple lorsque le texte est collé ou corrigé automatiquement. Dans ces cas, vous devez notifier les services de texte de ces modifications en appelant la méthode NotifyTextChanged.

Par exemple, il s’agit de l’état d’un contrôle d’édition avant que l’utilisateur ne colle « World ». Le point d’insertion est à [6, 6].

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à [6, 6], avant une insertion

L’utilisateur effectue l’action de collage et le contrôle d’édition après l’application des modifications :

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à \[11, 11\], après une insertion

Lorsque cela se produit, vous devez appeler NotifyTextChanged avec ces arguments :

  • modifiedRange = [6, 6]
  • newLength = 5
  • newSelection = [11, 11]

Un ou plusieurs événements TextRequested suivent, que vous gérez pour mettre à jour le texte avec lequel les services de texte fonctionnent.

Remplacement des mises à jour de texte

Dans votre contrôle d’édition, vous pouvez remplacer une mise à jour de texte pour fournir des fonctionnalités de correction automatique.

Par exemple, considérez un contrôle d’édition qui fournit une fonctionnalité de correction qui formalise les contractions. Il s’agit de l’état du contrôle d’édition avant que l’utilisateur tape la clé d’espace pour déclencher la correction. Le point d’insertion est à [3, 3].

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à [3, 3], avant une insertion

L’utilisateur appuie sur la touche d’espace et un événement TextUpdating correspondant est déclenché. Le contrôle d’édition accepte la mise à jour de texte. Il s’agit de l’état du contrôle d’édition pendant un bref instant avant la fin de la correction. Le point d’insertion est à [4, 4].

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à [4, 4], après une insertion

En dehors du gestionnaire d’événements TextUpdating , le contrôle d’édition apporte la correction suivante. Il s’agit de l’état du contrôle d’édition une fois la correction terminée. Le point d’insertion est à [5, 5].

Capture d’écran d’un diagramme de flux de texte montrant le point d’insertion à [5, 5]

Lorsque cela se produit, vous devez appeler NotifyTextChanged avec ces arguments :

  • modifiedRange = [1, 2]
  • newLength = 2
  • newSelection = [5, 5]

Un ou plusieurs événements TextRequested suivent, que vous gérez pour mettre à jour le texte avec lequel les services de texte fonctionnent.

Fourniture d’un texte demandé

Il est important que les services de texte disposent du texte approprié pour fournir des fonctionnalités telles que la correction automatique ou la prédiction, en particulier pour le texte qui existait déjà dans le contrôle d’édition, à partir du chargement d’un document, par exemple, ou du texte inséré par le contrôle d’édition, comme expliqué dans les sections précédentes. Par conséquent, chaque fois qu’un événement TextRequested est déclenché, vous devez fournir le texte actuellement dans votre contrôle d’édition pour la plage spécifiée.

Il arrive que la plage dans CoreTextTextRequest spécifie une plage que votre contrôle d’édition ne peut pas prendre en charge tel quel. Par exemple, la plage est supérieure à la taille du contrôle d’édition au moment de l’événement TextRequested, ou la fin de la plage est hors limites. Dans ces cas, vous devez retourner la plage qui est logique, ce qui est généralement un sous-ensemble de la plage demandée.

Exemples

Exemples d’archive