Técnicas para una interfaz alternativa de Report Preview

Artículo original: Techniques for an alternative Report Preview UI
http://www.spacefold.com/colin/archive/articles/reportpreview/techniques.htm
Autor: Colin Nicholls
Traducido por: Ana María Bisbé York

---

Antes de comenzar

Un grupo importante de los debates sobre informes en VFP de estos últimos tiempos en Universal Thread (http://www.universalthread.com) se han referido al tema de la nueva pantalla de presentación preliminar (Report Preview) y cómo controlarla. Un aspecto particularmente debatido es el comportamiento de la barra de herramientas cuando empleamos REPORT FORM ... PREVIEW en una aplicación de nivel superior. Existe un bug en VFP 9.0 (vea el código para reproducirlo en http://www.spacefold.com/colin/archive/articles/reportpreview/repro.txt) que provoca que la barra de herramientas asociada sea visible, aunque inhabilitada a los clics del ratón. La funcionalidad existe a través del menú contextual de la ventana preliminar, pero esto se convierte en un problema de educación de los usuarios o hay que utilizar NOWAIT para forzar que la ventana preliminar se muestre como una forma no modal. ( Esto no es un gran problema, ahora que tenemos la cláusula NOPAGEEJECT en el comando report form. Muchas de las razones por la que la gente piensa que necesitan una ventana modal no se aplican.

No obstante de los bugs del producto, en mis sesiones me esfuerzo por mostrar que la presentación preliminar predeterminada es sólo eso - predeterminada - y que ahora, no sólo son posible formularios con soluciones alternativas, sino que son fáciles de implementar. Entonces, voy a mostrar hoy una interfaz de usuario alternativa para la ventana de presentación preliminar que puede utilizar y personalizar acorde a sus contenidos.

He aquí una presentación preliminar.

Esto es lo que estamos construyendo:

Es un formulario sencillo con algunos botones y un contenedor en el que reside un control forma (shape) en el que se generará una única página del informe. El formulario permite hacer acercamientos y alejamientos (zoom) y arrastrar la página, empleando el ratón, por dentro del contenedor.

Realmente, aquí no hay mucho que hacer.

Crear el marco preliminar

*------------------------------------------------
* Marco preliminar...
*------------------------------------------------
define class myFrame as Container
  Width = 296
  Height = 372
  Left = 12
  Top = 12
  SpecialEffect = 1
  BackColor = rgb(192,192,192)

  add Object canvas as myCanvas && vea debajo:
enddefine

*------------------------------------------------
* ...y su forma hija:
*------------------------------------------------
define class myCanvas as Shape
  Height = 330
  Width = 255
  Left = 20
  Top = 20
  BackColor = rgb(255,255,255)

Vamos a permitir que la forma se mueva dentro del marco añadiendo código al evento .MouseDown del objeto Shape.

  procedure MouseDown
    lparameters nButton, nShift, nXCoord, nYCoord

    offsetX = m.nXCoord - THIS.Left
    offsetY = m.nYCoord - THIS.Top
  
    THISFORM.MousePointer = 5
    do while mdown()
      THIS.Left = mcol(0,3) - m.offsetX
      THIS.Top = mrow(0,3) - m.offsetY
    enddo
    THISFORM.MousePointer = 0 
  endproc
enddefine

El .MousePointer de 5 es el puntero del ratón que muestra ambas flechas NSEO en lugar de un cursor normal. Puede verlo en la figura mostrada antes.

Crear la clase form

Ahora que ya tenemos el marco, podemos crear la clase form myPreview y colocarlo en el marco:

*------------------------------------------------
* La clase form:
*------------------------------------------------
define class myPreview as Form
  add object frame as myFrame && vea arriba

Junto con los botones de comandos:

  add object cmdPrev as myButton ;
    with Top=12, Caption = "Previous"
  add object cmdNext as myButton ;
    with Top=44, Caption = "Next"
  add object cmdZoomIn as myButton ;
    with Top=96, Caption = "Zoom In"
  add object cmdZoomOut as myButton ;
    with Top=128, Caption = "Zoom Out"
  add object cmdReset as myButton ;
    with Top=176, Caption = "Whole Page"
  add object cmdClose as myButton ;
    with Top=220, Caption = "Close"

La clase derivada myButton que he utilizado aquí es precisamente una plantilla para .FontName, .FontStyle y la posición .Left. En breve, vamos a implementar algunos .Click. Sea paciente.

Viendo cómo necesitamos interactuar con el motor de informes, vamos a darle al formulario un par de propiedades de usuarios: Un marcador de posición para una referencia a un objeto ReportListener, y una propiedad numérica para el número de página actual:

Listener = .null.
PageNo = 1

La llave para crear un formulario de presentación preliminar en VFP 9.0 es utilizar el método OutPutPage de ReportListener, pasándole tres parámetros:

• El número de página a generar
• El dispositivo u objeto para generar la presentación preliminar
• Un número que indica el tipo de dispositivo u objeto que se está generando.

Ya que estamos generando un objeto Visual FoxPro - THIS.Frame.Canvas - el parámetro - tipo de dispositivo es 2. Vamos a tener el número de página en THIS.PageNo, y la referencia al ReportListener es THIS.Listener, así que la sintaxis completa será:

THIS.Listener.OutputPage(THIS.PageNo, THIS.Frame.Canvas, 2)

Vamos a colocar todo el código - con las condiciones de verificación de límites - en un método de usuario del formulario, OutPage():

procedure Outputpage()
  with THIS
    if not isnull(.Listener) and .Listener.PageTotal > 0
      .Listener.OutputPage(.PageNo, .Frame.Canvas, 2)
      .Caption = ;
        justfname(.Listener.commandClauses.file) ;
        + " - page " + trans(.PageNo)
    endif
  endwith
endproc

Como puede ver, vamos a utilizar la propiedad Caption del formulario para mostrar el nombre de archivo y el número de página actual, solo por dejar las cosas más sencillas. Para asegurar que la página de informe se generará cuando se dibuje el formulario, añadimos una llamada a nuestro método de usuario en el evento Paint del formulario:

procedure Paint()
  THIS.OutputPage()
endproc

Hacer que estos botones reaccionen al Clic

¿Recuerda aquellos botones de comando que agregamos al formulario? Tenemos un par para la navegación alrededor del informe. Es importante tener en cuenta las condiciones de límites entre datos. El máximo número de páginas que se puede generar está determinado por: ReportListener.PageTotal:

procedure cmdPrev.Click
  with THISFORM
    .PageNo = max(1,.PageNo-1)
    .OutputPage()
  endwith
endproc

procedure cmdNext.Click
  with THISFORM
    .PageNo = min(.Listener.PageTotal,.PageNo+1)
    .OutputPage()
  endwith
endproc

Tenemos además un par de comandos para ajustar el tamaño de la presentación preliminar. Es fácil: solamente cambiar el tamaño del Shape y llamar a OutPutPage para re-pintar:

#define ZOOM_SCALE 1.3

procedure cmdZoomIn.Click
  with THISFORM.Frame.Canvas
    .Width = int(.Width * ZOOM_SCALE)
    .Height = int(.Height * ZOOM_SCALE)
  endwith
  THISFORM.OutputPage()
endproc

procedure cmdZoomOut.Click
  with THISFORM.Frame.Canvas
    .Width = max(17,int(.Width / ZOOM_SCALE))
    .Height = max(22,int(.Height / ZOOM_SCALE))
  endwith
  THISFORM.OutputPage()
endproc

Como puede ver, estamos utilizando algunas condiciones de límite en el tamaño más pequeño de la Forma, explícitamente escrito en el código 8.5 x 11, sobre esto podíamos pensar en algo más.

En caso de que desee perder el acercamiento y el movimiento, es conveniente un botón para re-inicializar el tamaño y la posición de la forma (shape).

procedure cmdReset.Click
  with THISFORM.Frame.Canvas
    .Top = 20
    .Left = 20
    .Width = 255
    .Height = 330
  endwith
endproc

El botón Cerrar no es realmente necesario - el formulario tiene su cuadro Cerrar en el título que funciona perfectamente. Pero, permítanme agregarlo de todas formas:

procedure cmdClose.Click
  THISFORM.Release()
endproc

Probamos hasta ahora

Bien, ¡Lo hemos hecho!, ahora vamos a probarlo. Lo primero que necesitamos es crear un ReportListener

rl = newobject("ReportListener")
rl.ListenerType = 3

Vea que estamos utilizando un ReportListener igual a 3. Un ListenerType igual a 1 provocaría que se invocara el contenedor preliminar predeterminado que no es lo deseado en este caso: Deseamos solamente generar la salida y guardarla en memoria temporal (caché) para nuestro propio empleo.

Ahora, necesitamos el motor de informes para que envíe un informe a nuestro listener:

report form ? object m.rl

Escoja cualquier informe que desee. (Yo escogí _SAMPLES+"\Solution\Reports\wrapping.frx" porque es bonito.) Ahora debemos instanciar nuestra Interfaz de usuario y asignarle una referencia a nuestra instancia ReportListener, y pedirle que lo muestre:

x = newobject("myPreview")
x.Listener = m.rl
x.Show(1)

Esperemos que en este punto tengamos algo como lo que tenemos en la figura mostrada antes.

• Intente navegar por el informe.
• Intente hacer Zoom.
• Trate de arrastrar la página.

Un pequeño problema

Bien, confieso que he omitido ante un aspecto importante. (Los escritores de artículos hacen así todo el tiempo, porque piensan que es un buen recurso didáctico.)

Como probablemente ha notado, el método ReportListener.OutputPage() utiliza la posición y las dimensiones del objeto Shape para generar la página del informe sobre la superficie del formulario. En realidad no dibuja el objeto como tal.

Como resultado, la página sobre-escribe los otros controles en el formulario, produciendo un efecto visual desconcertante. Vea la imagen.

Existe una solución: tenemos que utilizar parámetros adicionales a OutPutPage() para especificar los límites dentro de los que se va a dibujar la imagen.

Especificar un área fija para OutputPage()

La documentación para el método OutPutPage (ver ayuda VFP) indica que los parámetros adicionales no se aplican para un tipo de dispositivo igual a 2 (2 = objeto FoxPro) Esto no es estrictamente correcto. En realidad, los parámetros 4to, 5to, 6to y 7mo se ignoran; pero los parámetros nClipLeft, nClipTop, nClipWidth, y nClipHeight se respetan por el método ReportListener.OutputPage() para objetos FoxPro

Estos cuatro parámetros finales definen una "ventana" - en pixels - en el área del formulario a través de la cual la salida regenerada va a aparecer. Cualquier cosa que quede fuera de esta área no se mostrará en el formulario.

Afortunadamente para nosotros, tenemos la forma conveniente para determinar la ubicación y dimensiones de área fija: el objeto frame como tal nos lo dirá.

Substituya la línea de código resaltada en negrita en el método OutPutPage del formulario para que sean especificados los parámetros adicionales:

* .Listener.OutputPage( .PageNo, .Frame.Canvas, 2 )
.Listener.OutputPage( ;
.PageNo, .Frame.Canvas, 2, ;
  0, 0 , 0 , 0 , ;
  .Frame.Left +2, ;
  .Frame.Top +2, ;
  .Frame.Width -4, ;
  .Frame.Height -4 )

Ahora el formulario preliminar debe trabajar como esperamos (vea la siguiente figura)

Ejercicios para estudiantes:

Considero que he mostrado propiedades excitantes de las posibilidades existentes. Pero no hemos hecho todo: existen algunas cosas adicionales que va a necesitar hacer antes de emplear este código en una aplicación en producción.

Debe:

• Ajustar el código en el evento MouseDown del objeto Shape para evitar que el ratón se arrastre fuera de los límites del borde del marco.
• Ajustar la proporción del objeto Shape para que se corresponda con las dimensiones del informe, utilizando los métodos .GetPageWidth() y .GetPageHeight() del ReportListener.
• Permitir al formulario mostrar una escala apropiada para el nivel DPI de la pantalla, incluyendo una opción "Zoom al 100%"
• Ajustar el código de alejamiento-acercamiento de tal forma que el centro del área visible del objeto Forma permanezca centrado en lugar de moverse basado en la posición de la esquina superior izquierda como ocurre actualmente
• Posiblemente establecer el nivel máximo y mínimo para el zoom.
  

Puede además:

• Hacer que el formulario sea redimensionable

Y quizás, lo que puede ser aun más útil, podría agregar además código adicional a la clase, para que conecte en el sistema de informes de Visual FoxPro, proporcionando un Contenedor preliminar (Preview container) alternativo cuando SET REPORTBEHAVIOR 90 está activado.

... oh, está bien. He aquí cómo se hace:

Empaquetado como Contenedor preliminar

Necesitará agregar estos métodos en la clase myPreview

*-------------------------------------------
* Métodos requeridos para que opere como 
* un contenedor preliminar :
*-------------------------------------------
procedure Release()
  if not isnull(THIS.Listener)
    THIS.Listener.OnPreviewClose(.F.)
    THIS.Listener = .null.
  endif
  THIS.Hide()
endproc

procedure Destroy()
  THIS.Listener = null
  dodefault()
endproc

procedure QueryUnload()
  nodefault
  THIS.Release()
endproc

procedure SetReport( oRef )
  if not isnull(oRef) and vartype(oRef) = "O"
    THIS.Listener = m.oRef
  else
    THIS.Listener = .null.
    THIS.Hide()
  endif
endproc

Deseará además colocar el código al inicio del archivo, de tal forma que solamente apunte a _REPORTPREVIEW directamente al programa.

*------------------------------------------
* Utilizado como contenedor preliminar:
* _REPORTPREVIEW = "<this program>"
*
* Comprobación fuera del sistema de informes:
* DO <este programa>
*------------------------------------------
lparameters oRef
if pcount()=0
  rl = newobject("ReportListener")
  rl.ListenerType = 3
  report form ? object m.rl
  x = newobject("myPreview")
  x.Listener = m.rl
  x.Show(1)
  return
else
  oRef = newobject("myPreview")
endif
return

¡Que lo disfrute!

He aquí el código fuente para este artículo: http://www.spacefold.com/colin/archive/articles/reportpreview/tech_src.txt

Copyright (c) 2005 Colin Nicholls