Gestión de listas jerárquicas

Las listas jerárquicas son objetos de formulario que permiten mostrar los datos como listas con uno o más niveles que es posible expandir o contraer.

En los formularios, las listas jerárquicas pueden servir para visualizar o introducir datos. Cada elemento de la lista puede contener hasta 2 millardos de caracteres (tamaño máximo de un campo de texto) y estar asociado con un icono. Las listas jerárquicas por lo general soportan clic, doble clic y navegación con el teclado como también arrastrar y soltar. Es posible efectuar una búsqueda en el contenido de una lista (comando Find in list).

Las listas jerárquicas pueden ser creadas completamente por programación (vía los comandos New list o Copy list) o utilizando listas definidas en el editor de listas en el entorno Diseño (comando Load list).

Los contenidos y la apariencia de las listas jerárquicas son administrados por programación utilizando los comandos del tema "Listas jerárquicas". Ciertas características de apariencia específicas también pueden ser definidas utilizando comandos genéricos del tema Propiedades de los objetos (ver a continuación).

Puede asociar dinámicamente las referencias de listas jerárquicas  a las las listas de selección de objetos de formularios (fuentes, valores obligatorio y valores excluidos) utilizando los comandos OBJECT SET LIST BY REFERENCE o OBJECT SET LIST BY NAME. También puede asociar las listas de selección definidas en el editor de listas a los objetos de formularios vía la Lista de propiedades.

Una lista jerárquica es a la vez un objeto de lenguaje existente en memoria y un objeto de formulario.

El objeto de lenguaje se referencia de manera única por un identificador interno, de tipo Entero largo, diseñado por RefList en este manual. Este identificador es devuelto por los comandos que pueden ser utilizados para crear listas: New list, Copy list, Load list, BLOB to list. Existe una sola instancia en memoria del objeto de lenguaje y toda modificación que se lleve a cabo en este objeto inmediatamente repercute en todos los lugares donde se utiliza.

El objeto de formulario no es necesariamente único: puede haber varias representaciones de una misma lista jerárquica en un mismo formulario o en formularios diferentes. Como para los otros objetos de formulario, usted especifica el objeto en el lenguaje utilizando la sintaxis (*;"NomLista", etc.).

Usted conecta el "objeto de lenguaje" lista jerárquica con el "objeto de formulario" por intermedio de la variable que contiene el valor del identificador único RefLista. Por ejemplo, si escribe:

... es suficiente asociar el nombre de la variable milista al objeto de formulario Lista jerárquica en la lista de propiedades con el fin de que administre el objeto de lenguaje cuyo RefLista se guarda en milista

Cada representación de la lista tiene características propias como también características en común con las otras representaciones. Las siguientes características son específicas para cada representación de lista:

• La selección,
• El estado desplegado/contraído de sus elementos,
• La posición del cursor de desplazamiento,

Las otras características (fuente, estilo de fuente, estilo, filtro de entrada, color, contenido de la lista, iconos, etc.) son comunes a todas las representaciones y no pueden ser modificadas por separado.

Por lo tanto, cuando utilice comandos basados en la configuración expandida/contraída o el elemento actual, por ejemplo Count list items (cuando el parámetro * final no se pasa), es importante poder especificar sin ambigüedad la representación a utilizar.

Debe utilizar el identificador de tipo RefLista con los comandos del lenguaje cuando quiera especificar la lista jerárquica residente en memoria.

Si quiere especificar la representación a nivel de formulario de un objeto Lista jerárquica, debe utilizar el nombre del objeto (tipo cadena) en el comando, vía la sintaxis (*;"NomLista", etc.). Esta sintaxis es idéntica a la utilizada en los comandos del tema "Propiedades de los objetos". Es aceptada por la mayoría de los comandos del tema "Listas jerárquicas" que actúan sobre las propiedades de las listas (por favor consulte la descripción de los comandos de este tema).

Advertencia, en el caso de los comandos que definen propiedades, la sintaxis basada en el nombre del objeto no significa que sólo el objeto de formulario especificado será modificado por el comando, sino que la acción del comando estará basada en el estado de este objeto. Las características comunes de las listas jerárquicas siempre son modificadas en todas las representaciones.

Por ejemplo, si pasa la instrucción SET LIST ITEM FONT(*;"milista1";*;lafuente), está indicando que quiere modificar la fuente de la lista jerárquica asociada al objeto de formulario milista1. El comando tendrá en cuenta el elemento actual del objeto milista1 para definir el elemento a modificar, pero esta modificación será llevada a cabo en todas las representaciones de la lista en todos los procesos.

Como para los otros comandos de gestión de propiedades de objetos, es posible utilizar el carácter “@” en el parámetro ListName. En principio, esta sintaxis se utiliza para designar un conjunto de objetos en el formulario. Sin embargo, en el contexto de los comandos de listas jerárquicas, este principio no aplica en todos los casos. Esta sintaxis tendrá dos efectos diferentes dependiendo del tipo de comando:

• Para los comandos que definen las propiedades, esta sintaxis designa todos los objetos cuyo nombre corresponde (funcionamiento estándar). Por ejemplo, el parámetro "LH@" designa todos los objetos de tipo lista jerárquica cuyo nombre comienza con “LH.” Estos comandos son:
  DELETE FROM LIST,
  INSERT IN LIST
  SELECT LIST ITEMS BY POSITION
  SET LIST ITEM
  SET LIST ITEM FONT
  SET LIST ITEM ICON
  SET LIST ITEM PARAMETER
  SET LIST ITEM PROPERTIES
  
• Para los comandos que recuperan propiedades, esta sintaxis designa el primer objeto cuyo nombre corresponde. Estos comandos son:
  Count list items
  Find in list
  GET LIST ITEM
  Get list item font
  GET LIST ITEM ICON
  GET LIST ITEM PARAMETER
  GET LIST ITEM PROPERTIES
  List item parent
  List item position
  Selected list items
  

Es posible modificar la apariencia de una lista jerárquica en un formulario utilizando varios comandos 4D genéricos. Debe pasar a estos comandos bien sea el nombre del objeto de la lista jerárquica (utilizando el parámetro *) o su nombre de variable (sintaxis estándar).

Nota: en el caso de las listas jerárquicas, la variable del formulario contiene el valor de RefLista. Si ejecuta un comando que modifica un atributo pasándole la variable asociada a la lista jerárquica, no será posible definir la lista objetivo en el caso de las representaciones múltiples. Por lo tanto, sólo el nombre del objeto permite diferenciar individualmente cada representación.

Esta es una lista de comandos que pueden utilizarse con las listas jerárquicas. 

OBJECT SET FONT
OBJECT SET FONT STYLE
OBJECT SET FONT SIZE
OBJECT SET COLOR
OBJECT SET FILTER
OBJECT SET ENTERABLE
OBJECT SET SCROLLBAR VISIBLE
OBJECT SET SCROLL POSITION
OBJECT SET RGB COLORS

Recuerde: excepto por el comando OBJECT SET SCROLL POSITION, estos comandos modifican todas las representaciones de una misma lista, incluso si sólo especifica una lista vía su nombre de objeto.

Algunas propiedades de las listas jerárquicas (por ejemplo, el atributo editable o color) pueden definirse de tres maneras: vía la Lista de propiedades en el entorno Diseño, vía un comando del tema “Propiedades de los objetos” o vía un comando del tema “Listas jerárquicas”.

Cuando las tres maneras se utilizan para definir propiedades de una lista, se aplica el siguiente orden de prioridad:

1. Comandos del tema “Listas jerárquicas”
2. Comandos genéricos de propiedad del objeto
3. Parámetros de la Lista de propiedades

Este principio se aplica sin importar el orden en el cual se llaman los comandos. Si se modifica una propiedad del elemento individualmente vía un comando de lista jerárquica, el comando de propiedad del objeto equivalente no tendrá efecto en este elemento incluso si se llama posteriormente. Por ejemplo, si modifica el color de un elemento vía el comando SET LIST ITEM PROPERTIES, el comando OBJECT SET COLOR no tendrá efecto sobre este elemento.

Generalmente puede trabajar de dos formas con los contenidos de las listas jerárquicas: por posición o por referencia.

• Cuando trabaja por posición, 4D se basa en la posición relativa de los elementos en la lista mostrada en la pantalla para identificarlos. El resultado será diferente si los elementos jerárquicos están desplegados o contraídos. Note que en el caso de representaciones múltiples, cada objeto de formulario, tiene su propia configuración de elementos contraídos/desplegados.
• Cuando trabaja por referencia, 4D se basa en el número único refElemento de los elementos de la lista. Entonces cada elemento puede ser especificado individualmente, sin importar su posición o visualización en la lista jerárquica.

Cada elemento de una lista jerárquica tiene un número de referencia (refElemento) de tipo Entero largo. Este valor está destinado únicamente a su propio uso: 4D simplemente lo mantiene.

Advertencia: como número de referencia puede utilizar todo valor de tipo Entero largo, excepto 0. De hecho, para la mayoría de los comandos de este tema, el valor 0 se utiliza para especificar el último elemento añadido a la lista.

Estos son algunos consejos para utilizar números de referencia:

1. No necesita identificar cada elemento con un número único (nivel principiante).

• Primer ejemplo: usted construye por programación un sistema de pestañas, por ejemplo, una libreta de direcciones. Como el sistema devuelve el número de la pestaña seleccionada, probablemente necesite más información. En este caso, no se preocupe por los números de referencia de los elementos: pase cualquier valor (excepto 0) en el parámetro refElemento. Note que para un sistema de libreta de direcciones, puede predefinir una lista A, B, ..., Z en el entorno Diseño. Igualmente puede crearla por programación para eliminar las letras para las cuales no hay registros.

• Segundo ejemplo: trabajando con una base, usted construye progresivamente una lista de palabras claves. Puede guardar esta lista al final de cada sesión utilizando los comandos SAVE LIST o LIST TO BLOB y cargarla nuevamente al inicio de cada nueva sesión utilizando los comandos Load list o BLOB to list. Puede mostrar esta lista en una paleta flotante; cuando el usuario hace clic en una palabra clave de la lista, el elemento elegido se inserta en el área editable seleccionada del proceso del primer plano. También puede utilizar arrastrar y soltar. En todos los casos, lo importante es que usted sólo procesa el elemento seleccionado (por clic o arrastrar y soltar), porque los comandos Selected list items (en el caso de un clic) y DRAG AND DROP PROPERTIES devuelven la posición del elemento que usted debe procesar. Cuando utilice este valor de posición, obtiene el título del elemento gracias al comando GET LIST ITEM. Acá tampoco, necesita identificar cada elemento individualmente; puede pasar todo valor (excepto 0) en el parámetro refElemento.

2. Debe identificar parcialmente los elementos de la lista (nivel intermedio).

Utilice el número de referencia del elemento para guardar la información necesaria cuando trabaje con el elemento; este punto se detalla en el ejemplo del comando APPEND TO LIST. En este ejemplo, utilizamos los números de referencia del elemento para guardar los números de registros. Sin embargo, debemos poder establecer una distinción entre los elementos que corresponden a los registros [Departamentos] y los que corresponden a los registros [Empleados].

3. Debe identificar individualmente los elementos de la lista (nivel avanzado).

Usted programa una gestión elaborada de listas jerárquicas en las cual debe poder identificar individualmente cada elemento en todos los niveles de la lista. Una manera sencilla de implementar este funcionamiento es mantener un contador personal. Supongamos que crea una lista hlList utilizando el comando New list. En este momento, usted inicializa un contador vhlCounter en 1. Cada vez que usted llama APPEND TO LIST o INSERT IN LIST, se incrementa este contador (vhlCounter:=vhlCounter+1), y usted pasa el número del contador como número de referencia del elemento. El truco consiste en no disminuir el contador cuando borre elementos — el contador solo puede crecer. De esta forma, usted garantiza la unicidad de los números de referencia de los elementos. Como estos números son de tipo Entero largo, puede añadir o insertar más de dos millardos de elementos en una lista que ha sido reinicializada... (Sin embargo si está trabajando con grandes cantidades de elementos, esto generalmente significa que debe utilizar una tabla en lugar de una lista.)

Nota: si utiliza Operadores de bits, igualmente puede utilizar los números de referencia de los elementos para almacenar la información que puede ser alojada en un Entero largo, es decir 2 Enteros, valores de 4 bytes o 32 Booleanos.

En la mayoría de los casos, cuando utiliza listas jerárquicas en interfaces de usuario que sólo tratan con el elemento seleccionado (el cual recibió un clic o fue arrastrado), no necesitará utilizar los números de referencia de los elementos. La utilización de los comandos Selected list items y GET LIST ITEM le proporcionan toda la información necesaria para la gestión del elemento seleccionado actualmente. Además, los comandos tales como INSERT IN LIST y DELETE FROM LIST le permiten manipular la lista de manera “relativa” al elemento seleccionado.

Básicamente, necesita tratar con los números de referencia de los elementos cuando quiera acceder directamente por programación a cualquier elemento de la lista y no necesariamente al elemento actualmente seleccionado.