PDFDocument: Nuevas mejoras en PDFGraphics

Xojo 2022r1 completa prácticamente el soporte de todos los métodos y propiedades de la clase Graphics que tienen sentido (o son aplicables) en la clase PDFGraphics. Ahora también podrás utilizar en tus documentos PDF la funcionalidad proporcionada por la propiedad Brush y los métodos ClipToPath, Clip y DrawObject.

Rellenos con Brush

La propiedad Brush permite asignar al contexto gráfico del documento PDF una brocha que se empleará a la hora de aplicar color o relleno a cualquiera de las formas (óvalos, líneas, rectángulos, etc), así como a dibujos vectoriales (paths) o texto, incorporados al PDF a partir de su asignación. Si dicha propiedad Brush está definida a Nil entonces se aplicará el color normal asignado a través de la propiedad Graphics.DrawingColor.

Lo que hace especialmente interesante a la propiedad Brush es que se le puede asignar cualquier instancia creada a partir de las clases PictureBrush, LinearGradientBrush o RadialGradientBrush.

PictureBrush. De entre los diferentes modos soportados por la clase sólo está disponible Tile, de modo que la imagen asignada se repetirá hasta completar la superficie de relleno.
LinearGradientBrush. PDFGraphics ofrece el mismo comportamiento que el ofrecido por esta clase cuando se utiliza en la clase Graphics.
RadialGradientBrush. PDFGraphics ofrece el mismo comportamiento que el encontrado cuando se utiliza en la clase Graphics.

Esta imagen muestra un PDF generado con PictureBrush aplicado como fondo de relleno del texto, RadialGradientBrush en el rectángulo inferior y también como contorno del texto “The Golden”, así como LinearGradientBrush aplicado sobre el rectángulo superior. Adicionalmente, se ha aplicado transparencia en el dibujado de los textos, de modo que el relleno también proporciona el mismo grado de transparencia sobre el fondo.

ClipToPath

A diferencia de ClipToRectangle o Clip, el método ClipToPath permite definir el área irregular que será visible para cualquier posterior dibujado sobre el contexto gráfico (ClipToRectangle y Clip proporcionan áreas regulares: rectángulos o cuadrados).

Su aplicación en PDFGraphics es la misma que podrías esperar cuando se utiliza en combinación con el contexto gráfico normal proporcionado por la clase Graphics.

Por ejemplo, si bien el siguiente fragmento de código dibuja un círculo, verás en la imagen del resultado que sólo se dibuja en el área delimitada por el path definido mediante ClipToPath (un triángulo).

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

// Clip to a GraphicsPath
// Path is a triangle
Var p As New GraphicsPath
p.MoveToPoint(0, 0) // Start location
p.AddLineToPoint(20, 44)
p.AddLineToPoint(40, 0)
p.AddLineToPoint(0, 0)

g.SaveState
g.DrawingColor = Color.Red
g.ClipToPath(p)
g.FillOval(0, 0, 50, 50)
g.RestoreState

Var f As FolderItem = SpecialFolder.Desktop.Child("Cliptopath.pdf")
d.Save(f)

Clip: nuevos contextos gráficos

A diferencia de ClipToRectangle y ClipToPath, el método Clip es mucho más potente dado que si bien delimita el área de dibujo, la principal diferencia en este caso es que nos devuelve un sub-contexto gráfico completo. Es decir, podemos modificar sobre el nuevo sub-contexto cualquiera de las propiedades soportadas con PDFGraphics, así como invocar sus métodos.

En este sentido hay que tener en cuenta que todas las coordenadas de dibujado que utilicemos sobre el nuevo contexto gráfico creado se aplicarán sobre la esquina superior izquierda del Clip y no del contexto gráfico padre que lo contiene. Así, si utilizamos el siguiente código de ejemplo:

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

g.FontSize = 40
g.DrawText "Hello…", 40, 100

// Getting a new graphics context via Clip
// We change the Font and the 
// drawing color

Var g1 As Graphics = g.Clip(40,130,170,50)
g1.FontName = "Times"
g1.DrawingColor = Color.Red
g1.DrawText "…World!",0,0

// Back To drawing on the main Graphics context. 
// It Is Not affected by the changes made in the graphics subcontext from Clip.

g.DrawText "(Back to Main Graphics context)", 40, 240

Observamos como la línea g1.DrawText "…World!",0,0 pasa como coordenadas para X e Y los valores 0,0. Esto es, la esquina superior izquierda del Clip creado, mientras que serían las coordenadas 40,130 en valores absolutos si se estuviese dibujando sobre el contexto principal.

El PDF generado como resultado de ejecutar el anterior código sería el siguiente:

Por supuesto, se pueden anidar tantos contextos gráficos o Clips como consideres necesarios. Por ejemplo, puedes crear un nuevo contexto gráfico con Clip a partir de un sub-contexto gráfico creado anteriormente.

DrawObject

Por último, también se ha añadido a PDFGraphics la capacidad de dibujar cualquiera de los objetos correspondientes a la clase Object2D, así como Group2D:

Por ejemplo, el siguiente fragmento de código:

Var c As New CurveShape
c.ControlX(0) = 120
c.ControlY(0) = -40
c.Order = 1
c.X = 10
c.Y = 100
c.X2 = 250
c.Y2 = 100

Var fx As New FigureShape
fx.AddLine(0, 100, 50, 0)
fx.AddLine(50, 0, -50, 0)
fx.Border = 100  // opaque border
fx.BorderColor = &cFF0000  // red border
fx.FillColor = &cFFFF00   // yellow interior

Var d As New PDFDocument

Var g As Graphics = d.Graphics
g.DrawObject(c, c.x, c.y)
g.DrawObject(fx,100,100)

d.Save(SpecialFolder.Desktop.Child("CurveShape.PDF"))

Producirá el documento PDF que puedes ver en la imagen superior.