Gestión de los objetos de tipo List box

versión 11.3 (Modificado)

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

Los list boxes son comparables con las Áreas de desplazamiento agrupadas. Un list box ofrece todas las funciones de las áreas de desplazamiento agrupadas, principalmente la posibilidad de representar los datos en forma de columnas y de filas seleccionables. Sin embargo, los list box hacen más que esto, incluyendo la posibilidad de introducir valores, ordenar columnas, 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 List boxes en el editor de formularios como también sobre su uso, consulte el Manual de Diseño.

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.

Nota: los List box son objetos diseñados únicamente para interfaces de pantalla. No es posible imprimirlos.

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 SET FORMAT.

Utilizando el lenguaje, los valores de las columnas (entrada y visualización de datos) son administrados utilizando los comandos de alto nivel del tema List box (tales como INSERT LISTBOX ROW o DELETE LISTBOX ROW) 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:

   ARRAY TEXT(NomColumna; tamano)

Igualmente puede utilizar una lista:

   LIST TO ARRAY("NomLista"; NomColumna)

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 el número de elementos del array más pequeño (columna) será mostrado. 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 es evaluado 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 INSERT LISTBOX ROW y DELETE LISTBOX ROW 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 SET LISTBOX TABLE SOURCE puede utilizarse para modificar la tabla asociada con el list box por programación.

Un objeto List box está compuesto de tres tipos de elementos separados:

• el objeto mismo,

• las columnas,

• y los títulos de las columnas.

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 son llamadas Columna1 a X y los títulos Título1 a X en el formulario, independientemente de los objetos list box.

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 y a los títulos. 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 y/o títulos de 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 list boxes:

Notas:

• Todos los comandos del tema "List Box" aplican únicamente a los objetos List box, a excepción del comando SET LISTBOX COLUMN WIDTH (aplica a objeto, columna y encabezado) y el comando Get listbox column width (aplica a columna y título únicamente).

• 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 cone el list box en la lista de propiedades. Puede recuperar los nombres de estos arrays por programación utilizando el comando GET LIST BOX ARRAYS.

Es posible añadir un método de objeto al objeto list box 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 cada columna

2. Método de objeto del list box

El método de objeto de la columna recibe los eventos que ocurren en su título.

Cuando el comando SET VISIBLE se utiliza con un encabezado, se utiliza en todos los encabezados del objeto List box, sin importar el título definido en el comando. Por ejemplo, la instrucción SET VISIBLE(*;"título3";False) ocultará todos los títulos del objeto List box al cual pertenece titulo3 y no únicamente este encabezado.

La función Self (tema "Lenguaje") puede utilizarse en el método de objeto de un list box o de una columna de list box. En el caso de un evento de formulario On Clicked u On Header Click, devuelve respectivamente un puntero a la variable de la columna o a la variable del título en función de donde ocurrió el clic.

La función Focus object (tema "Interfaz usuario") y Self (tema "Lenguaje") pueden utilizarse en el método de objeto de un list box o una columna list box. Devuelven un puntero al list box, la columna(1) list box o la variable del encabezado dependiendo dle tipo de evento de formulario. La siguiente tabla detalla este funcionamiento:

(*) Cuando el foco se modifica dentro de un list box, se devuelve un puntero a la columna. 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 punero a la columna.

(**) No ejecutado en el contexto de un método de objeto 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 Focus object (tema "Interfaz del usuario") devuelve un puntero a la columna del list box con el foco (ej. a un array). El mecanismo de punteros 4D le permite ver el número de elemento del array modificado. Por ejemplo, suponiendo que el usuario modificó la quinta fila de la columna col2:

   $Column:=Focus object
      ` $Column contiene un puntero a col2
   $Fila:= $Column->   `$Fila igual a 5

En el caso de un list box de tipo selección, la función Focus object 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 SCROLL LINES (tema "Interfaz usuario) puede utilizarse con un list box. Este comando permite desplazarse por las filas del list box de manera que la primera fila seleccionada o una fila específica se muestre.

El comando EDIT ITEM (tema "Gestión de entrada") le permite pasar a modo edición una celda de un objeto 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.

Eventos de formulario específicos están destinados a facilitar la gestión 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.

El administrar el arrastrar y soltar de datos en list boxes está soportado por los comandos Drop position y DRAG AND DROP PROPERTIES. Estos comandos han sido especialmente para list boxes.

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

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.

El desarrollador puede configurar ordenaciones personalizadas utilizando el comando SORT LISTBOX COLUMNS y/o combinando los eventos de formulario On Header Click y On After Sort (ver el comando Form event) y los comandos 4D de gestión de arrays.

Nota: la propiedad "Ordenable" únicamente afecta la ordenación del usuario estándar; el comando SORT LISTBOX 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 dependiendo de si el list box está basado en un array o en una 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 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, usted no puede 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):

   ARRAY BOOLEAN(tBListBox;10)
      ` tBListBox es el nombre de la variable asociada al list box en el formulario
   If (tBListBox{1} = True)
      tBListBox{1}:= False
   Else
      tBListBox{1}:= True
   End if