Tutorial: Añadir un Índice de Contenidos a PDFDocument

Desde su aparición inicial en Xojo 2020r1, una de las características más solicitadas para PDFDocument ha sido la capacidad de crear un Índice de Contenidos; y ahora es posible a partir de Xojo 2021r3… ¡y de un modo realmente sencillo! Continúa leyendo y te mostraré cómo.

Cuando pensamos en las entradas de un Índice de Contenidos (TOC), podemos ver claramente que se trata de una jerarquía en forma de árbol, donde cada una de las ramas indica un nivel inferior que cuelga sobre el nodo padre. Por tanto, si echamos un vistazo a esta imagen:

Podemos ver cómo las entradas “First Page” y “Second Page” del TOC están en un nivel raíz correspondientes a, bueno, la primera y segunda páginas del documento, respectivamente; mientras que tanto “First Section” y “Second Section” están un nivel por debajo, colgando del nodo “First Page”, y “First Sub-Section” está en un tercer nivel en la jerarquía, colgando en este caso de la entrada “First Section” de la entrada “First Page”.

¿Cómo podemos crear este tipo de jerarquía para un Índice de Contenidos (TOC) en una instancia de PDFDocument? La respuesta: usando la clase PDFTOCEntry en combinación el método PDFDocumento.AddTOCEntry.

El Constructor de PDFTOCEntry toma un total de cuatro parámetros:

• PageNumber As Integer. Este es el número de página de la instancia PDFDocument asociada con la entrada en el TOC. Las páginas PDF empiezan en 1.
• Title As String. El texto que se mostrará como el título de la entrada TOC en el visor PDF.
• X As Integer. La coordenada X a la que “saltará” el visor PDF para la página asociada cuando el usuario haga clic en la entrada del TOC.
• Y As Integer. La coordenada Y a la que “saltará” el visor PDF para la página asociada cuando el usuario haga clic en la entrada del TOC.

Volveremos un poco más adelante para ver cuál es el comportamiento que podemos esperar en el “salto” a las coordenadas X / Y por parte del visor PDF.

Por tanto, para crear nuestra primera entrada raíz del TOC, correspondiente a la primera página de la instancia PDFDocument, todo lo que necesitamos es:

Var te As New PDFTOCEntry(1,"First Page",0,40)

Ahora, la entrada “First Section” implica que queremos añadir un Marcador (o entrada al TOC) a la instancia PDFDocument de modo que, cuando el usuario haga clic sobre ella, salte a las coordenadas X/Y asignadas en la misma página. De modo que hemos de crear una nueva instancia para ello:

Var te1 As New PDFTOCEntry(1,"First Section",100,100)

Y lo mismo ocurre en el caso de la primera sub-sección que colgará de la entrada “First Section”:

Var te1a As New PDFTOCEntry(1,"First Sub-Section", 0, 100)

Hasta ahora tenemos tres instancias PDFTOCEntry, pero aún no hemos definido la jerarquía entre ellas. Para ello utilizaremos el método PDFTOCEntry.AddEntry. Por ejemplo, la siguiente línea de código añadirá la instancia te1a como un sub-nodo de la instancia te1 (es decir, “First Sub-Section” como nodo de “First Section”):

te1.AddEntry te1a

Y ahora podemos añadir la instancia te1 como un sub-nodo de la instancia te (es decir, “First Section” será un sub-nodo de “First Page”):

te.AddEntry te1

Por tanto, para añadir una nueva sección con el nombre “Second Section” también como sub-nodo del nodo raíz “First Page”, sólo tendremos que escribir las siguientes dos líneas de código:

Var te2 As New PDFTOCEntry(1,"Second Section", 30,30)
te.AddEntry te2

Fijo que ya pillas la idea, de modo que estoy convencido de que sabrías como crear las instancias requeridas y la jerarquía asociada para las entradas “Second Page” y “First Section” para la segunda página que se hubiese añadido al documento PDF:

Var teG2 As New PDFTOCEntry(2,"Second Page",0,40)
Var teg2a As New PDFTOCEntry(2, "First Section", 100, 100)

teG2.AddEntry teG2a

Por último, todo lo que necesitamos es añadir las instancias raíz correspondientes a la jerarquía del TOC (es decir, te y teG2) a la instancia de PDFDocument. Imaginemos que nuestra instancia PDFDocument está almacenada en la variable d. Estas dos líneas de código completarán el trabajo:

d.AddTOCEntry te
d.AddTOCEntry teG2

Entradas del TOC y comportamiento del Visor PDF

Las aplicaciones para visualizar archivos PDF tienen sus propias reglas sobre cómo y cuándo “saltar” a las coordenadas X/y asociadas con las entradas del TOC. De forma abreviada:

• Si las coordenadas de destino para la página de destino ya son visibles en el área del visor, entonces no verás ningún tipo de movimiento en las páginas. Después de todo, ya estarías viendo los contenidos de la página a las que estuviesen apuntando las coordenadas X/Y. Por ejemplo, este puede ser el caso cuando se configura el visor PDF para que muestre las dos páginas del PDF al mismo tiempo en la vista.
• Si las coordenadas de destino para la página de destino se encuentran fuera del área mostrada por la vista, entonces el visor de PDF saltará a las coordenadas indicadas de modo que sus contenidos sean visibles. El comportamiento que se obtenga en este caso dependerá del nivel de Zoom o ampliación que se esté usando para mostrar las páginas del PDF.Es decir, es probable que veas cómo el visor de PDF cambia para mostrar la segunda página cuando se hace clic sobre la entrada “Second Page” en el TOC, pero no cuando se hace clic en las entradas “First Section” or “First Sub-Section” para la primera página del documento si dicha página ya está en el área de visualización y el nivel de ampliación está configurado como “Ajustar contenidos a Ventana”.

Conclusión

Como hemos visto, ahora es realmente fácil crear un Índice de Contenidos para tus documentos PDF creados con Xojo, añadiendo tantas entradas como requiera la estructura de tus PDF con el objeto de proporcionar una mejor experiencia y navegación por el contenido del documento.