Gestión programada 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:

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.

Estos principios se aplican a los comandos del tema “Propiedades de los objetos” que 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.

Con el fin de preservar la coherencia de los datos para los list box de tipo selección, todo registro modificado se guarda tan pronto como se valida la celda (si está definido el trigger On saving an existing record se llama) luego se ejecuta el evento On Data Change. La secuencia típica de eventos generada durante la entrada o la modificación de datos es la siguiente:

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.

Nota: el comando OBJECT SET FORMAT ofrece un soporte específico para los íconos en los encabezados de list box, útil cuando desea trabajar con un icono de ordenación personalizado.

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 intermedio de un conjunto llamado por defecto $ListboxSetX (X comienza en 0 y se incrementa en función del número de list box en el formulario), puede modificarlo si es necesario. 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 (los formularios proyecto y los formularios tabla se tienen en cuenta). 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 OBJECT SET SCROLL POSITION 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.

Hay varios modos distintos de configurar los colores de fondo, colores de fuente y estilos de fuente para los list boxes:

• a nivel de las propiedades del objeto list box,
• a nivel de las propiedades de la columna,
• utilizando arrays o métodos para el list box y/o para cada columna,
• a nivel del texto de cada celda (si texto multiestilo).

Se observan principios de prioridad y de herencia.

propiedades del objeto list box o columna, el uso de arrays o métodos para el list box o por columna y definición a nivel de celdas (si son de texto multiestilo).

Cuando una misma propiedad se define en más de un nivel, el orden de prioridad es el siguiente:

Por ejemplo, si define un estilo de caracteres en las propiedades del list box y otro utilizando un array de estilo para la columna, se tendrá en cuenta este último.

Dado un list box cuyas filas tienen un color alterno gris/gris claro, definido en las propiedades del list box. Un array de color de fondo también se ha definido para el list box con el fin de cambiar el color de las filas en las que al menos un valor es negativo por naranja:

A continuación, vamos a colorear los valores negativos de color naranja oscuro. Para ello , se define un array de color de fondo para cada columna, por ejemplo ample <>_BgndColor_1, <>_BgndColor_2 and <>_BgndColor_3.  Los valores de estos arrays serán prioritarios sobre los definidos en las propiedades del list box, así como las del array general de color de fondo:

Puede obtener el mismo resultado utilizando los nuevos comandos LISTBOX SET ROW FONT STYLE y LISTBOX SET ROW COLOR. Tienen la ventaja de que le permite evitar tener que predefinir los arrays de
estilo/color de las columnas: son creados dinámicamente por los comandos.

Para cada atributo (estilo, color y color de fondo), la herencia se aplica cuando se utiliza el valor por defecto:

• para los atributos de las celdas: valores de atributos de líneas
• para los atributos de las líneas: valores de los atributos de las columnas
• para los atributos de las columnas: valores de los atributos del listbox

De esta manera, si quiere que un objeto herede el valor del atributo de un nivel superior, pase la constante lk inherited (valor por defecto) al comando de definición o directamente en el elemento del array de estilo/color correspondiente.

Dado un listbox que contiene una estilo de fuente estándar con colores alternativos: 

Puede realizar las modificaciones siguientes:

• cambiar el fondo de la fila 2 a rojo con la propiedad Array colores de fondo del objeto list box,
• cambiar el estilo de la fila 4 a itálica por la propiedad Array de estilos del objeto list box,
• dos elementos de la columna 5 se pasan a negrita por la propiedad Array de estilos del objeto columna 5,
• los elementos de la fila 2 de las columnas 1 y 2 se cambian a fondo azul utilizando la propiedad Array colores de fondo de los objetos columna 1 y 2:

• pase la constante lk inherited en los elementos 2 de los arrays de fondo de las columnas 1 y 2: a continuación, heredan el color de fondo rojo de la línea.
• pase la constante lk inherited en los elementos 3 y 4 de los arrays de estilo de la columna 5: entonces heredan el estilo estándar, excepto el elemento 4, que cambia a itálica como se define en el array de estilo del list box
• pase la constante lk inherited en el elemento 4 del array de estilo del list box con el fin de suprimir el estilo itálica.
• pase la constante lk inherited en el elemento 2 del array de colores de fondo del list box con el fin de restaurar el color alterno original del list box.

Puede definir las propiedades de interfaz "oculta", "desactivada" y "seleccionable"  para cada línea de list box de tipo array.

Estas funcionalidades se pueden manejar por medio del Array de control de líneas, el cual puede designar utilizando el comando LISTBOX SET ARRAY o vía la Lista de propiedades:

Un array de control de líneas debe ser de tipo Entero largo e incluir el número de líneas que el list box. Para obtener más información, consulte la sección Propiedades específicas de los list box.

Cada elemento del Array de control de líneas define el estado de la interfaz de la línea correspondiente en el list box. Tres propiedades de interfaz están disponibles usando las constantes del tema "List box":

Para cambiar el estado de una línea, sólo tiene que pasar las constantes apropiadas en el elemento correspondiente. Por ejemplo, si o quiere que la línea #10 sea seleccionable, puede escribir:

Puede definir varias propiedades de la interfaz a la vez:

Tenga en cuenta que la definición de una propiedad para un elemento anula cualquier otro valor de este elemento (si no reinicializa). Por ejemplo:

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 dinámicas de tipo array. Estos arrays dinámicos permanecen siempre y cuando el formulario exista. Una variable dinámica se crea igualmente para cada encabezado. Cuando se llama el comando LISTBOX GET ARRAYS, el parámetro arrVarCols contiene los punteros a los arrays dinámicos y el parámetro arrVarEncabezados contiene los punteros a las variables de encabezados dinámicos. 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: