Xojo 2022r2: Nuevos Tipos de Anotaciones en PDFDocument

La característica de anotaciones en PDFDocument se ha ampliado notablemente en esta release de Xojo. Sigue leyendo y te mostraré cuáles son y por qué querrías utilizarlas en la composición de tus propios documentos PDF desde Xojo.

Hasta ahora PDFDocument ya soportaba el más común de los tipos de anotaciones en un documento PDF. Ya sabes, esas pequeñas “cajas amarillas” mostradas como anotaciones sobre las propias páginas del documento PDF y que mostraban su contenido de texto cuando se hacía clic sobre ellas.

La buena noticia es que ¡a partir de ahora tendrás a tu alcance un rango de opciones mucho más amplio! Y si bien muchas de ellas no tendrán el aspecto de anotaciones “reales”, o bien pueda darte a impresión de que es algo que podrías hacer utilizando para ello los métodos de dibujado de la propia clase Graphics, lo cierto es que son anotaciones y por tanto se comportarán como tales. Esto significa que también podrán mostrar el texto o comentario asociado con la anotación, al tiempo de que los usuarios podrán aceptar o declinar la anotación y también añadir nuevas respuestas sobre la misma.

Pero antes de que entremos en los detalles de las novedades, permíteme aclara algo: el estándar PDF indica el modo en el que las características han de ser implementadas para que un PDF sea, bueno, un PDF; y luego está en manos de los desarrolladores de las aplicaciones para la visualización o edición de archivos PDF el decidir qué característica del estándar quieren implementar y cómo hacerlo.

Por tanto, y tal y como ocurre con muchas otras cosas relacionadas con los archivos PDF, no esperes que muchos editores o aplicaciones de PDF soporten o se adhieran a la característica de anotaciones más allá de las que son del tipo más básico (es decir, las que ya venían estando soportadas en anteriores versiones de Xojo).

Por supuesto, Adobe es el creador original de las especificaciones PDF mucho antes de que se convirtiese en un estándar, y su aplicación gratuita para la visualización y edición de archivos PDF, Acrobat Reader, soporta correctamente todo lo que ofrece PDFDocument.

Adjuntar Archivos al PDF

Podrás embeber cualquier archivo (exceptuando aquellos basados en una estructura de Bundle) en el documento PDF propiamente dicho; como por ejemplo un archivo de Excel, una imagen en alta resolución, etc. Luego, el usuario podrá abrir el archivo adjunto haciendo clic sobre el área de la anotación… siempre y cuando su equipo tenga instalada una aplicación compatible con el tipo de archivo en cuestión. Por supuesto, y dado que no deja de ser una anotación, el usuario también podrá editar la anotación o añadir nuevas respuestas.

Este ejemplo muestra cómo crear una anotación de este tipo:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
Const kContentText As String = "Attached File Annotation: double click on me!"

g.FontSize = 20
g.DrawText(kContentText, 40, 60)

If exampleFile <> Nil Then
  
  // Creating a new EmbeddedSound.
  d.AddEmbeddedFile(exampleFile, 40, 60, g.TextWidth(kContentText), 20)
  
  // Saving the created PDF document to the selected path.
  Var f As FolderItem = FolderItem.ShowSaveFileDialog("","PDFAttachedFile.pdf")
  
  If f <> Nil Then
    
    d.Save(f)
    
  End If
End If

Aquí exampleFile es una propiedad de tipo FolderItem que se ha añadido al proyecto y que apunta al archivo que se incluirá como parte del PDF.

Y así es cómo se verá en el archivo PDF resultante:

Anotaciones de Llamada

Las anotaciones Callout son perfectas para dirigir la atención hacia otro elemento de la página del PDF. Son muy personalizables dado que puedes indicar el tipo de línea a utilizar, la terminación de la línea, su color y, por supuesto, el texto a mostrar en la anotación propiamente dicha.

Este es un ejemplo sobre cómo añadir una anotación Callout con PDFDocument:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
Const kContentText As String = "Callout Annotation in PDF"

g.FontSize = 40
g.Bold = True
g.DrawText(kContentText, 40, 60)

g.Bold = False
g.FontSize = 12
g.DrawText(kSampleText, 40, 100, 200)

Var originY As Double = (g.TextHeight(kSampleText, 200) / 2)

Var tCallout As New PDFCallout("Callout Example", New Point(250, originY), New Point(300, originY + 50), _
 New Point(350, originY + 50), 100, 50)

tCallout.BorderStyle = PDFAnnotation.BorderStyles.Dashed
tCallout.DashPattern = Array(2.0, 2.0)
tCallout.DrawingColor = Color.Orange
tCallout.LineEndingStyle = PDFAnnotation.LineEndingStyles.OpenArrow
tCallout.Value = "Some sample text in the annotation"
tCallout.FontSize = 9.5

d.AddCallout(tCallout)

// Saving the created PDF document to the selected path.
Var f As FolderItem = FolderItem.ShowSaveFileDialog("","PDFCalloutExample.pdf")

If f <> Nil Then
  
  d.Save(f)
  
End If

Donde kSampleText es una Constante añadida al proyecto que contiene un texto de muestra utilizado en la página del documento PDF.

Y así es como se verá la anotación Callout cuando se abre el PDF resultante en Acrobat Reader:

Anotaciones de Línea

Una anotación de línea muestra una línea recta en la página con una etiqueta de texto en su interior o sobre la línea propiamente dicha.

Opcionalmente, también es posible añadir líneas de avance de forma perpendicular sobre ambos extremos de la línea principal (ya sea utilizando valores positivos o negativos), además de ajustar otra serie de valores como por ejemplo el tipo de línea (sólida, punteada, etc), el tipo de terminación utilizado en ambos extremos de la línea principal (como una flecha abierta/cerrada, círculo, diamante, cuadrado…), el color de dibujado, el ancho de la línea y también el tamaño de la fuente.

Todo ello hace que este tipo de anotaciones resulten útiles, entre otras cosas, para indicar el tamaño de otros elementos añadidos a la página del documento PDF.

Así es como se ven una anotación de tipo Línea cuando se abre el documento PDF resultante en Acrobat Reader (en este caso utilizando líneas de avance):

Anotaciones de Vídeo

Así es, puedes incluir archivos de vídeo .mp4 en un PDF creado con PDFDocument y estos se reproducirán desde el propio PDF. Por supuesto, esto aumentará el tamaño del archivo PDF generado dado que también incorporará en él los datos correspondientes al archivo de vídeo propiamente dicho. Así que es importante mantener como buena práctica la máxima optimización que se pueda hacer del archivo de vídeo en cuestión, incluyendo el ajuste de su resolución al del tamaño al que se deseen reproducir.

Por supuesto también puedes añadir este tipo de contenido utilizando un tipo de anotación de archivo adjunto. En ambos casos se incluirán los datos del archivo de vídeo en sí. La principal diferencia es que en este caso el archivo de vídeo se abrirá y reproducirá utilizando una aplicación externa que, siendo compatible, esté instalada en tu equipo. Adicionalmente, ello también te permitirá la inclusión de otros formatos de archivo de vídeo más allá de los .mp4.

El modo de añadir este tipo de anotaciones a una instancia de PDFDocument es realmente sencilla. Por ejemplo:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
Const kContentText As String = "Embedded Video Annotation"

g.FontSize = 30
g.DrawText(kContentText, 40, 60)

If exampleVideo <> Nil Then
  
  // Creating a new EmbeddedSound.
  d.AddEmbeddedMovie(exampleVideo, 40, 100, 478, 360)
  
  // Saving the created PDF document to the selected path.
  Var f As FolderItem = FolderItem.ShowSaveFileDialog("","PDFEmbeddedVideo.pdf")
  
  If f <> Nil Then
    
    d.Save(f)
    
  End If
End If

Donde exampleVideo es una propiedad de tipo FolderItem añadida al proyecto y que apunta al archivo de vídeo que se incluirá en el PDF.

Y este es el aspecto que tendrá la anotación de vídeo cuando se abra el documento PDF resultante en Acrobat Reader:

Anotaciones de Sonido

Junto con las anotaciones de vídeo también es posible añadir archivos de audio que se reproduzcan desde el PDF. En este caso los archivos de audio han de ser en formato AIFF con 2 canales de audio (estéreo), una resolución de 16 bits, y utilizando una frecuencia de muestreo de 44,1 kHz.

Tal y como ocurre con las anotaciones de vídeo, también puedes optar por incorporar este tipo de contenido como una anotación de archivo adjunto, de modo que el archivo se abrirá con una aplicación que, siendo compatible, se encuentre instalada en el mismo equipo. También abre el rango en cuanto a los formatos de archivo de audio que se pueden incluir en el documento PDF.

La forma de añadir anotaciones de audio usando PDFDocument es realmente simple, tal y como puedes ver aquí:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
g.FontSize = 30

Const kContentText As String = "Embedded Sound Annotation"

Var x, y, width, height As Double

x = g.Width/2 - width/2
y = 60

width = g.TextWidth(kContentText)
height = g.TextHeight

g.DrawText(kContentText, x, y)

If exampleSound <> Nil Then
  
  // Creating a new EmbeddedSound.
  d.AddEmbeddedSound(exampleSound,x,y,width,height)
  
  // Saving the created PDF document to the selected path.
  Var f As FolderItem = FolderItem.ShowSaveFileDialog("","PDFEmbeddedSound.pdf")
  
  If f <> Nil Then
    
    d.Save(f)
    
  End If
End If

Donde exampleSound es una propiedad de tipo FolderItem añadida al proyecto y que apunta al archivo de audio que se incluirá en el PDF.

Y este es el aspecto que tiene una anotación de tipo Sonido cuando se abre el documento PDF resultante en Acrobat Reader:

Anotaciones de Marcado

Una anotación de marcado tiene como propósito marcar (o hacer indicaciones) sobre el contenido de texto disponible bajo el área definida, como por ejemplo “resaltado” (Highlight), “corrección” (Squiggly), subrayado (Underline) o tachado (Strikeout). Adicionalmente, también se puede indicar el color para la anotación.

Por ejemplo, el siguiente fragmento de código añade dos anotaciones de marcado a la página del documento PDF utilizando los tipos de marcado Highlight y Squiggly:

Var d As New PDFDocument
Var g As Graphics = d.Graphics
Const kContentText As String = "Markup Annotation in PDF"

g.FontSize = 40
g.Bold = True
g.DrawText(kContentText, 40, 60)

// Adding a Markup annotation with the Highlight type (Default)
d.AddMarkup(40,40,g.TextWidth(kContentText),g.FontSize,"Let's focus on this Section")

g.Bold = False
g.FontSize = 12
g.DrawText(kSampleText, 40, 100, g.Width-80)

// Adding a Markup annotation with the Squiggly type
d.AddMarkup(40,195,210,g.FontSize,"Some text to correct!",Color.Red,PDFAnnotation.MarkupTypes.Squiggly)

// Saving the created PDF document to the selected path.
Var f As FolderItem = FolderItem.ShowSaveFileDialog("","PDFMarkupExample.pdf")

If f <> Nil Then
  
  d.Save(f)
  
End If

Y así es como se ve cuando el documento resultante se abre en Adobe Acrobat Reader:

Bonus

Permíteme que finalice apuntando otra mejora menor relacionada con las anotaciones en PDFDocument: a partir de Xojo 2022r2, todas las anotaciones incluyen metadatos sobre la fecha y hora de su creación/modificación; de modo que será presentada al usuario cuando se seleccione cualquiera de estos elementos en la aplicación visor de PDF.