13.4. Iteradores de Texto

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.

13.4.1. Atributos de los Iteradores de Texto

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

13.4.2. Atributos de Texto de un Iterador de Texto

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_colorcolor de fondo
fg_colorcolor de frente
bg_stipplebitmap de patrón de fondo
fg_stipplebitmap de patrón de frente
risedesplazamiento del texto sobre la línea base
underlineestilo de subrayado
strikethroughindica si el texto aparece tachado
draw_bgTRUE si algunas marcas afectan al dibujado del fondo
justificationestilo de la justificación
directionla dirección del texto
fontPangoFontDescription en uso
font_scaleescala de la fuente en uso
left_marginposición del márgen izquierdo
right_marginposición del márgen derecho
pixels_above_linesespacio en píxeles sobre una línea
pixels_below_linesespacio en píxeles debajo de una línea
pixels_inside_wrapespacio en píxeles entre líneas solapadas
tabsPangoTabArray en uso
wrap_modemodo de ajuste en uso
languagePangoLanguage en uso
invisiblesi el texto es invisible (sin implementar en GTK+ 2.0)
bg_full_heightsi el fondo está ocupando el alto completo de línea
editablesi el texto es editable
realizedsi el texto está realizado
pad1 
pad2 
pad3 
pad4 

13.4.3. Copiar un Iterador de Texto

Se puede duplicar un TextIter usando el método:

  iter_copy = iter.copy()

13.4.4. Recuperar Texto y Objetos

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

13.4.5. Comprobar Condiciones en un Iterador de Texto

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.

13.4.6. Comprobar la posición en un Texto

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()

13.4.7. Movimiento a través del Texto

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)

13.4.8. Moverse a una Posición Determinada

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.

13.4.9. Búsqueda en el Texto

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.