Gestión de los objetos de tipo List box

Los comandos de este tema están dedicados a la gestión de objetos de formulario de tipo List box.

Los list boxes permiten representar los datos en forma de columnas y de filas seleccionables y proponen numerosas funciones de interfaz como la posibilidad de introducir valores, ordenar columnas, mostrar una jerarquía, definir colores alternos, etc.

Es posible configurar completamente un list box en el editor de formularios de 4D e igualmente puede controlarlo por programación. Para mayor información sobre la creación y definición de objetos de tipo list box en el editor de formularios como también sobre su uso, consulte el Manual de Diseño de la documentación 4D.

La programación de objetos de tipo List box se efectúa de la misma forma que para los otros objetos de formulario en lista de 4D. Sin embargo, se deben seguir las reglas específicas, descritas en esta sección.

Un list box puede contener una o más columnas y puede estar asociado a arrays 4D o a una selección de registros. En el caso de list boxes de tipo selección, las columnas son asociadas a campos o expresiones.

No es posible tener ambos tipos de fuentes de datos (arrays y selecciones) combinados en el mismo list box. La definición de la fuente de datos se efectúa en el momento de la creación del list box en el editor de formularios, vía la Lista de propiedades. Entonces ya no es posible modificarlo por programación.

En este tipo de list box, cada columna está asociada a un array 4D de una dimensión; todos los tipos de array pueden utilizarse, a excepción de los arrays de punteros. El formato de salida de cada columna puede definirse en el editor de formularios o utilizando el comando OBJECT SET FORMAT.

Utilizando el lenguaje, los valores de las columnas (entrada y visualización de datos) se administran utilizando los comandos de alto nivel del tema List box (tales como LISTBOX INSERT ROWS o LISTBOX INSERT COLUMN) como también los comandos de manipulación de arrays.

Por ejemplo, para inicializar el contenido de una columna, puede utilizar la siguiente instrucción:

Igualmente puede utilizar una lista:

Nota: cuando un objeto List box contiene varias columnas, cada array relacionado debe tener el mismo tamaño (mismo número de elementos) que los otros, de lo contrario sólo se mostrarán el número de elementos del array más pequeño.

Advertencia: cuando un list box contiene varias columnas de diferentes tamaños, sólo se muestra el número de elementos del array más pequeño (columna). Debe asegurarse de que cada array tenga el mismo número de elementos que los otros. Igualmente, si una columna de la list box está vacía (esto ocurre cuando el array asociado no fue declarado correctamente o dimensionado utilizando el lenguaje), la list box no muestra nada.

En este tipo de list box, cada columna puede estar asociada con un campo o una expresión. El contenido de cada fila se evalúa de acuerdo a una selección de registros: la selección actual de una tabla o una selección temporal.

Cuando la selección actual es la fuente de datos, todas las modificaciones realizadas en la base son reportadas automáticamente en el list box y viceversa. La selección actual es entonces siempre la misma en ambas ubicaciones. Note que los comandos LISTBOX INSERT ROWS y LISTBOX DELETE ROWS no pueden utilizarse con list boxes de tipo selección.

Puede asociar una columna de list box a una expresión. La expresión puede estar basada en uno o más campos (por ejemplo [Empleados]Apellido+" "+[Empleados]Nombre) o simplemente en una fórmula (por ejemplo String(Milliseconds)). La expresión también puede tener un método de proyecto, una variable o un elemento de array.

El comando LISTBOX SET TABLE SOURCE puede utilizarse para modificar la tabla asociada con el list box por programación.

Un objeto List box está compuesto de cuatro tipos de elementos diferentes:

• el objeto mismo,
• las columnas,
• los encabezados de las columnas (pueden mostrarse u ocultarse, se muestran por defecto),
• los pies de las columnas (pueden mostrarse u ocultarse, se ocultan por defecto),

Estos elementos pueden seleccionarse individualmente en el editor de formularios. Cada uno tiene su propio nombre de objeto y nombre de variable y puede ser manejado por separado.

Por defecto, las columnas se llaman Columna1 a n y los encabezados Título1 a n en el formulario, independientemente de los objetos list box. Note que por defecto, el mismo nombres se utiliza para los objetos y sus variables asociadas, a excepción de los pies (por defecto las variables están vacías para los pies, 4D utiliza las variables dinámicas).
Cada tipo de elemento contiene características propias y características compartidas con los otros elementos. Por ejemplo, la fuente de los caracteres puede ser asignada globalmente al objeto list box o por separado a las columnas, a los encabezados y/o a los pies. Por otra parte, las propiedades de entrada sólo pueden definirse para las columnas.
Estas reglas que aplican a los comandos del tema “Propiedades de los objetos” pueden utilizarse con los list box. Dependiendo de su funcionalidad, cada comando puede utilizarse con el list box, las columnas, los encabezados y/o los pies de las columnas. Para definir el tipo de elemento en el cual quiere trabajar, simplemente pase el nombre o la variable asociada a él.
La siguiente tabla detalla el alcance de cada comando del tema “Propiedades de los objetos” que puede utilizarse con los objetos de tipo list box:

Nota: con list boxes de tipo array, es posible especificar el estilo, color de fuente, color de fondo y visibilidad para cada línea por separado. Esto se administra por medio de arrays asociados con el list box en la lista de propiedades. Puede recuperar los nombres de estos arrays por programación utilizando el comando LISTBOX GET ARRAYS.

Es posible añadir un método de objeto al objeto list box en su conjunto y/o a cada columna de la list box.
Los métodos de objeto se llaman en la siguiente orden:

1. Método de objeto de la columna
2. Método de objeto del list box

Cuando el comando OBJECT SET VISIBLE se utiliza con un encabezado o un pie de list box, se utiliza en todos los encabezados o todos los pies del objeto List box, sin importar el elemento individual especificado por el comando.
Por ejemplo, la instrucción OBJECT SET VISIBLE(*;"encabezado3";False) ocultará todos los encabezados del objeto List box al cual pertenece el encabezado3 y no únicamente este encabezado.
Note que para poder manejar la visibilidad de estos objetos utilizando el comando OBJECT SET VISIBLE, debe haber sido mostrados en el list box a nivel del editor de formularios (la opción Mostrar encabezados y/o Mostrar pies debe estar seleccionada para el objeto).

La función OBJECT Get pointer utilizada con la constante Object with focus u Object current (antiguas funciones Focus object y Self) puede ser utilizada en el método de objeto de un list box o de una columna de list box.
Devuelven un puntero al list box, la columna(1) list box o la variable del encabezado en función del tipo de evento de formulario. La siguiente tabla detalla este funcionamiento:

(*) Cuando el foco se modifica dentro de un list box, se devuelve a la columna un puntero. Cuando el foco se modifica a nivel del formulario, se devuelve un puntero al list box. En el contexto de un método de objeto de columna, se devuelve un puntero a la columna.

(**) No ejecutado en el contexto de un método de objeto de columna.

(1) Cuando se devuelve un puntero a una columna, el objeto al cual se apunta depende del tipo del list box. Con un array de tipo list box, la función OBJECT Get pointer devuelve un puntero al array). El mecanismo de punteros de 4D permite conocer el número del elemento del array modificado. Por ejemplo, suponiendo que el usuario modificó la quinta fila de la columna col2:

En el caso de un list box de tipo selección, la función OBJECT Get pointer devuelve:

• Para una columna asociada a un campo, un puntero al campo asociado,
• Para una columna asociada a una variable, un puntero a la variable,
• Para una columna asociada a una expresión, el puntero Nil.

El comando OBJECT SET SCROLL POSITION (tema “Propiedades de los objetos") puede utilizarse con un objeto de tipo list box. Ese comando permite desplazar las líneas de la list box para mostrar la primera línea seleccionada o una línea específica.

El comando EDIT ITEM (tema “Gestión de entrada”) le permite pasar a modo edición una celda de un objeto list box.

Cuando se aplica a un listbox en modo selección, el comando REDRAW (tema "Interfaz del usuario") dispara la actualización de los datos mostrados en el list box.

El comando Displayed line number (tema "Selecciones") funciona en el contexto del evento de formulario On Display Detail para un objeto list box.

Los eventos de formulario específicos están destinados a facilitar la gestión programada del list box, en particular con lo relacionado a las operaciones de arrastrar y soltar y ordenar. Para mayor información, consulte la descripción del comando Form event.

La gestión de arrastrar y soltar de datos en los list boxes está soportada por los comandos Drop position y DRAG AND DROP PROPERTIES. Estos comandos han sido adaptados especialmente para los list boxes.

Tenga cuidado en no confundir arrastrar y soltar con mover filas y columnas, soportado por los comandos LISTBOX MOVED ROW NUMBER y LISTBOX MOVED COLUMN NUMBER.

Para que una celda de list box sea editable, ambas de las siguientes condiciones deben cumplirse:

• La columna de la celda debe haberse definido como Editable (de lo contrario, las celdas de la columna no serán editables).
• En el evento formulario On Before Data Entry, $0 no devuelve -1.
  Cuando el cursor llega a la celda, el evento On Before Data Entry se genera en el método de la columna. Si, en el contexto de este evento, $0 toma el valor -1, la celda se considera como no editable. Si el evento se generó luego de presionar Tab o Mayús+Tab, el foco va a la celda siguiente o anterior respectivamente. Si $0 no vale -1 (por defecto $0 es 0), la celda es editable y pasa a modo edición.

Imaginemos por ejemplo un list box que contiene dos arrays, de tipo fecha y texto. El array fecha no es editable pero el array texto es editable si la fecha no ha pasado. 

Este es el método de la columna arrText:

Nota: a partir de 4D v13, el evento On Before Data Entry se devuelve antes de On Getting Focus.

Por defecto, la list box administra automáticamente la ordenación estándar de columnas en caso de clic en el encabezado. Una ordenación estándar es una ordenación alfanumérica de valores de la columna, de forma alterna ascendente/descendente con cada clic. Todas las columnas siempre se sincronizan automáticamente.
Puede evitar las ordenaciones de usuario estándar deseleccionando la propiedad “Ordenable” del list box.

Por defecto, el list box maneja automáticamente las ordenaciones estándar de columnas en caso de clic en el encabezado. Una ordenación estándar es una ordenación alfanumérica de los valores de la columna, alternamente ascendente/descendente con cada clic sucesivo. Todas las columnas siempre se sincronizan automáticamente.
Usted puede prohibir ordenar al usuario estándar deseleccionando la propiedad "Ordenable" para el listbox.

Nota: la propiedad “Ordenable” únicamente afecta la ordenación del usuario estándar; el comando LISTBOX SORT COLUMNS no tiene en cuenta esta propiedad.

El valor de la variable asociada al título de la columna le permite administrar información adicional: la ordenación actual de la columna (lectura) y la visualización de la flecha de ordenación.

• Si la variable vale 0, la columna no se ordena y no se muestra la flecha de ordenación;

• Si la variable vale 1, la columna se ordena de forma ascendente y se muestra la flecha de ordenación;

• Si la variable vale 2, la columna se ordena de forma descendente y se muestra la flecha de ordenación.

Es posible fija el valor de la variable (por ejemplo, Titulo2:=2) para “forzar” la visualización de la flecha de ordenación. La ordenación de la columna misma no se modifica en este caso; está en manos del desarrollador manejarlo.

La gestión de selecciones se efectúa de manera diferente para los list box de tipo array y de tipo selección.

• List box de tipo selección: las selecciones son administradas por un conjunto llamado "Highlight Set". Este conjunto se define en las propiedades del list box. Es mantenido automáticamente por 4D: si el usuario selecciona una o más filas en el list box, el conjunto se actualiza inmediatamente. Por otra parte, también es posible utilizar los comandos del tema "Conjuntos" con el fin de modificar por programación la selección del list box.

• List box de tipo array: el comando SELECT LISTBOX ROW puede utilizarse para seleccionar por programación una o más filas del list box.

La variable asociada al objeto List box se utiliza para obtener, fijar o almacenar las selecciones de filas del objeto.

Esta variable corresponde a un array de booleanos que es creada y mantenida automáticamente por 4D. El tamaño de este array se determina por el tamaño del list box: contiene el mismo número de elementos que el array más pequeño asociado a las columnas.

Cada elemento de este array contiene True si la fila correspondiente se selecciona y de lo contrario False. 4D actualiza los contenidos de este array dependiendo de las acciones del usuario. A la inversa, usted puede modificar el valor de los elementos de este array para modificar la selección en el list box.

Por otra parte, no es posible insertar o borrar filas en este array; tampoco es posible digitar filas nuevamente.

Nota: el comando Count in Array puede utilizarse para conocer el número de las filas seleccionadas.

Por ejemplo, este método permite invertir la selección de esta primera fila del list box (tipo array):

Es posible imprimir list boxes a partir de 4D v12. Están disponibles dos modos de impresión: modo previsualización, el cual puede permite imprimir un list box como un objeto de formulario y el modo avanzado, permite controlar la impresión del objeto list box mismo dentro del formulario. Note que la apariencia "Impresión" está disponible para los objetos list box en el editor de formularios.

La impresión de un list box en modo previsualización consiste en imprimir directamente el list box con el formulario que lo contiene utilizando los comandos de impresión estándar o el comando de menú Print. El list box se imprime como está en el formulario. Este modo no permite controlar con precisión la impresión del objeto; en particular, no permite imprimir todas las líneas de un list box que contenga más líneas de las que pueda mostrar.

En este modo, la impresión de los list box se efectúa por programación, vía el comando Print object. Por lo tanto, sólo los list box presentes en los formularios proyecto pueden imprimirse en modo avanzado. El comando LISTBOX GET PRINT INFORMATION se utiliza para controlar la impresión del objeto. 

En este modo:

• La altura del objeto list box se reduce automáticamente cuando el número de líneas a imprimir es menor a la altura original del objeto (no hay líneas "vacías" impresas). Por el contrario, la altura no aumenta automáticamente  en función del contenido del objeto. El tamaño del objeto efectivamente impreso puede obtenerse vía el comando LISTBOX GET PRINT INFORMATION.
• El objeto list box se imprime "tal cual", en otras palabras, teniendo en cuenta sus parámetros de visualización actuales: visibilidad de encabezados y rejillas, líneas mostradas y ocultas, etc.
  Estos parámetros también incluyen la primera línea a imprimir: si llama al comando SCROLL LINES antes del lanzar la impresión, la primera línea impresa en el list box será la designada por el comando. 
• Un mecanismo automático facilita la impresión de los list box que contienen más líneas de las que es posible mostrar: llamadas sucesivas a Print object permiten imprimir un nuevo conjunto de líneas cada vez. El comando LISTBOX GET PRINT INFORMATION permite controlar el estado de la impresión.

Es posible poner directamente el resultado de una petición SQL en un list box de tipo array. Esta función ofrece un medio rápido de visualizar el resultado de peticiones SQL. Sólo pueden utilizarse las peticiones de tipo SELECT. Este mecanismo no puede utilizarse con una base SQL externa. 

Esto funciona de acuerdo a los siguientes principios:

• Cree el list box que recibirá los resultados de la petición. La fuente de datos del list box debe ser Arrays.
• Ejecute la petición SQL de tipo SELECT y asigne el resultado a la
  variable asociada al list box. Puede utilizar las palabras claves Begin SQL/End SQL (ver el manual de Lenguaje de 4D).
• Las columnas del list box son ordenables y modificables por el usuario.
• Cada nueva ejecución de una petición SELECT con la list box provoca la reinicialización de las columnas (no es posible llenar el mismo list box progresivamente utilizando varias peticiones SELECT).   
• Se recomienda dar al list box el mismo número de columnas que las que tendrá en el resultado de petición SQL. Si el número de columnas del list box es inferior al del necesario para la petición SELECT, las columnas se añaden automáticamente. Si el número de columnas del list box es superior al necesario para la petición SELECT, se
  ocultan las columnas innecesarias.
  Nota: las columnas añadidas automáticamente están relacionadas con las variables de tipo array temporal. Estos arrays temporales permanecen siempre y cuando el formulario exista. Una variable temporal se crea igualmente para cada encabezado. Cuando se llama el comando LISTBOX GET ARRAYS, el parámetro arrVarCols contiene los punteros a los arrays temporales y el parámetro arrVarEncabezados contiene los punteros a las variables de encabezados temporales. Si una columna añadida es por ejemplo la quinta columna, su nombre es sql_column5 y su nombre de encabezado es sql_header5.
• En modo interpretado, los arrays existentes utilizados por el list box pueden redigitarse automáticamente de acuerdo a los datos enviados por la petición SQL

Ejemplo
Queremos recuperar todos los campos de la tabla PERSONAS y ubicar su contenido en el list box cuyo nombre de variable es vlistbox. En el método de objeto de un botón (por ejemplo), es suficiente escribir: