Les TextIter représentent une position entre deux caractères d'un TextBuffer. Ils sont généralement créés par une méthode de TextBuffer et sont invalidés lorsque le nombre de caractères de ce dernier est modifié (excepté le TextIter utilisé pour l'insertion ou la suppression). Insérer ou supprimer des images pixbuf ou des points d'ancrage consiste aussi en une modification du buffer, et invalide par conséquent les TextIter.
L'objet TextIter possède un grand nombre de méthodes. Celles-ci sont groupées par fonction similaire dans les sections suivantes.
On peut récupérer le TextBuffer qui contient le TextIter iter avec la méthode :
buffer = iter.get_buffer()
Les méthodes suivantes permettent de recupérer la localisation du TextIter iter dans le TextBuffer :
num_car = iter.get_offset() # renvoie la position de iter en partant du début du buffer num_ligne = iter.get_line() # renvoie le numéro de la ligne de iter num_car_ligne = iter.get_line_offset() # renvoie la position de iter en partant du début de la ligne nbr_car_ligne = iter.get_chars_in_line() # renvoie le nombre de caractères dans la ligne de iter
Le PangoLanguage utilisé à un emplacement du buffer portant un itérateur peut s'obtenir avec la méthode suivante :
langage = iter.get_language()
Plus généralement, on fera appel à la méthode qui suit pour récupérer les attributs d'un texte à une position portant un TextIter :
resultat = iter.get_attributes(valeurs)
La variable resultat indiquera si les valeurs fournies en argument (qui doivent être des objets TextAttributes) ont été modifiées. On obtient ces valeurs par l'intermédiraire de la méthode de TextView suivante :
valeurs = zonedetexte.get_default_attributes()
où zonedetexte est la TextView en question.
On peut accéder aux attributs suivants à partir d'un objet TextAttributes (non implementé dans PyGTK <= 1.99.15) :
| bg_color | couleur de l'arrière-plan |
| fg_color | couleur du premier plan |
| bg_stipple | bitmap à utiliser comme masque pour l'arrière-plan |
| fg_stipple | bitmap à utiliser comme masque pour le premier plan |
| rise | décalage du texte au-dessus de la ligne de base |
| underline | style de soulignement |
| strikethrough | texte barré |
| draw_bg | TRUE si des balises affectent le dessin de l'arrière-plan |
| justification | type d'alignement |
| direction | direction du texte |
| font | PangoFontDescription utilisée |
| font_scale | échelle de la police utilisée |
| left_margin | largeur de la marge de gauche |
| right_margin | largeur de la marge de droite |
| pixels_above_lines | Espacement en pixels au-dessus des paragraphes |
| pixels_below_lines | Espacement en pixels au-dessous des paragraphes |
| pixels_inside_wrap | Espacement en pixels entre les lignes coupées dans un paragraphe |
| tabs | PangoTabArray utilisé |
| wrap_mode | mode de retour à la ligne automatique utilisé |
| language | PangoLanguage utilisé |
| invisible | texte invisible (non implémenté dans GTK+ 2.0) |
| bg_full_height | hauteur de l'arrière-plan par rapport à la ligne |
| editable | possibilité d'édition du texte |
| realized | texte réalisé |
| pad1 | |
| pad2 | |
| pad3 | |
| pad4 |
Il est possible de dupliquer un TextIter grâce à la méthode :
copie_iter = iter.copy()
On peut récupérer différentes quantités de texte et d'objets de TextBuffer en utilisant les méthodes suivantes :
caract = iter.get_char() # renvoie le caractère qui suit iter (ou 0 si l'on est à la fin du buffer) texte = debut.get_slice(fin) # renvoie le texte compris entre les itérateurs debut et fin texte = debut.get_text(fin) # renvoie le texte compris entre les itérateurs debut et fin pixbuf = iter.get_pixbuf() # renvoie l'image pixbuf située à l'itérateur iter (ou None) ancrage = iter.get_child_anchor() # renvoie le point d'ancrage situé à l'itérateur iter(ou None) liste_marques = iter.get_marks() # renvoie une liste de marques liste_balises = iter.get_toggled_tags() # renvoie une liste de balises activées ou désactivées liste_balises = iter.get_tags() # renvoie une liste de balises par priorités
Les méthodes suivantes permettent de vérifier certaines caractéristiques des balises se trouvant à une position de TextIter :
resultat = iter.begins_tag(tag=None) # renvoie TRUE si tag s'active à l'emplacement iter resultat = iter.ends_tag(tag=None) # renvoie TRUE si tag se désactive à l'emplacement iter resultat = iter.toggles_tag(tag=None) # renvoie TRUE si tag s'active ou se désactive à l'emplacement iter resultat = iter.has_tag(tag) # renvoie TRUE si la portion de texte contenant iter est balisée par tag
Ces méthodes renvoient TRUE si la balise tag à la position iter remplit la condition. Si l'argument tag vaut None aux trois premières méthodes, le résultat sera TRUE si n'importe quelle balise remplit la condition à la position iter.
Les deux méthodes qui suivent indiquent si le texte situé à la position spécifiée par le TextIter est éditable ou accepte une insertion de texte :
resultat = iter.editable() resultat = iter.can_insert(defaut_editable)
La méthode editable() indique si l'itérateur iter se situe dans une portion de texte éditable. La méthode can_insert() indique si l'on peut insérer du texte à l'emplacement spécifié par iter, en prenant en compte la possibilité d'édition par défaut de la TextView, du TextBuffer et des balises applicables. L'argument defaut_editable est généralement déterminé par un appel à la méthode de TextView :
defaut_editable = zonedetexte.get_editable()
où zonedetexte est la TextView.
On peut savoir si deux TextIter sont équivalents grâce à la méthode :
egalite = iter1.equal(iter2)
La méthode suivante permet de comparer deux TextIter :
resultat = iterA.compare(iterB)
resultat aura pour valeur : -1 si iterA est inférieur à iterB ; 0 si iterA égale iterB ; et 1 si iterA est supérieur à iterB.
Pour savoir si un TextIter se trouve entre deux TextIter donnés, utilisez la méthode :
resultat = iter.in_range(debut, fin)
resultat vaudra TRUE si iter est situé entre debut et fin. Attention, debut et fin doivent être donnés dans l'ordre croissant ! Ceci peut être assuré par la méthode :
iterA.order(iterB)
qui réorganise les positions des TextIter de sorte que iterA soit avant iterB.
On peut déterminer la position d'un TextIter par rapport au texte d'un TextBuffer grâce aux méthodes suivantes :
resultat = iter.starts_word() # iter commence un mot resultat = iter.ends_word() # iter termine un mot resultat = iter.inside_word() # iter est à l'intérieur d'un mot resultat = iter.starts_sentence() # iter commence une phrase resultat = iter.ends_sentence() # iter termine une phrase resultat = iter.inside_sentence() # iter est à l'intérieur d'une phrase resultat = starts_line() # iter commence une ligne resultat = iter.ends_line() # iter termine une ligne
resultat renvoie TRUE si le TextIter est à la position donnée. La définition de "mot" et "phrase" dépend du langage utilisé à la position du TextIter. Quant à la ligne, il s'agit d'un ensemble de phrases s'apparentant à un paragraphe.
La méthode suivante permet de déterminer si un TextIter se situe au début ou à la fin du TextBuffer :
resultat = iter.is_start() resultat = iter.is_end()
resultat vaudra TRUE si le TextIter est situé au début ou à la fin du TextBuffer.
Du fait qu'un TextBuffer peut contenir des groupe de caractères s'affichant comme une seule position de curseur (par exemple un retour chariot + saut de ligne, ou une lettre + marque d'accent), il est possible qu'un TextIter soit à un emplacement ne représentant pas une position de curseur possible. Dans un tel cas, la méthode suivante renverrait FALSE :
resultat = iter.is_cursor_position()
On peut déplacer les TextIter dans un TextBuffer par sauts de différents éléments de texte. La définition de ces éléments de texte est fixée par le PangoLanguage utilisé à l'emplacement du TextIter. Les méthodes basiques sont :
resultat = iter.forward_char() # avancer d'un caractère resultat = iter.backward_char() # reculer d'un caractère resultat = iter.forward_word_end() # avancer à la fin du mot resultat = iter.backward_word_start() # reculer au début du mot resultat = iter.forward_sentence_end() # avancer à la fin de la phrase resultat = iter.backward_sentence_start() # reculer à au début de la phrase resultat = iter.forward_line() # avancer au début de la prochaine ligne resultat = iter.backward_line() # reculer au début de la ligne précédente resultat = iter.forward_to_line_end() # avancer à la fin de la ligne resultat = iter.forward_cursor_position() # avancer à la prochaine position de curseur resultat = iter.backward_cursor_position() # reculer à la position de curseur précédente
resultat vaut TRUE si le TextIter a été déplacé et FALSE s'il se trouve au début ou à la fin du TextBuffer.
Toutes les méthodes ci-dessus (hormis forward_to_line_end() ) ont un équivalent avec argument. Ce dernier est un nombre (positif ou négatif) indiquant de combien d'unités doit se déplacer le TextIter :
resultat = iter.forward_chars(combien) resultat = iter.backward_chars(combien) resultat = iter.forward_word_ends(combien) resultat = iter.backward_word_starts(combien) resultat = iter.forward_sentence_ends(combien) resultat = iter.backward_sentence_starts(combien) resultat = iter.forward_lines(combien) resultat = iter.backward_lines(combien) resultat = iter.forward_cursor_positions(combien) resultat = iter.backward_cursor_positions(combien)
Un TextIter peut être déplacé à un emplacement spécifique du TextBuffer avec les méthodes suivantes :
iter.set_offset(n) # déplace iter juste après le nème caractère du buffer iter.set_line(x) # déplace iter au début de la xème ligne iter.set_line_offset(n) # déplace iter juste après le nème caractère de sa ligne iter.forward_to_end() # déplace iter à la dernière position du buffer
Un TextIter peut également être déplacé vers un emplacement où une balise s'active ou se désactive, et ce grâce à la méthode suivante :
resultat = iter.forward_to_tag_toggle(balise) resultat = iter.backward_to_tag_toggle(balise)
resultat vaudra TRUE si le TextIter a été déplacé vers une nouvelle position où balise s'active ou se désactive. Si balise vaut None, la méthode déplacera TextIter vers la prochaine position où n'importe quelle balise s'active ou se désactive.
La méthode suivante permet de rechercher une chaîne de caractères dans un TextBuffer :
debut_resultat, fin_resultat = iter.forward_search(chaine, drapeaux, limit=None) debut_resultat, fin_resultat = iter.backward_search(chaine, drapeaux, limit=None)
La méthode renvoie un tuple contenant deux TextIter. Ces derniers indiquent respectivement la position du premier caractère du résultat et celle du premier caractère suivant ce résultat. chaine est la chaîne de caractères à localiser. Les drapeaux modifient les paramètres de la recherche ; il peuvent prendre comme valeurs :
gtk.TEXT_SEARCH_VISIBLE_ONLY # les caractères invisibles seront ignorés gtk.TEXT_SEARCH_TEXT_ONLY # les images pixbuf et les points d'ancrages seront ignorés
limit est un TextIter facultatif qui limite la recherche au texte le précédant.