Tutorial: ¡Llega la Transparencia a PDFDocument!

Entre las múltiples mejoras añadidas a PDFDocument en Xojo 2021r3 se encuentra el soporte de Graphics.Transparency y también el soporte del valor alfa en el color asignado a la propiedad Graphics.DrawingColor. ¡Continúa leyendo para conocer todos los detalles!

A partir de 2021r3 podrás utilizar de forma efectiva tanto la Transparencia como el componente Alfa de las instancias de Color en cada uno de los ítems que añadas a tus documentos PDF: texto, formas e imágenes.

Es más, también se ha mejorado el soporte de las imágenes (objetos Picture) de modo que PDFDocument podrá utilizar el canal alfa de la imagen (en el caso de que disponga de uno), en vez de generar dicho canal alfa de las imágenes como un fondo de color blanco, tal y como venía sucediendo hasta ahora. ¡Esto significa una mayor flexibilidad en el diseño de las páginas PDF!

Y dado que se ha añadido a PDF el soporte de transparencia utilizando la misma clase Graphics que ya conocías, el modo de aplicarla es realmente simple. Por ejemplo, utilicemos el siguiente fragmento de código en el Manejador de Evento Open de una app Desktop (en este caso, la imagen GrassBG utilizada en el código se ha añadido al proyecto):

// Creamos una nueva instancia de PDFDocument
Var d As New PDFDocument

// Obtenemos el contexto gráfico del documento PDF
Var g As Graphics = d.Graphics

// ¿Cuántos rectángulos podemos dibujar en el ancho de la página?
Var iter As Integer = g.Width/10

Var x As Integer

// Calculemos la coordenada Y para el centro de la imagen
// GrassBG sobre la altura disponible en la página PDF
Var imageY As Integer = g.Height/2 - grassBG.Height/2

// Y calculemos también la coordenada Y para los rectángulos
Var y As Integer = (imagey + grassbg.Height) - 40

// Valor de transparencia = 0
Var tLevel As Integer

// Valor usado para incrementar la transparencia en
// el dibujado de cada rectángulo
Var offset As Integer = 10

Var txt As String = "Transparency"

g.FontSize = 90
g.Bold = True

// Coordenadas X e Y para centrar el texto "Transparency"
// sobre la altura y ancho de la página
Var txtX As Integer =  g.Width/2 - g.TextWidth(txt) / 2
Var txtY As Integer = ImageY + GrassBG.Height - g.FontAscent

// Dibujamos el texto "Transparency" -> ¡Capa de fondo!
g.DrawText txt, txtX, txty

// Dibujamos la imagen GrassBG sobre el texto
// es decir, es la segunda capa y preserva
// el canal alfa del PNG.
g.DrawPicture grassBG,0,ImageY

// Definimos el color aleatorio inicial para
// dibujar el primer rectángulo.
Var rd As New Random
g.DrawingColor = Color.RGB(rd.InRange(0,255), rd.InRange(0,255), rd.InRange(0,255))

Var tmpLevel, y1 As Integer

// Dibujamos la tira horizontal de rectángulos
// esta es la tercera capa
For n As Integer = 0 To iter

// Definimos el valor de transparencia
g.Transparency = tLevel

// Dibujamos el rectángulo
g.FillRectangle x,y,20,40

// Asignamos el valor de transparencia actual a
// la variable tmpLevel para dibujar las gotas de color

tmpLevel = tLevel

// Coordenada Y para la gota de color
y1 = y + 40

// Dibujamoss la gotas de color para el rectángulo actual
For i As Integer = 0 To 10
tmpLevel = tmpLevel - 10
If tmpLevel >= 0 Then
g.Transparency = tmpLevel
g.FillRectangle x,y1,2, 2
y1 = y1 + 2
End If
Next i

// Incrementamos la coordenada X para dibujar
// el siguiente rectángulo
x = x + 20

//…e incrementamos el valor de transparencia en diez
tLevel = tLevel + offset

// si alcanzamos el máximo valor permitido para
// la transparencia, invertimos el signo del
// offset y definimos un nuevo color de dibujo
If tLevel = 100 Or tLevel = 0 Then
offset = -offset
g.DrawingColor = Color.RGB(rd.InRange(0,255), rd.InRange(0,255), rd.InRange(0,255))
End If

Next n

// Dibujamos la cuarta capa sobre la tira de rectángulos
// con el texto "Comes to PDFDocument".
txt = "COMES TO PDFDOCUMENT"
g.FontSize = 30

// Observa que aquí estamos definiendo el valor alfa para
// el color, en vez de emplear la propiedad Transparency
g.DrawingColor = Color.RGB(255,255,255,127)

g.CharacterSpacing = 20
txtX = g.Width/2 - g.TextWidth(txt) /2
txty = y + 20 + g.FontAscent/2
g.DrawText txt,txtx, txty

// Obtenemos una referencia FolderItem apuntando
// al archivo "Transparency.PDF" en el escritorio.
Var f As FolderItem = SpecialFolder.Desktop.Child("Transparency.pdf")

// Guardamos el archivo PDFDocument
d.Save(f)
f.Open

Una vez que se ejecute el código, se obtendrá el documento PDF cuyo contenido se corresponde con la imagen mostrada en la parte superior de este artículo.

Como puedes ver, este es un documento de cuatro capas con el texto “Transparency” dibujado en la primera capa (la situada más al fondo), seguida de la imagen PNG cuyo canal alfa nos permite ver las partes no cubiertas del texto detrás de la imagen.

A continuación, la imagen está seguida por una tira de rectángulos horizontales en una nueva capa sobre ella. Dichos rectángulos están dibujados con una cantidad variable de transparencia.

Por último, en la capa situada más al frente de la página estamos dibujando el texto “Comes to PDFDocument”; haciendo uso, en este caso, del valor alfa asociado al color blanco definido como DrawingColor.

Como puedes ver, las dos capas superiores combinan su color / nivel de transparencia contra las situadas tras ellas y, por supuesto, el texto dibujado en el documento PDF continúa siendo vectorial y editable.

Transparencia vs. valor Alfa del Color

Como seguramente ya sepas, el valor de la propiedad Transparency comprende desde 0.0 (opaco) a 100.0 (totalmente transparente), mientras que el rango del componente alfa de una instancia de color comprende desde 0.0 (opaco) a 255.0 (totalmente transparente).

¿Qué ocurre cuando usamos ambos tipos de valores en el dibujado de nuestros documentos PDF? Es decir, supongamos que hemos ajustado el valor de Transparency a 40, mientras que el valor alfa del color de dibujado está definido a 127. En este caso, el valor alfa del color de dibujo es más elevado, de modo que será este el valor de transparencia empleado en el dibujado; dado que todos los elementos, exceptuando las imágenes, se ven afectadas por el color de dibujado.

Por el contrario, si el valor de transparencia es superior al valor alfa del color de dibujado en curso, entonces será este el nivel de transparencia aplicado a cualquiera de los elementos añadidos al documento PDF, incluidas también las imágenes.