Los Iteradores de Texto TextIter representan una posición entre dos caracteres en un TextBuffer. Los TextIters se crean normalmente usando un método de la clase TextBuffer. Los TextIters se invalidan cuando el número de caracteres de un TextBuffer cambia (excepto para el TextIter que se usa para inserción o borrado). Insertar o borrar pixbuffers o anclajes también invalida un TextIter.
Hay un gran número de métodos asociados con un objeto TextIter. Se agrupan en las siguientes secciones según realicen funciones similares.
El TextBuffer que contiene el TextIter se puede recuperar usando el método:
buffer = iter.get_buffer() |
Los siguientes métodos se pueden usar para obtener la posición del TextIter en el TextBuffer:
offset = iter.get_offset() # devuelve el desplazamiento en el buffer del iterador line_number = iter.get_line() # devuelve el número de línea del iterador line_offset = iter.get_line_offset() # devuelve el desplazamiento en la línea numchars = iter.get_chars_in_line() # devuelve el número de caracteres en la línea |
El objeto PangoLanguage que se usa en una determinada posición del iterador en el TextBuffer se obtiene llamando al método:
language = iter.get_language() |
Hay otro método más general para obtener los atributos de texto en una posición de un TextIter :
result = iter.get_attributes(values) |
donde result indica si el parámetro values (un objeto de la clase TextAttributes ) fue modificado. El parámetro values se obtiene usando el siguiente método de la clase TextView :
values = textview.get_default_attributes() |
Los siguientes atributos se pueden obtener a partir de un objeto de la clase TextAttributes (no está implementado en PyGTK <=1.99.15):
| bg_color | color de fondo |
| fg_color | color de frente |
| bg_stipple | bitmap de patrón de fondo |
| fg_stipple | bitmap de patrón de frente |
| rise | desplazamiento del texto sobre la línea base |
| underline | estilo de subrayado |
| strikethrough | indica si el texto aparece tachado |
| draw_bg | TRUE si algunas marcas afectan al dibujado del fondo |
| justification | estilo de la justificación |
| direction | la dirección del texto |
| font | PangoFontDescription en uso |
| font_scale | escala de la fuente en uso |
| left_margin | posición del márgen izquierdo |
| right_margin | posición del márgen derecho |
| pixels_above_lines | espacio en píxeles sobre una línea |
| pixels_below_lines | espacio en píxeles debajo de una línea |
| pixels_inside_wrap | espacio en píxeles entre líneas solapadas |
| tabs | PangoTabArray en uso |
| wrap_mode | modo de ajuste en uso |
| language | PangoLanguage en uso |
| invisible | si el texto es invisible (sin implementar en GTK+ 2.0) |
| bg_full_height | si el fondo está ocupando el alto completo de línea |
| editable | si el texto es editable |
| realized | si el texto está realizado |
| pad1 | |
| pad2 | |
| pad3 | |
| pad4 |
Se puede duplicar un TextIter usando el método:
iter_copy = iter.copy() |
Se pueden obtener varias cantidades de texto y objetos de un TextBuffer usando los siguientes métodos TextBuffer :
char = iter.get_char() # devuelve un caracter o 0 si se ha llegado al final del buffer text = start.get_slice(end) # devuelve el texto entre los iteradores de principio y fin text = start.get_text(end) # devuelve el texto entre los iteradores de principio y fin pixbuf = iter.get_pixbuf() # devuelve el pixbuf en esa posición (o None) anchor = iter.get_child_anchor() # devuelve el anclaje (o None) mark_list = iter.get_marks() # devuelve una lista de marcas tag_list = iter.get_toggled_tags() # devuelve una lista de etiquetas que están activadas o desactivadas tag_list = iter.get_tags() # devuelve una lista de etiquetas por prioridades |
Las condiciones de marcado de en la posición de un iterador TextIter se pueden comprobar usando los siguientes métodos:
result = iter.begins_tag(tag=None) # TRUE si la etiqueta está activada en el iterador result = iter.ends_tag(tag=None) # TRUE si la etiqueta está desactivada en el iterador result = iter.toggles_tag(tag=None) # TRUE si la etiqueta está activa o desactivada en el iterador result = iter.has_tag(tag) # TRUE si existe la etiqueta en el iterador |
Estos métodos devuelven TRUE si la marca que representa el parámetro tag satisface la condición en las posición del iterador iter. En los tres primeros métodos, si la marca representada por el parámetro tag es None entonces el resultado es TRUE si cualquier etiqueta satisface la condición dada en la posición del iterador iter.
Los siguientes métodos indican si el texto en la posición del iterador TextIter es editable o permite inserción de texto:
result = iter.editable() result = iter.can_insert(default_editability) |
El método editable() indica si el iter está en un rango editable de texto mientras que el método can_insert() indica si el texto se puede insertar en el iterador iter considerando la editabilidad predeterminada de la TextView, el TextBuffer y las etiquetas aplicables. La editabilidad predeterminada default_editability se obtiene con el método:
default_editability = textview.get_editable() |
La equivalencia de dos iteradores TextIter se puede determinar con el método:
are_equal = lhs.equal(rhs) |
Dos iteradores TextIter se pueden comparar con el método:
result = lhs.compare(rhs) |
result será: -1 si lhs es menor que rhs; 0 si lhs es igual que rhs; y, 1 si lhs es mayor que rhs.
Para determinar si un iterador TextIter está situado entre otros dos iteradores TextIter se usa el método:
result = iter.in_range(start, end) |
El result será TRUE si iter está entre start y end. Atención: start y end deben estar en orden ascendente. Esto se puede garantizar con el método:
first.order(second) |
que reordenará los desplazamientos de los iteradores TextIter para que first esté antes que second.
La posición de un TextIter con respecto al texto en un TextBuffer se puede determinar con los siguientes métodos:
result = iter.starts_word() # empieza palabra result = iter.ends_word() # termina palabra result = iter.inside_word() # dentro de palabra result = iter.starts_sentence() # empieza frase result = iter.ends_sentence() # termina frase result = iter.inside_sentence() # dentro de frase result = starts_line() # empieza línea result = iter.ends_line() # termina línea |
result será TRUE si el TextIter está en la posición dada. Estos métodos son autoexplicativos. La definición de los elementos de texto y sus límites se determina por el lenguaje usado en el iterador TextIter. Obsérvese que una línea es una colección de frases similar a un párrafo.
Los siguientes métodos se pueden usar para determinar si un TextIter está al principio o al final de un TextBuffer:
result = iter.is_start() result = iter.is_end() |
result es TRUE si el iterador TextIter está al principio o al final del TextBuffer.
Ya que un TextBuffer puede contener múltiples caracteres que se visualizan en la práctica como una única posición del cursor (por ejemplo la combinación de retorno de carro y nueva línea o una letra con un símbolo de acento) es posible que un TextIter pueda estar en una posición que no corresponde con una posición de cursor. El siguiente método indica si un iterador TextIter está en una posición del cursor:
result = iter.is_cursor_position() |
Los TextIters se pueden mover por un TextBuffer en saltos de varias unidades de texto. La definición de las unidades de texto se establece en el objeto PangoLanguage que se use en la posición del TextIter . Los métodos básicos son:
result = iter.forward_char() # avanzar un caracter result = iter.backward_char() # retroceder un caracter result = iter.forward_word_end() # avanzar hasta el final de la palabra result = iter.backward_word_start() # retroceder al principio de la palabra result = iter.forward_sentence_end() # avanzar al final de la frase result = iter.backward_sentence_start() # retroceder al principio de la frase result = iter.forward_line() # avanzar al principio de la línea result = iter.backward_line() # retroceder al principio de la línea result = iter.forward_to_line_end() # avanzar al final de la línea result = iter.forward_cursor_position() # avanzar una posición del cursor result = iter.backward_cursor_position() # retroceder una posición del cursor |
result es TRUE si el TextIter se movió y FALSE si el TextIter está al principio o al final del TextBuffer.
Todos estos métodos (excepto forward_to_line_end()) tienen métodos equivalentes que reciben una cantidad (que puede ser positiva o negativa) para mover el TextIter en un salto de múltiples unidades de texto:
result = iter.forward_chars(count) result = iter.backward_chars(count) result = iter.forward_word_ends(count) result = iter.backward_word_starts(count) result = iter.forward_sentence_ends(count) result = iter.backward_sentence_starts(count) result = iter.forward_lines(count) result = iter.backward_lines(count) result = iter.forward_cursor_positions(count) result = iter.backward_cursor_positions(count) |
Un iterador TextIter se puede mover a una posición específica en el TextBuffer haciendo uso de los siguientes métodos:
iter.set_offset(char_offset) # moverse al desplazamiento de caracteres específico iter.set_line(line_number) # moverse al principio de la línea dada como parámetro iter.set_line_offset(char_on_line) # moverse al caracter especificado en la línea actual iter.forward_to_end() # moverse al final del buffer |
Además, un iterador TextIter se puede mover a una posición donde una etiqueta esté activada o desactivada usando los métodos:
result = iter.forward_to_tag_toggle(tag) result = iter.backward_to_tag_taoggle(tag) |
result es TRUE si el TextIter se movió a la nueva posición donde exista la etiqueta tag. Si la etiqueta tag es None entonces el iterador TextIter se moverá a la siguiente posición donde exista una etiqueta.
Una búsqueda de una cadena de texto en un TextBuffer se hace con los siguientes métodos:
match_start, match_end = iter.forward_search(str, flags, limit=None) # búsqueda hacia adelante match_start, match_end = iter.backward_search(str, flags, limit=None) # búsqueda hacia atrás |
El valor de retorno es una tupla que contiene los iteradores TextIter que indican la posición del primer caracter que coincide con la búsqueda y la posición del primer caracter después de la coincidencia. str es la cadena a buscar. El parámetro flags modifica las condiciones de la búsqueda y puede tomar los siguientes valores:
gtk.TEXT_SEARCH_VISIBLE_ONLY # se ignoran los caracteres invisibles gtk.TEXT_SEARCH_TEXT_ONLY # se ignoran los pixbuffers y los anclajes de hijos |
limit es un parámetro opcional que limita el rango de la búsqueda.