TextRange | NN s.o. IE 4 (Win) DOM s.o.
L´objet TextRange, similaire conceptuellement à l´objet Range de Netscape 6 et du DOM W3C, représente une séquence de zéro caractère de texte affiché ou plus dans un document. Une plage de texte comprenant zéro caractère représente un point d'insertion situé entre deux caractères (il peut également se situer avant le premier ou après le dernier caractère).
Un objet TextRange est créé par la méthode createTextRange() associée aux objets body, button, text ou textarea. Vous pouvez aussi transformer une sélection de l´utilisateur en plage par le biais de la méthode createRange() de l´objet selection (remarquez la légère différence dans le nom de la méthode). Après avoir créé une plage de texte, vous pouvez utiliser ses méthodes pour déterminer ses points de début et de fin pour englober un segment de texte spécifique (par exemple, le texte correspondant à une chaîne recherchée). Après avoir rétréci la plage au texte cible, affectez des valeurs à ses propriétés htmlText and text afin de modifier, supprimer ou insérer du texte. Vous pouvez également invoquer une bibliothèque de commandes directes pour apporter des modifications textuelles spécifiques à cette plage de texte. Reportez-vous au chapitre 5 pour plus de détails et des exemples d'utilisation de l'objet TextRange.
Les propriétés et méthodes partagées de la liste au début de ce chapitre sont: offsetLeft, offsetTop, getBoundingClientRect(), getClientRects() et scrollIntoView(). Notez que l'objet TextRange ainsi que toutes les fonctions qui y sont associées sont uniquement disponibles dans la version Win32 de Microsoft Internet Explorer.
Référence de modèle d'objet
    objectRef.createTextRange()
    selectionObjectRef.createRange()
Propriétés spécifiques à l´objet
boundingHeight | boundingLeft | boundingTop | boundingWidth
htmlText | text |  |
Méthodes spécifiques à l´objet
collapse() | compareEndPoints() | duplicate()
execCommand() | expand() | findText()
getBookmark() | inRange() | isEqual()
move() | moveEnd() | moveStart()
moveToBookmark() | moveToElementText() | moveToPoint()
parentElement() | pasteHTML() | queryCommandEnabled()
queryCommandIndeterm() | queryCommandState() | queryCommandSupported()
queryCommandText() | queryCommandValue() | select()
setEndPoint() |  |

boundingHeight, boundingWidth | NN s.o. IE 4 (Win) DOM s.o.
| Lecture seule
Renvoient la mesure en pixels de l'espace imaginaire occupé par l'objet TextRange. Bien que l'objet TextRange ne soit pas visible dans le document (à moins qu'un script ne le sélectionne), la zone d'un objet TextRange est identique à celle qu'occuperait une zone sélectionnée en surbrillance. Ces valeurs sont ajustées de telle sorte à ne pas dépasser la hauteur et la largeur maximales de la plage. Vous arriveriez aux mêmes résultats en effectuant des calculs arithmétiques sur les valeurs renvoyées par la méthode getBoundingClientRect().
Exemple
    var rangeWidth = document.forms[0].myTextArea.createTextRange().boundingWidth;
Valeur
Nombre entier.
Par défaut
Aucune.

boundingLeft, boundingTop | NN s.o. IE 4 (Win) DOM s.o.
| Lecture seule
Renvoient la distance en pixels séparant la partie supérieure ou gauche de la fenêtre ou du cadre du navigateur des bords supérieur ou gauche de l'espace imaginaire occupé par l'objet TextRange. Bien que l'objet TextRange ne soit pas visible dans le document (à moins qu'un script ne le sélectionne), la zone d'un objet TextRange est identique à celle qu'occuperait une zone sélectionnée en surbrillance. Les valeurs de ces propriétés sont mesurées à partir des bords fixes de la fenêtre ou du cadre et non à partir de la partie supérieure et gauche du document qui peut être masquée lorsque le document défile. Dès lors, ces valeurs changent lorsque le document défile.
Exemple
    var rangeOffH = document.forms[0].myTextArea.createTextRange().boundingLeft;
Valeur
Nombre entier.
Par défaut
Aucune.

htmlText | NN s.o. IE 4 (Win) DOM s.o.
| Lecture seule
Spécifie tout code HTML du document pour un élément donné, lorsque ce dernier sert de base à un objet TextRange. Par exemple, si vous créez un objet TextRange pour l'élément body (document.body.createTextRange()), la propriété htmlText englobe tout le contenu HTML inclus entre des balises d'élément body (ces dernières non comprises).
Exemple
    var rangeHTML = document.body.createTextRange().htmlText;
Valeur
Chaîne.
Par défaut
Aucune.

text | NN s.o. IE 4 (Win) DOM s.o.
| Lecture/écriture
Indique le texte contenu dans la plage de texte. Dans le cas d'un objet TextRange d'un élément body, il s'agit du texte affiché, sans les balises HTML.
Exemple
    var rangeText = document.body.createTextRange().text;
Valeur
Chaîne.
Par défaut
Aucune.

collapse() | NN s.o. IE 4 (Win) DOM s.o.
collapse([début]) |
Réduit l'objet TextRange à une longueur zéro (créant un point d'insertion) au début ou à la fin de la plage de texte avant réduction.
Paramètres
Valeur booléenne facultative qui contrôle si le point d'insertion se situe au début (true) ou à la fin (false) de la plage de texte originale. La valeur par défaut est true.
Valeur renvoyée
Aucune.

compareEndPoints() | NN s.o. IE 4 (Win) DOM s.o.
compareEndPoints("type", comparisonRange) |
Compare la position relative des points de début et de fin de deux plages (la plage active et celle préalablement enregistrée comme variable). Le premier paramètre définit les points de début et de fin de chaque plage que vous souhaitez comparer. Si le résultat de la comparaison montre que le premier point se trouve avant l´autre point dans la plage, la valeur renvoyée est -1. Si le résultat montre que les deux points sont au même emplacement, la valeur renvoyée est 0. Si le résultat de la comparaison montre que le premier point se trouve après l´autre point dans la plage, la valeur renvoyée est 1. Par exemple, si vous avez enregistré la première plage dans une variable r1 et créé une nouvelle plage intitulée r2, vous pouvez voir la relation physique entre la fin de r2 et le début de r1:
    r1.compareEndPoints("EndToStart", r2)
Si r1 se termine là où r2 commence (le point d'insertion entre deux caractères), la valeur renvoyée est 0.
Paramètres
L'une des constantes suivantes (sous forme de chaîne): StartToEnd | StartToStart | EndToStart | EndToEnd. Objet TextRange créé précédemment et enregistré comme variable.
Valeur renvoyée
-1, 0 ou 1.

duplicate() | NN s.o. IE 4 (Win) DOM s.o.
Crée un nouvel objet TextRange ayant les mêmes valeurs que la plage active. Le nouvel objet est indépendant; l'ancien et le nouveau ne sont pas égaux mais, initialement, leurs valeurs sont identiques (tant que vous ne modifiez pas une plage ou l'autre).
Paramètres
Aucune.
Valeur renvoyée
Objet TextRange.

execCommand() | NN s.o. IE 4 (Win) DOM s.o.
execCommand("nom_commande"[, drapeau_interface[, valeur]]) |
Exécute la commande nommée dans l'objet TextRange actif. Dans bien des cas, les commandes fonctionnent mieux lorsque l'objet TextRange est un point d'insertion. Reportez-vous à l´annexe D pour une liste de commandes.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D. Valeur booléenne facultative: true pour afficher, le cas échéant, toute interface utilisateur déclenchée par la commande; false pour éviter cet affichage. Valeur de paramètre pour la commande.
Valeur renvoyée
Valeur booléenne: true si la commande a abouti;false si elle a échoué.

expand() | NN s.o. IE 4 (Win) DOM s.o.
expand("unit") |
Etend la plage de texte courante (y compris une plage réduite) afin d'englober l'unité textuelle transmise comme paramètre. Par exemple, si quelqu'un sélectionne certains caractères d'un document, vous pouvez créer la plage et l'étendre afin qu'elle englobe toute la phrase dans laquelle figurent les caractères sélectionnés:
    var rng = document.selection.createRange( );
    rng.expand("sentence");
Si la plage de début s'étend sur plusieurs unités, la méthode expand() étend la plage jusqu'à l'unité suivante la plus proche.
Paramètres
Valeur non sensible à la casse, sous forme de chaîne, de l´unité désirée: character | word | sentence | textedit. La valeur textedit étend la plage à la totalité de la plage originale.
Valeur renvoyée
Valeur booléenne: true si la commande a abouti;false si elle a échoué.

findText() | NN s.o. IE 4 (Win) DOM s.o.
findText("string"[, searchScope][, flags]) |
Recherche, dans l'objet TextRange actif, une correspondance avec une chaîne transmise comme le premier paramètre requis. Par défaut, la mise en correspondance ne tient pas compte de la casse. En présence d'une correspondance, l'objet TextRange repositionne ses points de début et de fin de telle sorte à englober le texte trouvé. Pour poursuivre la recherche dans le document, repositionnez le point de départ de la plage de texte à la fin de la chaîne trouvée (avec collapse()).
Des paramètres facultatifs vous permettent de limiter la portée de la recherche au sein de la plage à un nombre de caractères de votre choix après le point de début de la plage ou déterminent des spécifications de correspondance supplémentaires, comme des mots partiels ou entiers.
Paramètres
Chaîne à rechercher, non sensible à la casse. Nombre entier pour le nombre de caractères à partir du point de début de la plage dans lesquels effectuer la recherche. Un nombre positif indique une recherche vers l´avant et un nombre négatif indique une recherche vers l´arrière, dans du texte qui se trouve avant le point de début de la plage de texte dans le document. Nombre entier pour les codes de détail de la recherche: 0 (correspondance avec mots partiels); 1 (correspondance vers l´arrière); 2 (correspondance avec mots entiers uniquement); 4 (correspondance sensible à la casse).
Valeur renvoyée
Valeur booléenne: true indique qu'une correspondance a été trouvée;false indique le contraire.

getBookmark(), moveToBookmark() | NN s.o. IE 4 (Win) DOM s.o.
getBookmark() moveToBookmark(bookmarkString) |
Associées, ces deux méthodes permettent d'enregistrer temporairement la spécification d'une plage de texte et de la récupérer si nécessaire. La méthode getBookmark() renvoie une chaîne opaque (contenant des données binaires sans intérêt pour l'utilisateur). Une fois la valeur stockée dans une variable, il est possible de modifier la plage au gré des besoins pour le script. La plage de texte balisée d'un signet peut être récupérée à un stade ultérieur gr ce à la méthode moveToBookmark():
    var rangeMark = myRange.getBookmark( );
    ...
    myRange.moveToBookmark(rangeMark);
Paramètres
Chaîne opaque renvoyée par la méthode getBookmark().
Valeur renvoyée
Valeur booléenne: true si l'opération a abouti;false si elle a échoué.

inRange() | NN s.o. IE 4 (Win) DOM s.o.
inRange(plage_de_comparaison) |
Détermine si la plage faisant l'objet de la comparaison est contenue dans la plage physique de la plage de texte active ou se confond avec elle.
Paramètres
Objet TextRange créé précédemment et enregistré comme variable.
Valeur renvoyée
Valeur booléenne: true si la plage faisant l'objet de la comparaison est contenue dans la plage active ou se confond avec elle; false si ce n'est pas le cas.

isEqual() | NN s.o. IE 4 (Win) DOM s.o.
isEqual(plage_de_comparaison) |
Détermine si la plage faisant l'objet de la comparaison est identique à la plage de texte active.
Paramètres
Objet TextRange créé précédemment et enregistré comme variable.
Valeur renvoyée
Valeur booléenne: true si la plage faisant l'objet de la comparaison est égale à la plage active; false si ce n'est pas le cas.

move() | NN s.o. IE 4 (Win) DOM s.o.
move("unit"[, count]) |
Réduit la plage de texte active à un point d'insertion situé à la fin de la plage de texte active et le déplace d'une ou plusieurs unités vers l'avant ou vers l'arrière par rapport à la position actuelle.
Paramètres
Valeur non sensible à la casse, sous forme de chaîne, de l´unité désirée: character | word | sentence | textedit. La valeur textedit déplace le point d'insertion au début ou à la fin de la plage originale. Nombre entier facultatif correspondant au nombre d'unités dont le point d'insertion doit être déplacé. Les valeurs positives déplacent le pointeur vers l'avant, tandis que les valeurs négatives le déplacent vers l'arrière. La valeur par défaut est 1.
Valeur renvoyée
Nombre entier correspondant au déplacement, en nombre d'unités.

moveEnd(), moveStart() | NN s.o. IE 4 (Win) DOM s.o.
moveEnd("unit"[, count]) moveStart("unit"[, count]) |
Déplace uniquement le point de fin ou de début (respectivement) de la plage de texte active d'une (ou plusieurs) unité(s). Un paramètre facultatif vous permet de spécifier à la fois le nombre d'unités et la direction. Pour replacer le point de départ d'une plage de texte au début de la plage originale, n'oubliez pas d'indiquer une valeur négative. Lorsque vous déplacez le point de fin vers l´avant par unités de mots, songez que le mot se termine par un espace blanc (comprenant un point). Dès lors, si une méthode findText() définit la plage sur une chaîne qui ne se termine pas par un espace, la première méthode moveEnd("word") place le point de fin à l'emplacement situé derrière l'espace suivant la chaîne trouvée, au lieu de le placer au mot suivant.
Paramètres
Valeur non sensible à la casse, sous forme de chaîne, de l´unité désirée: character | word | sentence | textedit. La valeur textedit déplace le point d'insertion au début ou à la fin de la plage originale. Nombre entier facultatif correspondant au nombre d'unités dont le point d'insertion doit être déplacé. Les valeurs positives déplacent le pointeur vers l'avant, tandis que les valeurs négatives le déplacent vers l'arrière. La valeur par défaut est 1.
Valeur renvoyée
Nombre entier correspondant au déplacement, en nombre d'unités.

moveToBookmark() |
Voir getBookmark().

moveToElementText() | NN s.o. IE 4 (Win) DOM s.o.
moveToElementText(objet_élément) |
Déplace les points de début et de fin de l'objet TextRange de manière à englober l'objet élément HTML spécifié. La plage de texte qui en résulte inclut également le code HTML relatif à l'élément.
Paramètres
Référence par script à l'objet. Celle-ci peut prendre la forme d'une référence directe (document.getElementById("elementID") ou d'une variable contenant le même type de valeur.
Valeur renvoyée
Aucune.

moveToPoint() | NN s.o. IE 4 (Win) DOM s.o.
moveToPoint(x, y) |
Réduit la plage de texte à un point d'insertion et définit sa position sur le point indiqué par les coordonnées horizontales et verticales dans la fenêtre ou le cadre du navigateur. Cela revient au même que cliquer sur un point de la fenêtre pour définir un point d'insertion. Utilisez des méthodes telles que expand() pour élargir la plage de texte afin d'inclure un caractère, un mot, une phrase ou une plage de texte complète.
Paramètres
Coordonnée horizontale du point d'insertion, en pixels, par rapport au bord gauche de la fenêtre ou du cadre. Coordonnée verticale du point d'insertion, en pixels, par rapport au bord supérieur de la fenêtre ou du cadre.
Valeur renvoyée
Aucune.

parentElement() | NN s.o. IE 4 (Win) DOM s.o.
Renvoie une référence d'objet à l'élément père contenant l'objet TextRange.
Paramètres
Aucune.
Valeur renvoyée
Référence de l'objet élément.

pasteHTML() | NN s.o. IE 4 (Win) DOM s.o.
pasteHTML("HTMLText") |
Remplace la plage de texte active par le contenu HTML fourni comme chaîne de paramètre. En général, cette méthode est utilisée sur un objet de plage de texte de longueur zéro faisant office de pointeur d'insertion. Toutes les balises sont affichées comme si elles faisaient partie du code source original.
Paramètres
Code source du document à insérer dans le document.
Valeur renvoyée
Aucune.

queryCommandEnabled() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandEnabled("nom_commande") |
Détermine si la commande peut être invoquée en fonction de l'état actuel du document ou de la sélection.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
Valeur booléenne: true s'il est activé;false s'il ne l'est pas.

queryCommandIndeterm() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandEnabled("nom_commande") |
Détermine si la commande est dans un état indéterminé.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
Valeur booléenne: true | false.

queryCommandState() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandState("nom_commande") |
Détermine l'état courant de la commande indiquée.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
true si la commande a été exécutée;false si la commande n'a pas été exécutée;null si l'état ne peut pas être déterminé avec certitude.

queryCommandSupported() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandEnabled("nom_commande") |
Détermine si la commande nommée est prise en charge par l'objet document.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
Valeur booléenne: true | false.

queryCommandText() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandText("nom_commande") |
Renvoie le texte associé à la commande.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
Chaîne.

queryCommandValue() | NN s.o. IE 4 (Win) DOM s.o.
queryCommandValue("nom_commande") |
Renvoie la valeur associée à la commande, tel le nom de police de la sélection.
Paramètres
Nom de la commande, sous forme de chaîne non sensible à la casse. Reportez-vous à l´annexe D.
Valeur renvoyée
Dépend de la commande.

select() | NN s.o. IE 4 (Win) DOM s.o.
Sélectionne tout le texte inclus dans l'objet TextRange actif. Cette méthode confirme visuellement à l'utilisateur que le script reconnaît un bloc de texte particulier. Par exemple, si vous créez un script de recherche avec la méthode findText(), l'utilisation des méthodes scrollIntoView() et select() sur cette plage permet de montrer à l'utilisateur où se trouve le texte correspondant à la recherche.
Paramètres
Aucune.
Valeur renvoyée
Aucune.

setEndPoint() | NN s.o. IE 4 (Win) DOM s.o.
setEndPoint("type", comparisonRange) |
Paramètre le point de fin de l'objet TextRange actif sur le point de fin d'une autre plage préalablement enregistrée comme variable de référence.
Paramètres
L'une des constantes suivantes (sous forme de chaîne): StartToEnd | StartToStart | EndToStart | EndToEnd. Objet TextRange créé précédemment et enregistré comme variable.
Valeur renvoyée
Aucune.