ClearLight: Sistemas para la Administracion

posExt.vbs: control paralelo de la aplicación

En la noticia de actualización correspondiente a la versión 2.32, de julio de 2002, se describe un mecanismo que permite la ejecución de un script que corre paralelo a la de la aplicación principal del punto de ventas.
Inicialmente, el único propósito de posExt era soportar la impresión “línea a línea” de las facturas en las impresoras fiscales.

Desde entonces, y respondiendo a diferentes necesidades, hemos aumentado considerablemente las llamadas realizadas a posExt (sobre todo desde las aplicaciones punto de ventas). El propósito de este documento es ofrecer una relación detallada de estas llamadas.

Sub AbrirGaveta:
Se llama desde las aplicaciones de punto de ventas despues de cerrarse la forma de ingreso de caja. Si posExt.vbs implementa este procedimiento, se cancela la llamada posterior a la apertura de caja en AbrirCaja.vbs. Si posExt mantiene abierto un dispositivo fiscal que se responsabilice de la apertura de la gaveta, otros componentes (por ejemplo AbrirCaja.vbs) no podrán acceder al dispositivo. En este caso, hay que utilizar el procedimiento AbrirGaveta en posExt, ya que desde este script se tiene acceso al dispositivo.

Sub CuentaCargada:
Se llama cuando se ha cargado una cuenta en la sesion activa. La información de la cuenta está disponible en la sesión. La cuenta es borrada despues de la carga.

Function CalcularPrecio:
Permite alterar el precio de venta de un producto en función de condiciones particulares (ofertas especiales, descuentos por volumen, etc).

La información sobre el detalle se encuentra en las siguientes variables:

Codigo: el código del producto
Cantidad: cantidad de unidades vendidas en el renglón
Precio: precio unitario
TipoImpuesto: código del tipo de impuesto correspondiente al producto

El valor devuelto será el nuevo precio unitario a utilizarse en el renglón.

El valor que se asigne desde esta función a la variable Cantidad será asumido por la aplicación como la cantidad de unidades a vender en el detalle en proceso.

Sub Initialize:
Este procedimiento es llamado al iniciar la ejecución de cualquiera de las aplicaciones de ClearLight. A partir de la version 5.5 la llamada se produce antes de la apertura de la BD.

Sub DataInitialized:
Es llamado desde todas las aplicaciones despues de haber inicializado el entorno de datos (incluida la apertura de la BD, la creacion de las clases AlmacenXX -no los almacenes de inventario sino los almacenes de datos y el usuario activo).

Sub Terminate:
Se llama al terminar la ejecución de la aplicación.

Sub AddRenglon(Codigo, Cantidad, Precio, PorcentajeImpuesto, TipoImpuesto, Descripcion):
Es llamada cada vez que un nuevo renglón es agregado a la sesión activa.

Sub EliminarTodo:
Se llama cuando el usuario pulsa el botón «EliminarTodo»
No es una función de validación, sino una notificación. Los renglones cargados en la forma de facturación aun estan disponibles en los detalles de la sesion activa, disponible a través del objeto SESION de la Factoria. La variable FromCuenta contiene el numero de la cuenta relacionada con la sesion.

Sub EliminarRenglon(pRenglon):
Notificación de la eliminación de un renglón. El argumento «pRenglon» contiene una referencia a un objeto de la clase «clsRenglonSesion» con la información del renglón que va a ser eliminado. La variable FromCuenta contiene el numero de la cuenta relacionada con la sesion.

Sub EliminarFactura(Numero):
Notificación de que se va a anular una factura de punto de ventas. El argumento «Numero» es el número único de la factura (no el número de ticket en función del terminal, sino un número único asignado por el sistema).

Sub FacturaAnulada(Numero):
Notificación de que una factura FUE anulada. En este momento ya no es posible acceder a la información original de la factura.

Sub SalvarFactura(Sesion):
Notificación de que va a comenzar el registro de una nueva factura de punto de ventas. «Sesion» es una referencia a la sesión activa.

Sub SetCuenta(Cuenta, Detalles)
Function DetallesDinamicos:
El procedimiento «SetCuenta» le informa al script que se está en proceso de cargar una cuenta.

La función «DetallesDinamicos» devuelve una colección de objetos de la clase «clsRenglonSesion» que contiene detalles de consumo adicionales. Estas funciones se agregaron para un establecimiento donde ciertas mesas tienen un expendedor de bebidas, de los cuales el cliente se sirve libremente. Al cargar la cuenta se trae la información de la cantidad de bebida expendida desde que la cuenta se abrió, y se suma a los detalles por otros conceptos de consumo. Normalmente se usa en combinación con clrCaja4.

Hay que tener cuidado al usar estos servicios: la función es llamada cada vez que una cuenta se carga. Si, por ejemplo, se carga una cuenta, se realiza algun cambio y se guarda nuevamente (esto puede hacerse en clrCaja y clrCaja5) los detalles dinámicos calculados al cargar la cuenta se convierten en detalles estáticos al gurdarla nuevamente. En determinados escenarios, si no se tiene cuidado, esto puede llevar a la doble carga de detalles.

Sub PostIngresoCaja(Ingreso):
Notificación de que se han aceptado los medios de pago. «Ingreso» es una referencia an movimiento de caja que contiene los datos del pago.

Function GuardarCuenta:
Devuelve un valor lógico que determina si se pueden mover a una cuenta los consumos cargados en la forma de facturación activa.

Sub CuentaGuardada(Cuenta):
Notificacion de que la cuenta cuya referencia se pasa en el argumento Cuenta acaba de ser guardada.

Sub CerrarDelivery(Cuenta):
Notificación de que se ha cerrado una cuenta de delivery (sólo en clrCaja4.exe). La información de la cuenta está disponible en el argumento «Cuenta» (una instancia de «clsCuentaPOS»). Al momento de la llamada, los detalles de la cuenta ya no están disponibles, y la cuenta ha sido eliminada de la DB.

Sub ImprimirComanda(Descripcion):
Solo se usa desde clrCaja4.exe. Se acaba de agregar a la forma de registro de consumos un detalle cuya descripción detallada (producto base, extras, opciones, etc) está contenida en el argumento Descripcion (una cadena de caracteres). ADVERTENCIA: para el momento de llamar a esta función, el consumo NO ESTA ASOCIADO con ninguna cuenta (o mesa). Se llama solamente si está activada la opción “ComandaPorLinea” en el registro. La impresión de las comandas al pasarlas a una cuenta se realiza mediante el script “ImprimirComandaCuenta.vbs”.

Sub CobroDeliveryLoaded(f):
Notificación de que se cargo la forma de cobro de delivery. El argumento «f» se refiere a una instancia de la forma «frmCobroDelivery».

Function SePuedeVender(Codigo, Cantidad, Precio):
Esta función es llamada (si está definida) cada vez que una forma de facturación de punto de ventas intenta agregar un renglon a una sesion. Puede utilizarse para impedir la venta de productos inactivos, para limitar la cantidad de unidades vendidas (practica normal en este pais de carestías que se ha vuelto Venezuela) o para verificar que los precios de venta estén dentro de cierto rango, impidiendo asi que los operadores den descuentos excesivos.

Sub PostFactura(Factura):
Se usa para notificar al script que se acaba de procesar una factura. Es llamada antes de imprimir el documento. La factura que acaba de procesarse es pasada como argumento.

Sub ExtenderResumenPOS(Sesion, frmSalida):
Permite agregar información al reporte de resumen de una sesion (Cierre X). «Sesion» es una referencia a la sesión cuyo resumen se está emitiendo, «frmSalida» es una instancia de lfQuickView, la clase utilizada para presentar los listados en ClearLight. La función es llamada inmediatamente antes de mostrar el reporte en pantalla.

Function ValidarAtributo(codigoAtributo, ValorAtributo, TipoEntidad, CodigoEntidad):
Es llamada desde el programa principal (ClearLight.exe) cada vez que se intenta crear un nuevo atributo para una entidad. Permite que el usuario defina reglas para la validación de los nuevos atributos.

Sub CodigoInvalido(Codigo):
Se notifica al script de que el operador intentó pasar un código de producto invalido (cuyo valor se pasa en el argumento Codigo). Se agregó para activar una alarma auditiva imposble de ignorar para el cajero, impidiendo asi que se omitieran productos en la facturación.

Function GetEntidad(Tipo), Function GetItem(Tipo):
Permite que un componente externo (DLL) suministre al programa principal instancias de nuevas entidades no contempladas en el diseño original. Una empresa de transporte, por ejemplo, podria incluir las unidades de transporte como elementos de ClearLight. Estas entidades deben satisfacer los requerimientos de la Interfaz Standard de Personas Comerciales (ISPC).

Function GetDocumento(Tipo):
Permite que un componente externo (DLL) suministre al programa principal instancias de nuevos documentos no contemplados en el diseño original. Esa misma empresa de transporte podria incluir los Boletos como elementos de ClearLight. Estos documentos deben conformarse segun la Interfaz Standard de Documentos Comerciales (ISDOC).

Sub SesionMudada(Sesion, EquipoOrigen, NuevoEquipo):
Se notifica que la sesion referenciada por el argumento Sesion ha sido transferida desde el terminal indicado por EquipoOrigen al terminal identificado por EquipoDestino.

Function ValorServicio():
Permite que el script determine el valor del cargo por servicio para la venta cuyos detalles están cargados en la sesion activa.

Function AnularFactura(NumeroTicket):
Determina si la factura identificada por NumeroTicket (correspondiente a la sesion activa) puede ser anulada por el operador.

Sub SesionCreada(numTerminal, idUsuario, NumeroSesion):
Notificacion de que una sesion de trabajo ha sido creada con el numero NumeroSesion en el terminal identificado con numTerminal para el usuario cuyo codigo se pasa en idUsuario.

Sub ExtenderResumenSesion(Sesion, fView):
Permite que el usuario envíe información adicional al listado de resumen (X) de la sesion Sesion. fView es una instancia de la clase (forma) lfQuickView.

Sub SetFormaItems(laForma):
Es llamada desde la tabla de edicion rapida de roductos y servicios (ClearLight) para pasarle al script una referencia a la forma de edición rapida (laForma) para la cual esta a punto de cargarse un nuevo conjunto de datos, de manera que sepa a que ventana referirse para obtener los datos que le permitiran definir la consulta SQL que determinara los nuevos datos.

Function QueryFormaItems():
Devuelve la clausula de selección (lo que viene despues del WHERE y antes del ORDER BY) de una consulta SQL que se empleará para obtener un conjunto de productos a cargarse en la forma de edicion rapida. La forma en cuestión ha sido pasada previamente mediante la sub SetFormaItems.

Sub ProcesarCobranza(ProcesadorCobranzas):
Es llamada desde una instancia de CProcesadorCobranza (la clase responsable de procesar los datos de las cobranzas realizadas a los clientes). La llamada se realiza desde dentro de una transaccion de la BD, por lo que no es recomendable que haya ninguna interacción con el usuario ni con dispositivos de salida dentro de esta rutina. El argumento ProcesadorCobranzas es una referencia a la instancia de CProcesadorCobranzas que está realizando el proceso.
La forma de cobranzas llama a la función Main del script postCobroCuenta.vbs, habiendo definido la variable Forma con una referencia a la forma donde se introdujeron los datos de los pagos recibdos, y opcionalmente (si el cobro se realizó mediante un deposito directo) la variable pBanco, una instancia de clsBancos cargada con los datos del banco donde se realizó el deposito.

Sub AjustarDetalle(elDetalle):
Es llamada desde el formulario de carga de detalles en clrCaja (v6.1.2), clrCaja5 (v6.1.5) y clrCaja8 (v6.1.5).
elDetalle es una instancia de clsRenglonSesion con las propiedades codigoItem, PrecioUnitario y Cantidad cargadas con el código, precio de venta propuesto y cantidad de unidades que acaban de ser pasadas en el formulario de punto de ventas. Los cambios que AjustarDetalle haga sobre los valores de estas propiedades almacenadas en elDetalle serán registrados en la factura.
La intención es permitir la implementación de descuentos o transformaciones por volúmen para ciertos artículos.

Sub TransferirCuenta(cuentaOrigen, cuentaDestino):
Es llamada desde clsCuentasPos.Transferir, que normalmente se activa durante el traslado de consumos entre cuentas (Mesas) en clrCaja4 y clrCaja7.
cuentaOrigen y cuentaDestino son enteros largos que contienen los números de identificación de las cuentas respectivas. (clrCaja4.exe: v6.7.3, clrCaja7.exe: v6.7.2)

Function AjustarPrecioPOS(codigo, precio):
Es llamada desde las aplicaciones de punto de ventas (clrCaja, clrCaja5, clrCaja8 y clrCaja11) para permitir ajustar el precio de venta de un producto.
En las tres primeras el argumento codigo contiene el valor exacto introducido por el usuario. En clrCaja11 contiene el código del producto (que puede ser diferente del valor introducido por el operador).
El argumento precio contiene el precio "normal" de venta.
El valor devuelto es tomado como precio unitario de venta para el renglón en proceso.

Function AjustarCantidadPOS(codigo, cantidad):
Es llamada desde las aplicaciones de punto de ventas (clrCaja, clrCaja5, clrCaja8 y clrCaja11) para permitir ajustar la cantidad de unidades vendidas.
En las tres primeras el argumento codigo contiene el valor exacto introducido por el usuario. En clrCaja11 contiene el código del producto (que puede ser diferente del valor introducido por el operador).
El argumento cantidad contiene la cantidad de unidades obtenida a partir de la entrada del usuario.
El valor devuelto es tomado como la cantidad de unidades vendidas para el renglón en proceso.

Funciones genericas de validacion:

A partir del 7 de noviembre de 2007, la funcionalidad de las "dll de Forma" (usrDLL) puede ser implementada igualmente mediante código contenido en posExt.vbs.

El nombre de una rutina de validación para un evento tiene la siguiente forma:

<NombreForma>_<NombreControl>_<Evento>

por ejemplo: frmFacturacionCompleta_txFechaFactura_LostFocus. Los nombres de las formas y de los controles pueden ser consultados en el documentador. La información detallada sobre los eventos y su mecanismo de activación está descrita aquí.

La validación está implementada como una operación en dos partes. Primero se llama a la rutina de validación, pasándole los argumentos necesarios, y luego se obtiene el resultado, consultando la variable isValid.

El siguiente ejemplo exige que las fechas de la forma de facturación de distribución pertenezca al mes actual:

Public isValid ' (As Boolean): se usa para devolver los resultados de las validaciones genéricas

Public Sub frmFacturacionCompleta_txFechaFactura_LostFocus(pForm, pControl)
    isValid = True
    If Month(pControl.Fecha) <> Month(Date) Then
        isValid = False
        MsgBox "La factura debe ser de este mes", vbCritical, "Error de validacion"
        Exit Sub
    End If
End Sub

frmFechaFactura es el nombre del formulario, txFechaFactura el del control y LostFocus el nombre del evento pasado por la aplicación al activador de la DLL de la forma (que ahora tambien activa una rutina en posExt.vbs).

La rutina llamada debe condicionar el valor de la variable isValid. Si el contenido del control es válido, debe asignarsele el valor True. De lo contrario -es decir, si no se quiere acetar el valor- debe asignársele False. Es importante, si se van a usar estas rutinas de validación, que se asigne True a isValid cuando el valor sea valido. De lo contrario, no será posible continuar adelante con la edición del formulario.

ADVERTENCIA: La llamada a la rutina de validación en posExt.vbs se realiza antes de la llamada a la función correspondiente de la DLL de usuario (si existe). Cualquier error en el script causará que la rutina de validación se interrumpa sin dar ninguna advertencia antes de llamar a la función correspondiente de la DLL.

Detectar las teclas presionadas en un formulario:

Las revisiones a partir de 21/06/2008 permiten que posExt responda directamente a las pulsaciones de teclas sobre los formularios que soportan CUsrDLL.

Para ello se pueden implementar en posExt los procedimientos <nombreForma>_KeyPress(Forma, KeyAscii) o <nombreForma>_KeyDown(Forma, keyCode, Shift). La primera detecta las teclas que generan caracteres, y el segundo se genera con la pulsación de cualquier tecla. El primero recibe en KeyAscii el valor ASCII del caracter pulsado, el segundo recibe el código de teclado (scan code) de la tecla apretada. En ambos casos, Forma es una referencia al formulario.

Ejemplo:

Un cliente acostumbrado a facturar con el precio neto (sin el IVA incluido) quiere ocasionalmente indicar el precio final de los productos (incluyendo el IVA). Su aplicación anterior tenía una tecla para este fin: escribes el precio incluyendo el impuesto, pulsas esa tecla y el impuesto se elimina.

Lo implementamos en posExt, de la siguiente manera:

Private Sub CalcularPrecioNeto(form, Dest) ' Suprimir el IVA
Dim r, item, p

With form.flxDetalles
    r = .Row
    Set item = CrearObjeto("AlmacenItemsVenta").ItemVenta(.TextMatrix(r, 0))
    If item Is Nothing Then _
      Exit Sub
End With

p = item.PorcentajeImpuesto(1)
p = Dest.Value / (1 + (p / 100))
Dest.Value = p
End Sub

Public Sub frmFacturacionCompleta_KeyDown(Form, KeyCode, Shift)
Dim s

If KeyCode <> 115 Then Exit Sub ' {F4}

s = Form.ActiveControl.Name
If s = "txPrecioVenta" Or _
     s = "txPrecioLista" Or _
     s = "txPrecioTotal" Then _
        CalcularPrecioNeto Form, Form.ActiveControl
End Sub

Como asociamos el mecanismo con una tecla de función, tuvimos que implementarlo en el evento KeyDown (KeyPress no "ve" las teclas de función).

La forma de facturación se llama frmFacturacionCompleta, de manera que el nombre de la función será frmFacturacionCompleta_KeyDown.

La lógica es simplisima: si la tecla pulsada no es F4, salimos sin hacer nada.

Determinamos si el control activo en el formulario es alguno de los que permite la lectura de precios (txPrecioVenta, txPrecioLista o txTotal).

Si es alguno de estos controles, llamamos a una función que determina el porcentaje de impuesto y lo elimina del precio registrado en el control.