22 Dic Introducción a los objetos de lista

En el proyecto de aplicación de nuestra solución disponemos de un conjunto de objetos con los que podemos gestionar listas de registros de una determinada tabla. El objeto más conocido es la Rejilla porque su funcionalidad es la más extensa, aunque existen otros objetos de lista visualmente más atractivos para mostrar los datos al usuario.

Los objetos de lista

Hagamos un repaso de todos los objetos de lista, analizando a fondo aquellos aspectos más interesantes para el programador.

Enumeramos los objetos de lista disponibles:

1. Rejilla: Conjunto de celdas distribuidas en filas y columnas. Una fila se corresponde con un registro de la tabla y una columna con un campo de dicha tabla.
2. Árbol visor de tablas: Presenta, en distintos niveles, la información de una tabla con clave arbolada.
3. Bloc de formularios: Permite editar en un formulario cada uno de los registros de una tabla.
4. Casillero: Está compuesto por una serie de celdas (o casillas) distribuidas en filas y columnas. Cada celda permitirá mostrar un formulario de un registro de la tabla. Cada celda a su vez es un botón que permite disparar un comando al hacer clic sobre él.
5. ComboView: Presenta una lista desplegable de registros de la tabla.
6. Informe: Se utilizarán para enviar información de los registros de una lista de la tabla a una impresora o a un documento PDF en disco.
7. ListView: Presenta una lista de registros de la tabla en una zona con scroll.
8. Lista QML: Aprovecha toda la potencia gráfica de QML para mostrar listas de registros de una o varias tablas.
9. ViewFlow: Usa un modo gráfico a modo de presentación de diapositivas para mostrar un formulario o campo dibujo por cada registro de la tabla.
10. Rejilla avanzada: Partiendo de una Rejilla normal podemos crear otro Rejilla con opciones avanzadas, disponibles por el usuario en tiempo de ejecución.
11. Alternador de lista: En este objeto podemos declarar múltiples objeto de salida (rejilla, informe, casillero, …) entre los que el usuario final podrá alternar en tiempo de ejecución.
12. MultiVista: Permite presentar varios objetos sincronizados en función de su entrada y salida.

Características comunes a los objetos de lista

Algunas características comunes a todos ellos son:

• Los objetos de lista implementan el esquema Modelo/Vista (Model/View) a la hora de mostrar los datos de una tabla. El Modelo se corresponde con la Lista de entrada y la Vista es el propio objeto que proporciona el interface para que el usuario pueda interactuar con los datos de entrada. Por lo tanto, el objeto de lista necesita siempre una Lista de entrada para que pueda mostrar registros de la tabla. La propiedad Tabla asociada determina a qué tabla del proyecto pertenece la Lista de entrada.
• En la mayoría de objetos de lista podemos añadir, modificar o eliminar fichas o registros de la lista de entrada. Para ello especificaremos el Formulario de alta, modificación y baja, lo cual activa automáticamente las teclas Ins para mostrar el formulario de Inserción y Supr para el formulario de eliminación de la ficha seleccionada. El formulario de modificación se muestra haciendo doble click sobre la ficha seleccionada o con las teclas Enter/Return/Barra espacio. Existe la opción de mostrar un menú contextual por defecto que mostrará las opciones de Alta, Modificación y Baja de ficha. En este caso existe un problema, el menú por defecto seguirá mostrando todas las opciones aunque no hayamos especificado algún formulario de alta, modificación o baja. En ese caso usaremos un Menú personalizado.
• En todos los objetos de lista se pueden definir los subobjetos Conexión de evento, Manejador de evento, Variable y en la mayoría el Drop. Estos subobjetos permiten encapsular código en los objetos de lista y de esta forma darles funcionalidad que podremos aprovechar en múltiples lugares de nuestra aplicación.

El evento de drag&drop permite seleccionar registros en un objeto de lista para soltarlos en otro objeto de lista. Consultar los siguientes enlaces: qué es drag&drop, ejemplo drag&drop de ayudavelneo y tutor de drag&drop.

• Los objetos de lista se pueden mostrar en el interface de 3 formas:
  • Como un control «Vista de datos« incrustado en el formulario.
  • Como un objeto incrustado directamente en una ventana independiente (en modo Vista o Modal) mediante un objeto «Acción«.
  • Disparar el objeto desde un proceso con el comando «Crear manejador de objeto()«, en este último caso la ventana siempre es Modal, es decir, la ejecución del proceso se interrumpe hasta que se cierra la ventana contenedora del objeto de lista.
• Además desde el API podemos disparar una Acción con theMainWindow.runAction() o instanciar el objeto mediante la clase VDataViewDialog.

Veamos un ejemplo:

Queremos mostrar un Casillero CAS_ARTICULOS con datos de la tabla ARTICULOS. Se ha preparado un formulario FRM_ARTICULOS_CAS con cuatro campos de la tabla y lo asignaremos a la propiedad Formulario del objeto CAS_ARTICULOS.

Necesitamos un proceso que proporcione la Lista de entrada para el objeto CAS_ARTICULOS.

Rem ( Proceso PRO_LISTA_ARTICULOS - Entrada ninguna y Salida la Lista de Artículos)
Rem ( Obtenemos la Lista de Artículos que alimentará nuestro objeto de lista)
Cargar lista ( ARTICULOS@facturas_dat, ID, , , , )
        Añadir lista a la salida

Para insertar el control Vista de datos en un formulario que muestre el objeto CAS_ARTICULOS nevesitamos 2 objetos:
       Objeto 1: PRO_LISTA_ARTICULOS@facturas_app
       Objeto 2: CAS_ARTICULOS@facturas_app

Para mostrar el casillero en una ventana independiente en modo Vista necesitamos un objeto Acción ACC_ARTICULOS_CAS que nos permita encadenar el proceso y el objeto de lista tal como hemos visto en el control Vista de datos. En el objeto ACC_ARTICULOS_CAS seleccionamos el comando Disparar objetos y elegimos el proceso PRO_LISTA_ARTICULOS y el Casillero CAS_ARTICULOS.

Una Acción es el objeto del proyecto de aplicación que permite disparar un comando. Éste puede ser un comando en stock (preprogramado) o un comando programado que, en general, disparará objetos.

Rem ( Mostrar el Casillero en modo Vista )
Interfaz: Ejecutar acción ( ACC_ARTICULOS_CAS@facturas_app )

El comando Crear manejador de objeto muestra el objeto de lista en una ventana Modal o en cuadro de diálogo.

Rem ( Mostrar el Casillero en una Ventana Modal )
Crear manejador de objeto ( hCasillero, Casillero CAS_ARTICULOS@facturas_app )
Rem ( Obtenemos la lista de entrada y la añadimos al objeto de lista)
Cargar lista ( ARTICULOS@facturas_dat, NAME, , , , )
        Añadir lista al objeto ( hCasillero )
Rem ( Mostramos la ventana Modal. El proceso se detiene hasta que se cierra la ventana )
Disparar objeto ( hCasillero, No aplicable, LOK )

Con el API y la clase VDataViewDialog también podemos hacer algo equivalente:

// Instanciamos objeto Lista en modo Vista ejecutando una Acción del proyecto
theMainWindow.runAction("facturas_app/ACC_ARTICULOS_CAS")

// Usando la clase VDataViewDialog para mostrar el Casillero en Ventana Modal o cuadro de Diálogo
// Obtenemos la lista de entrada
var oLista = new VRegisterList(theRoot)
if (oLista.setTable("facturas_dat/ARTICULOS")) {
        if (oLista.load("ID", [])) {
                // Instanciamos el Casillero
                var oCasillero = new VDataViewDialog(theRoot)
                oCasillero.setDataView(17, "facturas_app/CAS_ARTICULOS")
                // Alimentamos la entrada
                if (oCasillero.setRegisterList(oLista)) {
                        // Ejecutamos el objeto. El script se detiene hasta que cerramos la ventana modal.
                        oCasillero.exec()
                }
        }
}

• A todos los objetos de lista se les puede asociar una Barra de herramientas (Toolbar) que irá situada en la parte superior o inferior.

Una Toolbar o Barra de herramientas es un objeto de interfaz gráfica que contiene botones que al ser presionados activan ciertas funciones de una aplicación. Cada botón de la toolbar disparará un objeto (Acción o Menú) declarado en el proyecto en curso o en los proyectos heredados o un menú en stock.

Los botones de la Barra de herramientas solo puede disparar Acciones o menús.
El uso más común es mostrar al Usuario de forma gráfica las opciones de Añadir, Modificar y Eliminar.

Las 3 Acciones son:

• Ficha: Formulario de alta – Muestra el formulario indicado en la Acción o en su defecto el indicado en el objeto de lista.
• Ficha: Formulario de modificación – Muestra el formulario indicado en el objeto de lista.
• Ficha: Formulario de baja – Muestra el formulario indicado en el objeto de lista.

Estas tres Acciones refrescan automáticamente la Ficha afectada del objeto de lista.
Si queremos refrescar la lista del objeto de lista no funcionará el comando Interfaz: Recalcular(), éste solo se puede aplicar a un control Vista de datos ya que necesitamos ejecutar de nuevo el proceso que alimenta la lista de entrada del objeto de lista.

¿Cómo podemos refrescar la lista del objeto de lista desde su propio manejador de evento?
Creamos un botón en la Toolbar cuya Acción ejecuta el comando Disparar señal. En el objeto de lista una conexión de evento captura la señal Acción disparada y ejecuta el siguiente manejador:

Rem ( El comando Recalcular() no funciona en el contexto del objeto de lista )
// Interfaz: Recalcular ( )
Libre
Rem ( Usamos una Cesta local para recargar la lista en el objeto de lista )
Cesta: Crear cesta local ( ARTICULOS@facturas_dat, cesArt )
Cargar lista ( ARTICULOS@facturas_dat, NAME, , , , )
Cesta: Agregar lista a la cesta ( cesArt )
Cortar lista ( 0, )
Cesta: Agregar a la lista en curso ( cesArt )
Seleccionar ficha por posición ( 1 )

• La clase del API VAbstractListDataView es la clase base de todos los objetos de lista. Con VAbstractListDataView tendremos acceso a funciones relacionadas con la lista asociada al objeto de lista. Para cada tipo de objeto de lista (rejilla, casillero, …) disponemos de la correspondiente clase que hereda de VAbstractListDataView que proporciona funciones específicas para la interfaz.

Veamos un ejemplo de un manejador de evento javascript que se dispara en el objeto de lista mediante una Acción que ejecuta el comando Disparar señal. Es un código genérico que podemos usar en cualquier objeto de lista independientemente de su tipo y de la tabla asociada.

// Manejador BUSCAR_LISTA_JS genérico que sirve para cualquier objeto de lista
// Obtenemos el objeto de lista
var oObjetoLista = theRoot.dataView()

// Obtenemos la Lista asociada al objeto de lista
var oLista = new VRegisterList(theRoot)
if (oObjetoLista.getList(oLista)) {
        // Tabla de la lista (alias/idTabla)
        var cTabla = oLista.tableInfo().idRef()
        // Instanciamos un registro de la Tabla para seleccionar una Ficha en la Lista
        var oRegistro = new VRegister(theRoot)
        if (oRegistro.setTable(cTabla)) {
                // Buscamos un registro por el índice ID único
                var cIDArt = prompt("ID del elemento de la Lista", "", "Búsqueda")
                if (cIDArt.length > 0) {
                        // Localizamos un registro por el Índice único
                        if (oRegistro.readRegister("ID", [cIDArt], VRegister.SearchThis)) {
                                oObjetoLista.setCurrentSelect(oRegistro)
                                // Edita el registro de la Lista
                                oObjetoLista.execEditForm()
                        }
                        else alert("No existe el elemento en la Lista", "Búsqueda")
                }
        }
}

Estas son algunas de las funcionalidades comunes a los objetos de lista.

En un próximo artículo repasaremos las peculiaridades de cada tipo de los objetos de lista y comprobaremos lo sencillo que resulta con Velneo mostrar una lista de registros de múltiples maneras solo con cambiar el objeto de lista, recuerda el esquema Modelo/Vista, un solo modelo y múltiples vistas.

¿Qué objetos de lista utilizas tú? 

Me gustaría escuchar tu opinión. Déjame un comentario más abajo.