## Cómo utilizar la Clase Lists

Un JList le presenta al usuario un grupo de ítems para elegir. Los ítems pueden ser cualquier Object. Normalmente son un String. Un lista puede tener muchos ítems, o podría crecer hasta tenerlos. Cómo la mayoría de las listas se sitúan dentro de paneles desplazables, JList es una clase scroll-savvy.

Además de las listas, los siguientes componentes Swing también presentan múltiples ítems seleccionables al usuario: check boxes, combo boxes,menus, radio buttons, y tables. Sólos los checkbox, las tablas, y las listas permiten seleccionar varios ítems a la vez.

Aquí podemos ver una imagen de una aplicación que utiliza JList para mostrar los nombres de las imágenes a ver.

> Intenta esto:
> 1. Compila y ejecuta la aplicación. El código fuente está en SplitPaneDemo.java. imagenames.properties proporciona los nombres de las imágenes para ponerlos en el JList.
> 2. Elige una imagen de la lista. Utiliza las barras de desplazamiento para ver más nombres.

Abajo está el código de SplitPaneDemo.java que crea y configura la lista:

    ...where member variables are declared
       this Vector is initialized from a properties file...
    static Vector imageList;
    ...where the GUI is created...
    // Create the list of images and put it in a scroll pane
    JList listOfImages = new JList(imageList);
    listOfImages.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
    listOfImages.setSelectedIndex(0);
    listOfImages.addListSelectionListener(this);
    JScrollPane listScrollPane = new JScrollPane(listOfImages);

El código utiliza un objeto Vector para proporcionar una lista con los ítems iniciales. También podemos inicializar una lista con un array o con un objeto ListModel.

En este ejemplo, el Vector contiene strings obtenidas desde un fichero de propiedades. Sin embargo, los valores de la lista pueden ser cualquier Object, en cuyo caso el método toString de la clase Object proporciona el texto a mostrar. Para mostrar un ítem como una imagen u otro valor no-texto, debemos proporcionar una celta personalizada con setCellRenderer.

Por defecto, una lista permite que cualquier combinación de ítems sea seleccionada a la vez. Podemos utilizar un valor por defecto diferente utilizando el método setSelectionMode. Por ejemplo, SplitPaneDemo configura el modo de selección a SINGLE_SELECTION (una constante definida por ListSelectionModel) para que sólo pueda seleccionarse un ítem de la lista. La siguiente lista describe los tres modos de selección disponibles.

Modo | Descripción | Ejemplo
--- | --- | ---
SINGLE_SELECTION | Sólo un ítem de la lista puede ser seleccionado. Cuando el usuario selecciona un ítem, cualquier ítem anteriormente seleccionado se deselecciona primero. |
SINGLE_INTERVAL_SELECTION | Se pueden seleccionar varios ítems contiguos. Cuando el usuario empieza una nueva selección, cualquier ítem anteriormente seleccionado se deselecciona primero. |
MULTIPLE_INTERVAL_SELECTION | El valor defecto. Se puede seleccionar cualquier combinación de ítems. El usuario debe deseleccionar explícitamente los ítems. |

No importa el modo de selección que utiliza la lista, siempre dispara eventos "list selection" cuando cambia la selección. Se pueden procesar esos eventos añadiendo un Oyente de "list selection" a la lista con el método addListSelectionListener.

Un oyente de 'list selection' debe implementar un método : valueChanged. Aquí podemos ver el método valueChanged para el oyente de SplitPaneDemo:

    public void valueChanged(ListSelectionEvent e) {
        if (e.getValueIsAdjusting())
            return;

        JList theList = (JList)e.getSource();
        if (theList.isSelectionEmpty()) {
            picture.setIcon(null);
        } else {
            int index = theList.getSelectedIndex();
            ImageIcon newImage = new ImageIcon("images/" +
                                     (String)imageList.elementAt(index));
            picture.setIcon(newImage);
            picture.setPreferredSize(new Dimension(newImage.getIconWidth(),
                                                   newImage.getIconHeight() ));
            picture.revalidate();
        }
    }

Observa que el método valueChanged sólo actualiza la imagen si getValueIsAdjusting devuelve false. La mayoría de los eventos 'list selection' pueden ser generados desde una simple acción del usuario como una pulsación del ratón. Este programa particular sólo está interesado en el resultado final de la acción del usuario.

Cómo la lista esta en modo de selección sencillo, este código puede utilizar getSelectedIndex para obtener el índice sólo del índice seleccionado. JList proporciona otros métodos para Seleccionar u Obtener la Selección cuando el modo de selección permite seleccionar más de un ítem. Por ejemplo, cambiemos el modo de selección de una lista dinámicamente, podemos ver Ejemplos de Manejos de Eventos 'List Selection'.

#### El API List

> Las siguientes tablas listan los métodos y constructores más utilizados de JList. Otros métodos útiles están definidos por las clases JComponent y Component.

> Muchas de las operaciones de una lista están manejadas por otros objetos. Por ejemplo, los ítems de la lista están manejados por un objeto ListModel, la selección está manejada por un objeto ListSelectionModel, y la mayoría de los programas ponen una lista en un panel desplazable para menajar el desplazamiento. No tenemos que preocuparnos de la mayor parte de estos objetos auxiliares, porque JList los crea cuando son necesarios, y nosotros interactuamos con ellos implicitamente con los métodos de conveniencia de JList.

> Cómo se ha dicho, el API para utilizar Lists de divide en estas categorías:

> - Seleccionar los ítems de una Lista
> - Manejar la Selección de una Lista
> - Trabajar con un ScrollPane

> Seleccionar los ítems de una Lista
> Método | Propósito
> --- | ---
> JList(ListModel) JList(Object[]) JList(Vector) | Crea una lista con los ítems especificados. El segundo y tercer constructores crean implicitamente un ListModel.
> void setModel(ListModel) ListModel getModel() | Selecciona u obtiene el modelo que contiene el contenido de la lista. Podemos modificar dinámicamente el contenido de la lista llamado a los métodos con el objeto devuelto por getModel.
> void setListData(Object[]) void setListData(Vector) | Selecciona los ítems de la lista. Estos métodos crean implícitamente un ListModel.

> Manejar la Selección de una Lista
> Método | Propósito
> --- | ---
> void addListSelectionListener( ListSelectionListener) | Registra para recibir notificación de los cambios de selección.
> void setSelectedIndex(int) void setSelectedIndices(int[]) void setSelectedValue(Object, boolean) void setSelectedInterval(int, int) | Configura la selección actual como indicada. Utiliza el método setSelectionMode para los rangos de selecciones aceptables. El argumento booleano especifica su la lista debería intentar desplazarse a sí misma para que el ítem seleccionado sea visible.
> int getSelectedIndex() int getMinSelectionIndex() int getMaxSelectionIndex() int[] getSelectedIndices() Object getSelectedValue() Object[] getSelectedValues() | Obtiene información sobre la selección actual.
> void setSelectionMode(int) int getSelectionMode() | Selecciona u obtiene el modod de selección. Los valores aceptables son: SINGLE_SELECTION, SINGLE_INTERVAL_SELECTION, o MULTIPLE_INTERVAL_SELECTION.
> void clearSelection() boolean isSelectionEmpty() | Selecciona u obtiene si hay algún ítem seleccionado.
> boolean isSelectedIndex(int) | Determina si el índice específicado está seleccionado.

> Trabajar con un Scroll Pane
> Método | Propósito
> --- | ---
> void ensureIndexIsVisible(int) | Desplaza para que el índice especificado sea visible dentro del recuadro de la lista.
> int getFirstVisibleIndex() int getLastVisibleIndex() | Obtiene el índice del primer o el último elemento visible de la lista.
> void setVisibleRowCount(int) int getVisibleRowCount() | Selecciona u obtiene cúantas filas de la lista son visibles.

#### Ejemplos que utilizan Listas

> Esta tabla muestra ejemplos que utilizan JList y dónde poder encontrarlos.

> Ejemplo | Dónde se Describe | Notas
> --- | --- | ---
> SplitPaneDemo.java | En esta página y en Cómo usar SplitPane | Contiene una sencilla lista de selección.
> ListDialog.java | Cómo usar BoxLayout | Implementa un diálogo modal con una sencilla lista de selección.
> ListSelectionDemo.java | Cómo escribir un oyente de 'List Selection' | Contiene una lista y una tabla que comparten el mismo modelo de selección. El modelo de selección se puede cambiar dinámicamente.

Ozito