Listas

Abrir en ChatGPT

info

Esta sección describe características comunes de todos los componentes de lista y no es una clase que se pueda instanciar o utilizar directamente.

Hay tres tipos de listas disponibles para usarse dentro de tus aplicaciones: ListBox, ChoiceBox y ComboBox. Estos componentes muestran una lista de elementos clave-valor y proporcionan métodos para agregar, eliminar, seleccionar y gestionar los elementos dentro de la lista.

Esta página describe las características compartidas y el comportamiento de todos los componentes de lista, mientras que los detalles específicos de cada uno se cubren en sus respectivas páginas.

Usando ListItem

Los componentes de lista se componen de objetos ListItem, que representan elementos individuales dentro de una lista. Cada ListItem está asociado con una clave y un texto de visualización únicos. Las características importantes de la clase ListItem incluyen:

• Un ListItem encapsula una clave única Object y un texto String que se mostrará dentro del componente de lista.
• Puedes construir un ListItem proporcionando una clave y un texto, o especificando solo el texto, que también se utiliza como clave.

Las claves deben ser únicas dentro de una lista. Agregar un segundo elemento solo con texto que tenga el mismo texto lanzará una IllegalArgumentException. Para mostrar etiquetas duplicadas, proporciona claves distintas para esos elementos.

Gestionando objetos ListItem con la API

Los diversos componentes de lista ofrecen varios métodos para gestionar la lista de elementos y mantener un estado coherente entre la lista y el cliente. Al utilizar estos métodos, puedes gestionar eficazmente los elementos dentro de la lista. La API te permite interactuar y manipular la lista para satisfacer los requisitos de tu aplicación.

Agregando elementos

• Agregando un elemento:

  • Para agregar un ListItem a la lista, puedes utilizar el add(ListItem item) método.
  • También puedes agregar un nuevo ListItem especificando la clave y el texto usando el add(Object key, String text) o el add(String text) método.

• Insertando un elemento en un índice específico:

  • Para insertar un elemento en un índice específico, utiliza el insert(int index, ListItem item) método.
  • Puedes insertar un elemento con clave y texto usando el insert(int index, Object key, String text) o el insert(int index, String text) método.

• Insertando múltiples elementos:

  • Puedes insertar múltiples elementos en un índice especificado utilizando el insert(int index, List< ListItem > items) método.

sugerencia

Para optimizar el rendimiento, en lugar de activar un mensaje del servidor al cliente cada vez que utilizas el método add(), es más eficiente crear primero una lista de objetos ListItem. Una vez que tengas esta lista, podrás agregar todos a la vez utilizando el método insert(int index, List<ListItem> items). Este enfoque reduce la comunicación entre el servidor y el cliente, mejorando la eficiencia general. Para pautas detalladas sobre esto y otras mejores prácticas en la arquitectura webforJ, consulta Interacción Cliente/Servidor.

Eliminando elementos

• Eliminando un elemento:

  • Para eliminar un elemento de la lista, utiliza el remove(int index) o el remove(Object key) método.

• Eliminando todos los elementos:

  • Puedes eliminar todos los elementos de la lista utilizando removeAll().

Seleccionando elementos

Todos los tipos de listas implementan la interfaz SelectableList. Esta interfaz permite múltiples formas de seleccionar el actual ListItem.

Con un ListItem dado

select(ListItem item) toma un ListItem como parámetro para seleccionar.

ListBox demoList = new ListBox();
ListItem demoItem = new ListItem("demo","Elemento de demostración");
demoList.add(demoItem);
demoList.select(demoItem);

Con una clave dada de un ListItem

selectKey(Object key) toma una clave de un ListItem como parámetro para seleccionar.

ListBox demoList = new ListBox();
demoList.add("demo","Elemento de demostración");
demoList.selectKey("demo");

Con un índice dado de un ListItem

selectIndex(int index) toma un índice de un ListItem como parámetro para seleccionar.

ListBox demoList = new ListBox();
demoList.add("demo","Elemento de demostración");
demoList.selectIndex(0);

Otras operaciones de lista

• Accediendo y actualizando elementos:

  • Para acceder a elementos por clave o índice, utiliza getByKey(Object key) o getByIndex(int index).
  • Puedes actualizar el texto de un elemento utilizando el setText(String text) método dentro de la clase ListItem.

• Recuperando información sobre la lista:

  • Puedes obtener el tamaño de la lista utilizando el size() método.
  • Para comprobar si la lista está vacía, utiliza el isEmpty() método.

Iterando sobre listas

Todos los componentes de lista implementan la interfaz Iterable de Java. Usa forEach() o un bucle for para acceder o modificar cada ListItem.

El fragmento de código a continuación demuestra dos formas sencillas de iterar a través de una lista:

list.forEach(item -> {
   item.setText("Modificado: " + item.getText());
});

for (ListItem item : list) {
   item.setText("Modificado2: " + item.getText());
}

Buscando 26.02

Todos los componentes de lista tienen un campo de búsqueda integrado que filtra los elementos por su texto. El campo está desactivado por defecto. Usa getSearch() para alcanzar la configuración de búsqueda, luego setFieldVisible(true) para mostrar el campo en la parte superior de la lista del componente.

ComboBox comboBox = new ComboBox("Fruta");
comboBox.insert("Manzana", "Banana", "Cereza", "Albaricoque", "Piña");

comboBox.getSearch()
  .setFieldVisible(true)
  .setPlaceholder("Buscar frutas")
  .setEmptyMessage("No se encontraron frutas");

Filtrar solo oculta los elementos que no coinciden. Los índices de los elementos y la selección actual no se ven afectados, por lo que getSelectedIndex() sigue refiriéndose a la lista completa en lugar de a los elementos actualmente visibles.

El campo de búsqueda puede ocultarse nuevamente con setFieldVisible(false).

Configurando el campo

• setPlaceholder() establece el texto del marcador de posición del campo de búsqueda. El valor predeterminado es Buscar.

• setEmptyMessage() establece el mensaje que se muestra cuando una búsqueda no devuelve resultados. El valor predeterminado es No hay datos que mostrar.

Cada configuración tiene un getter correspondiente: isFieldVisible(), getPlaceholder(), getEmptyMessage(), y getTerm().

Filtrando desde el código

setTerm() establece el término de búsqueda y filtra la lista. Funciona independientemente de si el campo es visible o no, por lo que una lista se puede filtrar sin mostrar ninguna interfaz de búsqueda.

listBox.getSearch().setTerm("manzana");

getTerm() y el campo de búsqueda

Escribir en el campo de búsqueda no devuelve el término a la configuración. getTerm() devuelve el último valor pasado a setTerm(), no lo que el usuario ha escrito.

Propiedades compartidas de la lista

Etiqueta

Todos los componentes de lista pueden ser asignados una etiqueta, que es un texto descriptivo o título asociado con el componente. Las etiquetas proporcionan una breve explicación o indicación para ayudar a los usuarios a entender el propósito o la selección esperada para esa lista en particular. Además de su importancia para la usabilidad, las etiquetas de lista también desempeñan un papel crucial en la accesibilidad, permitiendo que los lectores de pantalla y las tecnologías asistivas proporcionen información precisa y faciliten la navegación por teclado.

Texto de ayuda

Cada componente de lista puede mostrar texto de ayuda debajo de la lista utilizando el método setHelperText(). Este texto de ayuda ofrece contexto o explicaciones adicionales sobre las opciones disponibles, asegurando que los usuarios tengan la información necesaria para hacer selecciones informadas.

Alineación horizontal

Todos los componentes de lista implementan la interfaz HasHorizontalAlignment, lo que te brinda control sobre cómo se alinean el texto y el contenido dentro del componente.

Utiliza el método setHorizontalAlignment() con el enum HasHorizontalAlignment.Alignment para establecer la alineación:

• Alignment.LEFT (predeterminado)
• Alignment.MIDDLE
• Alignment.RIGHT

ListBox listBox = new ListBox();
listBox.setHorizontalAlignment(Alignment.LEFT);

Para obtener la alineación actual:

Alignment alignment = listBox.getHorizontalAlignment();

Expanses

Todos los componentes de lista en webforJ también implementan la interfaz HasExpanse, lo que te permite ajustar el tamaño general y el peso visual del componente. Esto es útil para adaptar el componente a varios contextos de UI, como formularios, diálogos, barras laterales, etc.

Utiliza el método setExpanse() para establecer el nivel de expanse. Las opciones incluyen:

• Expanse.NONE
• Expanse.XSMALL
• Expanse.SMALL
• Expanse.MEDIUM (predeterminado)
• Expanse.LARGE
• Expanse.XLARGE

ListBox listBox = new ListBox();
listBox.setExpanse(Expanse.LARGE);

Puedes recuperar la configuración actual utilizando:

Expanse current = listBox.getExpanse();

Temas

📄️ChoiceBox

Pick a single value from a fixed set with the ChoiceBox dropdown, including dropdown type styling, max row count, and keyboard navigation.

📄️ComboBox

Combine a dropdown list with a text input in the ComboBox to let users select preset items or type custom values with placeholder support.

📄️ListBox

Show a scrollable, always-visible list with the ListBox component, supporting single or multiple selection and keyboard navigation.

Sigue aprendiendo

ArtículoMulti-select in Java UI: ListBox and ChoiceBox with webforJArtículoComboBox in Java: preset items and custom values