<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:e="http://projectmallard.org/experimental/" type="guide" style="task" id="model-view-controller.py" xml:lang="es">

<info>

    <title type="text">El diseño modelo/vista/controlador (Python)</title>

  <link type="guide" xref="beginner.py#theory"/>

  <link type="next" xref="combobox_multicolumn.py"/>

  <revision version="0.1" date="2012-06-30" status="stub"/>

  <desc>El diseño modelo/vista/controlador</desc>

  <credit type="author copyright">

    <name>Sebastian Pölsterl</name>

    <email its:translate="no">sebp@k-d-w.org</email>

    <years>2011</years>

  </credit>

  <credit type="author copyright editor">

    <name>Marta Maria Casetti</name>

    <email its:translate="no">mmcasetti@gmail.com</email>

    <years>2012</years>

  </credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Daniel Mustieles</mal:name>

      <mal:email>daniel.mustieles@gmail.com</mal:email>

      <mal:years>2011 - 2017</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Nicolás Satragno</mal:name>

      <mal:email>nsatragno@gmail.com</mal:email>

      <mal:years>2012 - 2013</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Jorge González</mal:name>

      <mal:email>jorgegonz@svn.gnome.org</mal:email>

      <mal:years>2011</mal:years>

    </mal:credit>

  </info>

<title>El diseño modelo/vista/controlador</title>

<links type="section"/>

<section id="overview">

<title>Visión general</title>

Tanto los widgets <link xref="treeview_simple_liststore.py">TreeView</link> como los <link xref="combobox.py">ComboBox</link> se construyen sobre el diseño modelo/vista/controlador. El modelo (una implementación de Gtk.TreeModel, generalmente Gtk.TreeStore o Gtk.ListStore) almacena los datos; la vista (por ejemplo, Gtk.TreeView, Gtk.ComboBox, o Gtk.ComboBoxText) recibe las notificaciones de cambio y muestra el contenido del modelo. El controlador, finalmente, cambia el estado del modelo (a través de algunos métodos en la implementación del modelo, como append() o remove()) y le notifica a la vista de estos cambios (a través de señales como «changed»).

</section>

<section id="model">

<title>El modelo</title>

La principal diferencia entre las dos implementaciones primarias de Gtk.TreeModel es que Gtk.ListStore contiene filas simples de datos sin hijos, mientras que Gtk.TreeStore también contiene filas de datos, pero cada fila puede tener filas hijas (que a su vez pueden tener filas hijas, y así sucesivamente).

Los datos en el modelo pueden obtenerse o modificarse usando el «iter» del árbol y el índice de columna, Gtk.TreeIter, o Gtk.TreePath.

Con el objeto de lista empotrado de Python puede usar len() para obtener el número de filas y usar fragmentos para obtener o establecer valores. De lo contrario, el método append() devuelve una instancia de Gtk.TreeIter, que apunta al lugar de la fila insertada recientemente. También puede obtener un Gtk.TreeIter llamando a get_iter().

Como Gtk.ListStore sólo contiene un nivel, es decir que los nodos no tienen nodos hijos, una ruta es esencialmente el índice de la fila a la que quiere acceder. En el caso de Gtk.TreeStore, una ruta es una lista de índices o una cadena. La forma de la cadena es una lista de números separados por «:». Cada número se refiere al desplazamiento en ese nivel. Entonces, la ruta «0» se refiere al nodo raíz y la ruta «2:4» al quinto hijo del tercer nodo.

Métodos útiles para un Gtk.TreeModel:

<list>

  <item>
get_iter(ruta) devuelve una instancia de Gtk.TreeIter que apunta a ruta. Se espera que sea una lista de números separados por «:», o una tupla. Por ejemplo, la cadena «10:4:0» equivale a la tupla (10, 4, 0), ya que las dos crearían una ruta de profundidad 3 apuntando al 11º hijo del nodo raíz, el 5º hijo de ese 11º hijo, y el 1er hijo de ese 5º hijo.
</item>

  <item>
iter_next(treeiter) devuelve una instancia de Gtk.TreeIter apuntando siguiendo el «treeiter» en el nivel actual o None si no hay un «iter» siguiente.
</item>

  <item>
iter_has_child(treeiter) devuelve True si treeiter tiene hijos, False de lo contrario.
</item>

  <item>
iter_children(treeiter) devuelve una instancia de Gtk.TreeIter apuntando al primer hijo de treeiter o None si treeiter no tiene hijos.
</item>

  <item>
get_iter_first() devuelve una instancia de Gtk.TreeIter apuntando al primer iterador en el árbol (el que está en la ruta «0») o None si el árbol está vacío.
</item>

</list>

Métodos útiles para un Gtk.ListStore:

<list>

  <item>
append(fila) añade una fila nueva a este «ListStore», donde fila puede ser una lista de valores para cada columna; row también puede omitirse o ser None, y en ese caso se añade una fila vacía. El método devuelve un Gtk.TreeIter apuntando a la fila añadida.
</item>

  <item>
remove(iter) elimina iter del Gtk.ListStore, y devuelve True si el iter es válido, y False si no lo es. Después de eliminarse, iter se establece a la siguiente fila válida.
</item>

</list>

Métodos útiles para un Gtk.TreeStore:

<list>

  <item>
append(padre, fila) añade una fila nueva a este «TreeStore»; padre debe ser un «Gtk.TreeIter» válido. Si «padre» no es None, entonces añadirá la fila nueva después del último hijo de «padre», de lo contrario añadirá una fila al nivel superior; fila puede ser una lista de valores para cada columna; o puede omitirse o ser None; en este último caso se añadirá una fila vacía. El método devuelve un Gtk.TreeIter apuntando a la fila añadida.
</item>

  <item>
remove(iter) elimina iter del Gtk.ListStore, y devuelve True si el iter es válido, y False si no lo es. Después de eliminarse, iter se establece a la siguiente fila válida.
</item>

</list>

</section>

<section id="treeview">

<title>La vista: el caso de «TreeView»</title>

Una vista de árbol muestra la estructura de elementos padres e hijos como un árbol. Consulte <link xref="treeview_treestore.py">este ejemplo</link>.

La Gtk.TreeViewColumn se usa para organizar las columnas verticales.

Métodos útiles para un Gtk.TreeView:

<list>

  <item>
set_model(modelo) establece el modelo para esta vista de árbol. Si ya tiene un modelo, lo eliminará antes de establecer el nuevo. Si el modelo es None, entonces quitará el modelo viejo. 
</item>

  <item>
get_model() devuelve el modelo en el que está basada esta vista de árbol, None si no tiene modelo.
</item>

  <item>
append_column(columna) añade la columna a la lista de columnas.
</item>

  <item>
get_selection() obtiene la Gtk.TreeSelection asociada a esta vista de árbol.
</item>

</list>

Métodos útiles para un Gtk.TreeViewColumn:

<list>

  <item>
add_attribute(renderizador, atributo, valor) añade un mapeo de atributo a esta columna. atributo es el parámetro en renderizador al que se le asigna el valor.
</item>

  <item>
pack_start(renderizador, expandir) empaqueta el renderizador en el principio de esta columna. Si expandir es False, entonces no se le asigna a renderizador más espacio del que necesita. Cualquier espacio sin utilizar se divide equitativamente entre las celdas en las que «expandir» es True.
</item>

  <item>
pack_end(renderizador, expandir) añade el renderizador al final de esta columna. Si expandir es False, entonces no se le asigna a renderizador más espacio del que necesita. Cualquier espacio sin utilizar se divide equitativamente entre celdas en las que expandir es True.
</item>

  <item>
set_sort_column_id(id_columna_ordenada) establece la columna del modelo por la que debe ordenarse la vista. Esto también hace que se pueda pulsar la cabecera de la columna.
</item>

  <item>
set_sort_indicator(opción) establece si se muestra una pequeña flecha en la cabecera de la columna; opción puede ser True (se muestra el indicador) o False.
</item>

  <item>
set_sort_order(orden) cambia el orden por el que se ordena la columna; orden puede ser Gtk.SortType.ASCENDING o Gtk.SortType.DESCENDING.
</item>

</list>

</section>

<section id="combobox">

<title>La vista: el caso de la «ComboBox»</title>

Una Gtk.ComboBox permite la selección de un elemento desde un menú desplegable, consulte <link xref="combobox.py">este ejemplo</link>. Para una lista de opciones textuales, también se puede usar Gtk.ComboBoxText, que es más simple. Tanto Gtk.ComboBox como Gtk.ComboBoxText pueden contener una entrada.

Métodos útiles para un Gtk.ComboBox:

<list>

  <item>
El método estático new_with_entry() crea una Gtk.ComboBox nueva vacía con una entrada; el método estático new_with_model(modelo) crea una con el modelo inicializado a modelo nueva; y el método estático new_with_model_and_entry(modelo) es una combinación de los dos.
</item>

  <item>
get_active_iter() devuelve un Gtk.TreeIter que apunta al elemento activo actual. Si no existe, devuelve None.
</item>

  <item>
set_model(modelo) establece el modelo que esta caja combinada usa a modelo, y quita un modelo anterior (si existiera). Si modelo es None, entonces lo quitará. Tenga en cuenta que esta función no limpia los renderizadores de celda.
</item>

  <item>
set_entry_text_column(columna_texto) establece la columna del modelo de la que esta caja combinada obtendrá las cadenas a columna_texto. La columna columna_texto en el modelo de esta caja combinada debe ser del tipo str (esto sólo es relevante si esta caja combinada se creó con la propiedad «has-entry» establecida a «True»).
</item>

  <item>
set_wrap_width(anchura) establece la anchura del ajuste de línea de esta caja combinada a anchura. La anchura de ajuste de línea es básicamente el número preferido de columnas en el que quiere que el diálogo emergente se distribuya en una rejilla.
</item>

</list>

Métodos útiles para un Gtk.ComboBoxText:

<list>

  <item>
El método estático new_with_entry() crea una Gtk.ComboBoxText nueva vacía con una entrada.
</item>

  <item>
append_text(texto) añade texto a la lista de cadenas almacenadas en esta caja combinada.
</item>

  <item>
get_active_text() devuelve la cadena actualmente activa en esta caja combinada, o None si no hay ninguna seleccionada. Si esta caja combinada contiene una entrada, esta función devolverá su contenido (que no será necesariamente un elemento de la lista).
</item>

</list>

</section>

<section id="cellrenderer">

<title>La vista: los «CellRenderer»</title>

La vista hace uso de Gtk.CellRenderer de varios tipos para dibujar los datos.

Implementaciones de Gtk.CellRenderer y métodos útiles:

<list>

  <item>
Gtk.CellRendererText: muestra texto en una celda
</item>

  <item>
Gtk.CellRendererToggle: muestra un interruptor o botón de radio en una celda. Métodos útiles:

    <list>

    <item>
set_active(opción): activa o desactiva un renderizador de celda
</item>

    <item>
get_active(): devuelve si el renderizador de celda está activado
</item>

    <item>
set_radio(radio): si «radio» es True, el renderizador de celda muestra un interruptor de radio (es decir, un interruptor en un grupo mutuamente exclusivo); si es False, muestra una casilla de verificación (una opción booleana independiente)
</item>

    <item>
get_radio(): devuelve si se están mostrando botones de radio en lugar de casillas de verificación.
</item>

    </list>

  </item>

  <item>
Gtk.CellRendererPixbuf: muestra una imagen en una celda
</item>

  <item>
Gtk.CellRendererCombo: muestra texto en una celda; pero mientras que Gtk.CellRendererText ofrece una entrada simple para editar el texto, Gtk.CellRendererCombo ofrece un widget Gtk.ComboBox para editarlo. Puede usarse con o sin un widget «Gtk.Entry» asociado, dependiendo del valor de la propiedad «has-entry».
</item>

  <item>
Gtk.CellRendererProgress: muestra un valor numérico en forma de barra de progreso en una celda; puede mostrar un texto sobre ella
</item>

  <item>
Gtk.CellRendererSpinner: muestra una animación giratoria en una celda
</item>

  <item>
Gtk.CellRendererSpin: muestra un botón incremental en una celda
</item>

  <item>
Gtk.CellRendererAccel: muestra un acelerador de teclado en una celda
</item>

</list>

</section>

<section id="selection">

<title>El controlador: la selección</title>

La mayoría de las aplicaciones no solo necesitarán mostrar datos, sino también recibir eventos de entrada de los usuarios. Para hacer esto, simplemente obtenga una referencia a un objeto de selección y conéctela a la señal «changed».

select = tree.get_selection()

select.connect("changed", on_tree_selection_changed)

Después, para obtener datos de la fila seleccionada:

def on_tree_selection_changed(selection):

    model, treeiter = selection.get_selected()

    if treeiter != None:

        print "You selected", model[treeiter][0]

Métodos útiles para un Gtk.TreeSelection:

<list>

  <item>
set_mode(tipo) establece el tipo de la selección, donde «tipo» puede ser

  <list>

    <item>
Gtk.SelectionMode.NONE: la selección no es posible
</item>

    <item>
Gtk.SelectionMode.SINGLE: se puede seleccionar uno o ningún elemento
</item>

    <item>
Gtk.SelectionMode.BROWSE: se selecciona exactamente un elemento. En algunas circunstancias, como inicialmente o durante una operación de búsqueda, es posible que ningún elemento esté seleccionado. Lo que realmente se prohíbe es que el usuario deseleccione un elemento actualmente seleccionado excepto si selecciona otro.
</item>

    <item>
Gtk.SelectionMode.MULTIPLE: se puede seleccionar cualquier número de elementos. Las pulsaciones cambien el estado de un elemento. Se puede usar la tecla «Ctrl» para agrandar la selección, y «Mayús» para seleccionar entre el foco y el hijo al que apunta. Algunos widgets también pueden permitir arrastrar y soltar para seleccionar un rango de elementos.
</item>

  </list>

  </item>

  <item>
get_selected() devuelve una tupla (modelo, treeiter), donde modelo es el modelo actual y treeiter un Gtk.TreeIter que apunta a la fila actualmente seleccionada, o «None» si no la hay. El método no funciona si el modo de selección es Gtk.SelectionMode.MULTIPLE; en ese caso, use get_selected_rows() en su lugar, que devuelve una lista de instancias Gtk.TreePath de todas las filas seleccionadas.
</item>

</list>

</section>

<section id="references">

<title>Referencias</title>

<list>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeModel.html">GtkTreeModel</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeView.html">GtkTreeView</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkTreeViewColumn.html">GtkTreeViewColumn</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkComboBox.html">GtkComboBox</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkCellRenderer.html">GtkCellRenderer</link>
</item>

</list>

</section>

</page>