iText - ¿Que es una Layer/Mascara/Capa? - ¿Como manejar capas con iText? - ¿Como agregar una Layer/Mascara/Capa sobre otra con iText?

Buenas amigos, hace un tiempo comenzamos hablar de iText hoy continuaremos con esta saga. En el día de hoy veremos en profundidad Layers/Mascaras/Capas con iText.

¿Que es una Layer/Mascara/Capa?

Para comenzar a explicar las Layers/Mascaras/Capas tenemos entender cual es su significado. El Layers/Mascaras/Capas es básicamente es una porción de "algo" que sumando varias porciones generamos la materialización de ese "algo" y a su ves las porciones están superpuestas unas con otras (una sobre otra).

Ejemplo: 

Piel: Compuesta por varias secciones. (epidermis, dermis, hipodermis, etc.)

Pintura: Para darle una cobertura completa se utilizan varias manos de pinturas o apliques.

iText - ¿Como manejar capas con iText?

Para poder superponer capas con iText tenemos que acceder al contenido directamente. Cuando nosotros agregamos contenido a una pagina con el método "add" de la clase "Document" el iText escribe una sintaxis PDF a un ByteBuffer y este es encerrado en un objeto "PdfContentByte". Cuando una pagina esta cargada, estos buffer son agregados al archivo PDF en un orden especifico. Cada buffer puede ser visto como una capa diferente.

Cuando una pagina es inicializada, dos objetos PdfContentByte son creados para la construcción básica de bloques:

Un PdfContentByte para objetos de tipo texto: El contenido de Chunks, Phrases, Paragraphs, etc. 

Un PdfContentByte para gráficos: El fondo de un Chunk, Images, el borde de un PdfPCell y así sucesivamente.

Mirando la imagen de arriba, tenemos que explicar que con iText no podemos acceder al PdfContentBytes de la capa 2 y 3 directamente, estas dos capas son manejadas por iText internamente.

Las otras 2 capas (capa 1 y capa 4), podemos acceder al PdfContentByte directamente con los metodos:
.getDirectContent(): Trae la capa superior.
.getDirectContentUnder(): Trae la capa inferior.

En terminologías de iText, agregar contenido a de capas extras es llamado "escribir directamente el contenido", o acceso de bajo nivel ya que el accede a las operaciones a bajo nivel.

iText -  ¿Como agregar una Layer/Mascara/Capa sobre otra con iText?

Obviamente como agregar una mascara con iText, es una manera de explicar: como agregar texto sobre otro texto en iText, como agregar texto sobre una imagen con iText, como agregar texto sobre un logo con iText, como agregar una imagen sobre otra imagen con iText, etc!

Sabiendo el uso del PdfContentByte ahora veremos un ejemplo practico.

Para agregar una capa sobre otra tenemos que hacer algo que hasta el momento no utilizábamos, tenes que obtener un objeto del tipo PdfWriter, y no solamente su invocación en memoria.

Primero definimos el tipo de documento:

Document documento = new Document();

Por defecto al invocarlo sin indicación sera del tipo A4. Despues generamos una instancia de un PdfWriter.

PdfWriter writer=PdfWriter.getInstance(documento, new FileOutputStream("EjemploCapas.pdf"));

Abrimos el documento:

documento.open();

Ahora mediante el método getDirectContent del objeto PdfWrite obtenemos el PdfContentByte

PdfContentByte over = writer.getDirectContent();

Guardamos el estado actual del PdfContentByte mediante el metodo saveState().

write.saveState();

Obtenemos un BaseFont, para asignar el tamaño y tipo de letra.

BaseFont bf = BaseFont.createFont();

Le decimos al PdfContentByte que comenzaremos a escribir el texto mediante el método beginText() y seteado las características del texto mediante el método setFontAndSize().

over.setFontAndSize(bf, 36);

Asignamos una posición donde se comenzara a escribir mediante el método setTextMatrix().

over.setTextMatrix((float)1, (float)0, (float) 0,2, 50, 120);

Explicación rápida de estas propiedades:

1 parámetro = Estira el ancho.
2 parámetro = Elevación.
3 parámetro = Estira la parte superior hacia la izquierda (efecto cursiva).
4 parámetro = Estira el alto.
5 parámetro = X Desde izquierda a derecha.
6 parámetro = Y Desde abajo hacia arriba.

Escribimos el texto utilizando el metodo showText().

over.showText("El mejor lugar para aprender Java");

Cerramos el texto endText()

over.endText();

Restauramos el estado restoreState()

over.restoreState();

Finalmente cerramos el documento

documento.close();

Nota: Tenemos que tener en cuenta 2 cosas, primero tenemos que agregar un PdfContentByte por cada capa que escribiremos.

La segunda cosa a tener en cuenta es que tenemos que escribir el código dentro de un bloque try y catch para atrapar posibles errores en la generación del documento.

Resultado:

Código completo:

package com.java.white.box.itext.images.layers;

import java.io.FileOutputStream;

import com.itextpdf.text.Document;
import com.itextpdf.text.DocumentException;
import com.itextpdf.text.pdf.BaseFont;
import com.itextpdf.text.pdf.PdfContentByte;
import com.itextpdf.text.pdf.PdfWriter;

/**
 * <p>El lado oscuro de java ejemplo de capas</p>
 * @author nicolas conde
 *
 */
public class Main {

 public static void main(String[] args) {

  // Por defecto es A4
  Document documento = new Document();
  try {
   // Obtenemos una instancia de un objeto PDFWriter
   PdfWriter writer = PdfWriter.getInstance(documento, new FileOutputStream("EjemploCapas.pdf"));
   documento.open();
  
     PdfContentByte over = writer.getDirectContent();
     over.saveState();
     BaseFont bf = BaseFont.createFont();
     over.beginText();
     over.setFontAndSize(bf, 36);
     
     over.setTextMatrix((float)1, (float)0, (float) 0,2, 50, 120);
     over.showText("El mejor lugar para aprender Java");
     over.endText();
     over.restoreState();

     PdfContentByte ove2r = writer.getDirectContent();
     ove2r.saveState();     

     ove2r.beginText();
     ove2r.setFontAndSize(bf, 36);
     ove2r.setTextMatrix((float)1, (float)0, (float) 0,2, 50, 100);
     ove2r.showText("El lado oscuro de Java");
     ove2r.endText();
     ove2r.restoreState();
 
   documento.close();

  } catch (DocumentException ex) {
   // Atrapamos excepciones concernientes al documento.
  } catch (java.io.IOException ex) {
   // Atrapamos excepciones concernientes al I/O.
  }

 }
}

Espero que les sirva a muchos y mas adelante explicaremos en profundidad la clase  PdfContentByte.

Saludos!