Tutorial: PDFDocument, crear formularios PDF

Una de las nuevas características añadidas a PDFDocument en la release Xojo 2021r3 es la capacidad de crear Formularios (también conocidos como AcroForms) en tus documentos creados PDF.

Esto significa que es posible añadir los siguientes controles de Formulario a cualquiera de las páginas del documento PDF:

• PDFButton
• PDFTextField
• PDFTextArea
• PDFCheckBox
• PDFRadioButton
• PDFPopupMenu
• PDFComboBox
• PDFListBox

Tal y como está definido por el estándar PDF, cada documento PDF sólo puede contener un Formulario. Por otra parte, cuando se añade cualquiera de estos controles al documento PDF estos no proporcionarán ninguna información sobre su aspecto más allá del área interactiva sobre la cual puede actuar el usuario.

Esto significa que tendrás que dibujar cualquiera de los elementos de diseño a través de la clase Graphics, como por ejemplo los rectángulos que delimitan un Botón, TextField, TextArea, y también para dibujar las etiquetas de texto asociadas con cada uno de los controles CheckBox o RadioButton que se añadan a las páginas del documento.

Por ejemplo, este es el aspecto que tendrá un TextField añadido a la página del PDF:

Como puedes ver, en este caso sólo se muestra el área interactiva del control así como el texto asignado como valor por defecto para la instancia PDFTextField.

Y así es como se verá una vez que se haya dibujado un rectángulo que rodea a dicho control, utilizando para ello el método Graphics.DrawRectangle.

La forma de añadir cualquiera de estos controles de Formulario a una instancia PDFDocument es bastante sencilla; sólo tenemos que llamar al método AddControl en la instancia PDFDocument pasando como parámetro una instancia creada a partir de cualquiera de los controles soportados.

Sobre el comportamiento de estos controles, merece la pena mencionar los siguientes casos.

PDFButton

Puedes crear y añadir al Formulario nuevas instancias basadas en esta clase para configurar las siguientes Acciones:

• PDFButton.Actions.ResetAction. Reseteará los controles añadidos al formulario a sus valores por defecto (si se han establecido).
• PDFButton.Actions.SendForm. Enviará los valores introducidos/seleccionados por el usuario en los controles del Formulario como una serie de pares clave/valor, donde la Clave es el nombre del control y el valor enviado es el introducido/seleccionado por el usuario. Estos datos se enviarán al URL definido en la propiedad URL de la instancia PDFButton.Por ejemplo, algunos URL válidos podrían ser “http://127.0.0.1:8080”, “https://myDomain.com/WebService” o “mailto://someEmailAddress@here.com”. Si el URL se corresponde con el protocolo “mailto:”, entonces el receptor recibirá estos valores como un archivo de texto adjunto al mensaje.
• PDFButton.Actions.SendPDFFile. Cuando se utiliza esta acción el URL recibirá el archivo PDF propiamente dicho, tanto si se utiliza el protocolo “mailto:” como “http(s)”.

Es importante observar que no todas las aplicaciones de visualización de PDFs soportan este tipo de acciones. Por ejemplo, la app Vista Previa de macOS no los soporta. Es recomendable utilizar el gratuito Adobe Acrobat Reader DC, y que está disponible para todas las plataformas soportadas por Xojo.

PDFRadioButton

Puedes añadir al Formulario PDF instancias de PDFRadioButton como botones independientes o bien como un grupo de botones. Cuando se añaden como botones individuales sólo es posible seleccionarlo/deseleccionarlo, mientras que cuando se utilizan como un grupo de botones, entonces la activación de cualquiera de ellos supondrá la desactivación del resto de botones del mismo grupo. Es decir, el mismo comportamiento al que estás habituado cuando se utilizan este tipo de controles en un proyecto Xojo.

El modo de configurar una instancia RadioButton como miembro de un mismo grupo se basa en emplear el mismo nombre. Por ejemplo, siguiente código:

Var rBtn1GroupA As New PDFRadioButton(1, 200, 450, 15,15,"GroupA","OptionA")
Var rBtn2GroupA As New PDFRadioButton(1, 200, 470, 15, 15,"GroupA", "OptionB")
rBtn2GroupA.Value = True
d.AddControl(rBtn1GroupA)
d.AddControl(rBtn2GroupA)

Creará dos instancias de PDFRadioButton asignadas a las variables rBtn1GroupA y rBtn2Group2 que comparten el mismo nombre “GroupA”, pero en las que se han asignado diferentes valores: “OptionA” y “OptionB”. Igualmente, se configura la instancia rBtn2GroupA como el botón de radio seleccionado por omisión:

rBtn2GroupA.Value = True

Adicionalmente, dado que sólo es posible crear un Formulario por documento PDF, no importa que las instancias de RadioButton pertenecientes a un mismo grupo se encuentren repartidas por cualquiera de las páginas del documento PDF; estos continuarán comportándose como miembros del mismo grupo.

PDFPopupMenu y PDFComboBox

Estos controles se comportan de un modo muy similar a lo que podrías esperar cuando los usas en cualquier proyecto de Xojo. Es decir, puedes asignar la serie de valores a mostrar por estos controles de menú, así como seleccionar cualquiera de ellos como el valor seleccionado por omisión. La principal diferencia es que el PDFComboBox permitirá que el usuario introduzca cualquier otro valor aparte de los incluidos en el menu, utilizando para ello el campo de texto que forma parte del propio control.

Por ejemplo, el siguiente fragmento de código creará una instancia PDFPopupMenu:

Var cPopup As New PDFPopupMenu(1,210,540,100,15,"List","Option A", "Option B", "Option C", "Option D")
d.AddControl(cPopup)

Donde “List” es el nombre del control propiamente dicho, y “Option A”, “Option B”, “Option C” y “Option D” son los valores que se presentarán al usuario como las opciones del menú.

Por supuesto, también puedes proporcionar dichos valores en el Constructor del PDFPopupMenu como un Array de Strings si así lo deseas:

Var r() As String = Array("Option A", "Option B", "Option C", "Option D")
Var cPopup As New PDFPopupMenu(1,210,540,100,15,"List",r)
d.AddControl(cPopup)

La creación de una instancia PDFComboBox es muy similar. Por ejemplo:

Var cCombo As New PDFComboBox(1,100,540,100,15,"ListC","Option A", "Option B", "Option C", "Option D")
cCombo.SelectedRowValue = "Option C"
d.AddControl(cCombo)

En este caso, “Option C” será el valor seleccionado por defecto.

PDFListBox

No existe mucha diferencia sobre el modo en el que se crean nuevas instancias de un PDFListBox en comparación a cómo se hace con un PDFPopupMenu o un PDFComboBox:

Var options() As String = Array("Option A", "Option B", "Option C", "Option D")
Var cListBox As New PDFListBox(1,320,540,100,90,"ListB", options)
cListBox.RowSelectionType = PDFListBox.RowSelectionTypes.Multiple
cListBox.SelectedRowValue = "Option D"
d.AddControl(cListBox)

Como puedes ver, en este caso el valor seleccionado por defecto será “Option D”. La principal diferencia es que PDFListBox permite definir la propiedad RowSelectionType entre “Multiple” y “Single”, como es también el caso cuando se utiliza un DesktopListBox en un proyecto de Xojo. Por tanto, en este caso:

cListBox.RowSelectionType = PDFListBox.RowSelectionTypes.Multiple

Se indicará a la instancia cListBox que se permita al usuario la selección de múltiples entradas en el control.

Un aspecto a considerar en este sentido es que cuando se envía el PDF al URL indicado, utilizando el tipo de Acción SendForm, entonces las múltiples opciones seleccionadas por el usuario se representarán como una serie de pares clave/valor donde la clave se corresponderá con el mismo nombre del control. Por ejemplo, pongamos que el usuario ha seleccionado los valores “Option B”, “Option C” y “Option D”. Entonces, el servicio web que esté disponible en el URL de destino recibirá lo siguiente:

ListB=Option+B&ListB=Option+C&ListB=Option+D

Observa cómo en todos estos casos “ListB” es el nombre que se ha asignado a la instancia PDFListBox.

PDFTextField y PDFTextArea

Hay un par de propiedades interesantes que puedes configurar en las instancias creadas para estas clases:

• ReadOnly: Define esta propiedad a True para que el usuario no pueda introducir texto en el control.
• MaximumCharactersAllowed: Configura esta propiedad al máximo número de caracteres que pueda introducir el usuario en el control.

Este fragmento de código creará una instancia de PDFTextField:

Var tf As New PDFTextField(1, 100, 50, 200, 22, "TextField", "Some sample text")
d.AddControl(tf)

Donde “TextField” es el nombre de la instancia del control, y “Some sample Text” es el valor mostrado por defecto.

Y así es como podemos crear una instancia de PDFTextArea en la que se permita la introducción de un máximo de 100 caracteres:

Var ta As New PDFTextArea(1, 100, 100, 200, 300, "TextArea", "Hi There!")
ta.MaximumCharactersAllowed = 100
d.AddControl(ta)

Donde “TextArea” es el nombre de la instancia del control y “Hi There!” es el valor por defecto mostrado.

Conclusión

¡Hemos visto lo sencillo que resulta añadir Formularios a los documentos PDF creados con Xojo!

Si quieres aprender más sobre su funcionamiento y también probar los diferentes modos de Acción, entonces puedes ejecutar el proyecto Xojo PDFFormTest-Desktop que encontrarás en la carpeta Example Projects > PDF.